n8n

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 data	HoneyHive event
Workflow execution root	`chain`
`AI Agent` node	`chain`
Chat model sub-node, such as `OpenAI Chat Model`	`model`
Memory sub-node, such as `Simple Memory`	`chain`
Tool sub-node, such as `Calculator`, `HTTP Request`, or app tools	`tool`
Standard n8n nodes, such as `Set` or `Code`	`chain`

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:

Variable	Default	Purpose
`DRY_RUN`	`true`	Map executions without exporting to HoneyHive
`CHECKPOINT_FILE`	`.shipper_checkpoint`	Stores the last processed execution ID
`FILTER_AI_ONLY`	`false`	Export AI-related spans plus required context
`FILTER_WORKFLOW_IDS`	none	Comma-separated workflow ID allowlist
`TRUNCATE_FIELD_LEN`	`0`	Truncate large input/output strings. `0` disables truncation
`OTEL_EXPORTER_OTLP_ENDPOINT`	derived from `HONEYHIVE_API_URL`	Full 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

Run the workflow

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

Run the shipper

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

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:

Table	Key columns	Contents
`execution_entity`	`id`, `workflowId`, `status`, `startedAt`, `stoppedAt`, `mode`	Execution metadata
`execution_data`	`executionId`, `workflowData`, `data`	Static 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

Concern	Detail
Latency	Near-real-time poll or backfill batch. Export is not inline with workflow execution
Re-export	A checkpoint file tracks processed executions. Keep the checkpoint on durable storage to avoid duplicate exports
Queue mode	Workers write to the same execution tables. Run the shipper after executions are persisted
AI Agent variants	Current 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

Symptom	Fix
No shipper-exported spans in HoneyHive	Confirm `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 executions	Confirm 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 children	Confirm 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 errors	`execution_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

Agent Frameworks & Platforms

Model Providers

AI Gateways

Coding Agents

Evaluation

How n8n AI Agent runs map to HoneyHive

Prerequisites

Install the shipper

Configure

Run

Example workflow: AI Agent with a tool

Verify in HoneyHive

Where n8n stores `runData`

Operational notes

Troubleshooting

Other options

Tracing via API

TrueFoundry Integration

Tracing Introduction

Enrich Your Traces

Resources

​How n8n AI Agent runs map to HoneyHive

​Prerequisites

​Install the shipper

​Configure

​Run

​Example workflow: AI Agent with a tool

​Verify in HoneyHive

​Where n8n stores runData

​Operational notes

​Troubleshooting

​Other options

​Related

Tracing via API

TrueFoundry Integration

Tracing Introduction

Enrich Your Traces

​Resources

How n8n AI Agent runs map to HoneyHive

Prerequisites

Install the shipper

Configure

Run

Example workflow: AI Agent with a tool

Verify in HoneyHive

Where n8n stores `runData`

Operational notes

Troubleshooting

Other options

Related

Resources