Skip to main content
n8n is a workflow automation platform for connecting apps, APIs, and AI steps. n8n’s main AI workflow path uses the AI Agent node with connected chat model, memory, and tool sub-nodes. The HoneyHive n8n shipper exports those workflow executions from n8n’s Postgres execution history to HoneyHive. This gives you HoneyHive traces for AI Agent runs, model calls, tool calls, node inputs, node outputs, and workflow metadata without adding HTTP Request nodes after every step.
The shipper works only with self-hosted n8n because it reads n8n’s execution database. For n8n Cloud, see Other options.

​
How n8n AI Agent runs map to HoneyHive

n8n’s current AI Agent node runs as a Tools Agent. In n8n’s own quickstart, you build an AI chat workflow with: The shipper reads the persisted runData for each completed execution and maps it to HoneyHive events:
n8n execution dataHoneyHive event
Workflow execution rootchain
AI Agent nodechain
Chat model sub-node, such as OpenAI Chat Modelmodel
Memory sub-node, such as Simple Memorychain
Tool sub-node, such as Calculator, HTTP Request, or app toolstool
Standard n8n nodes, such as Set or Codechain
For current AI Agent workflows, n8n stores chat model calls as ai_languageModel sub-runs, memory calls as ai_memory sub-runs, and tool calls as ai_tool sub-runs. The shipper preserves that hierarchy, so model, memory, and tool spans appear under the AI Agent span in HoneyHive.

​
Prerequisites

  • Self-hosted n8n with PostgreSQL execution storage
  • Read access to n8n’s Postgres database
  • A HoneyHive project and API key from Settings > Project > API Keys

​
Install the shipper

Clone the shipper and install it with uv: 
git clone https://github.com/honeyhiveai/n8n-honeyhive-shipper
cd n8n-honeyhive-shipper
uv sync

​
Configure

Set the required environment variables: 
export HONEYHIVE_API_KEY=<your-honeyhive-api-key>
export HONEYHIVE_API_URL=<your-honeyhive-data-plane-host>
export PG_DSN=postgresql://user:password@postgres-host:5432/n8n

# Match your n8n install. Default Docker + Postgres uses unprefixed tables:
export DB_TABLE_PREFIX=
# Some installs prefix tables, for example:
# export DB_TABLE_PREFIX=n8n_
HONEYHIVE_API_URL is your HoneyHive data plane API base URL, for example https://api.dp1.us.prod.honeyhive.ai. The shipper appends /opentelemetry/v1/traces automatically. You can also omit PG_DSN and use n8n-style Postgres variables: 
export DB_POSTGRESDB_HOST=postgres-host
export DB_POSTGRESDB_PORT=5432
export DB_POSTGRESDB_DATABASE=n8n
export DB_POSTGRESDB_USER=n8n
export DB_POSTGRESDB_PASSWORD=<password>
export DB_TABLE_PREFIX=
Useful optional settings:
VariableDefaultPurpose
DRY_RUNtrueMap executions without exporting to HoneyHive
CHECKPOINT_FILE.shipper_checkpointStores the last processed execution ID
FILTER_AI_ONLYfalseExport AI-related spans plus required context
FILTER_WORKFLOW_IDSnoneComma-separated workflow ID allowlist
TRUNCATE_FIELD_LEN0Truncate large input/output strings. 0 disables truncation
OTEL_EXPORTER_OTLP_ENDPOINTderived from HONEYHIVE_API_URLFull OTLP traces URL override

​
Run

Start with a dry run: 
uv run n8n-honeyhive-shipper shipper --dry-run --limit 5 --debug
Export a small batch: 
uv run n8n-honeyhive-shipper shipper --no-dry-run --limit 1
Then run incrementally on a schedule: 
uv run n8n-honeyhive-shipper shipper --no-dry-run
The shipper updates CHECKPOINT_FILE after successful non-dry-run exports, so later runs resume from the last processed execution ID.

​
Example workflow: AI Agent with a tool

In a local self-hosted n8n test, the prompt Use the calculator tool to compute 17 * 23 produced:
  • AI Agent output: 391
  • Calculator tool input: 17 * 23
  • Two OpenAI Chat Model sub-runs: one for the tool call and one for the final answer
  • One HoneyHive session with 6 spans under the session root: workflow root, trigger, AI Agent, Calculator tool, and two model calls

​
Verify in HoneyHive

1

Run the workflow

Execute the workflow from the n8n UI or workflow execute API. Confirm the execution is stored in n8n’s Postgres database.
2

Run the shipper

Start with a dry run, then export a small batch with --no-dry-run.
3

Check shipper-exported spans

In Traces, search for the workflow name or a node name from the execution.Shipper spans include service.name = n8n-honeyhive-shipper and n8n metadata such as n8n.metadata.n8n.execution.id and n8n.workflow.id. HoneyHive may store the session under its own session ID, so use the n8n execution ID as metadata when cross-checking against n8n’s database. AI Agent workflows should show the AI Agent span with model and tool spans beneath it.
HoneyHive trace tree for an n8n AI Agent run, showing OpenAI Chat Model and Calculator spans nested under the AI Agent span

​
Where n8n stores runData

On self-hosted n8n, finished executions are persisted in the database:
TableKey columnsContents
execution_entityid, workflowId, status, startedAt, stoppedAt, modeExecution metadata
execution_dataexecutionId, workflowData, dataStatic workflow snapshot plus runtime payload
The data column holds resultData.runData: a map of node name to execution runs. Each run includes startTime, executionTime, executionStatus, and per-item JSON under channels such as main, ai_languageModel, ai_memory, or ai_tool. The data value may be flatted pointer-compressed JSON, while workflowData is usually plain JSON.

​
Operational notes

ConcernDetail
LatencyNear-real-time poll or backfill batch. Export is not inline with workflow execution
Re-exportA checkpoint file tracks processed executions. Keep the checkpoint on durable storage to avoid duplicate exports
Queue modeWorkers write to the same execution tables. Run the shipper after executions are persisted
AI Agent variantsCurrent AI Agent nodes run as Tools Agents. Older Conversational Agent functionality was removed by n8n in February 2025
The shipper reads execution runData, which may include PII, API responses, or resolved values from workflow nodes. Use a read-only DB role, restrict workflow scope with FILTER_WORKFLOW_IDS when possible, and review redaction requirements before exporting production data.

​
Troubleshooting

SymptomFix
No shipper-exported spans in HoneyHiveConfirm HONEYHIVE_API_KEY, HONEYHIVE_API_URL, and PG_DSN point to the expected HoneyHive project and n8n database. Run a dry run first, then export with --no-dry-run
Shipper missing executionsConfirm the shipper points at the same Postgres DSN as the n8n instance that ran the workflow. Check DB_TABLE_PREFIX, workflow filters, and .shipper_checkpoint
AI Agent spans have no model/tool childrenConfirm the workflow uses connected AI sub-nodes such as ai_languageModel and ai_tool, and that the execution completed before the shipper ran
Flatted parse errorsexecution_data.data is often pointer-compressed. Use a flatted decoder, not plain JSON.parse

​
Other options

  • n8n Cloud: The shipper requires database access, so it does not work with n8n Cloud. For Cloud workflows, log a small number of summary events with the HoneyHive Events API, or instrument the application that triggers n8n.

Tracing via API

Full REST logging guide for sessions, model events, and batches

TrueFoundry Integration

Automatic OTLP trace export from an AI gateway

Tracing Introduction

Sessions, event types, and trace hierarchy

Enrich Your Traces

Add metadata, user properties, and feedback

​
Resources