Observability for n8n with Opik

n8n is a powerful workflow automation platform that allows you to connect various services and automate tasks through a visual interface. With the n8n-observability package, you can automatically trace workflow executions and node operations using OpenTelemetry.

Features

🔍 Automatic tracing of workflow executions and individual node operations
📊 Standard OpenTelemetry instrumentation using the official Node.js SDK
🎯 Zero-code setup via n8n's hook system
🔌 OTLP compatible - works with Opik's OpenTelemetry endpoint
⚙️ Configurable I/O capture, node filtering, and more

Account Setup

Comet provides a hosted version of the Opik platform. Simply create an account and grab your API Key.

You can also run the Opik platform locally, see the installation guide for more information.

Quick Start with Docker

The fastest way to get started is with Docker Compose:

Bash

# Clone and navigate to the example
git clone https://github.com/comet-ml/n8n-observability.git
cd n8n-observability/examples/docker-compose

# Set your Opik API key (get one free at https://www.comet.com/signup)
export OPIK_API_KEY=your_api_key_here

# Build and run
docker-compose up --build

Open http://localhost:5678, create a workflow, and see traces in your Opik dashboard!

Setup Options

Docker (Recommended)

Create a custom Dockerfile that installs the n8n-observability package globally:

Docker

FROM n8nio/n8n:latest

USER root
RUN npm install -g n8n-observability

ENV EXTERNAL_HOOK_FILES=/usr/local/lib/node_modules/n8n-observability/dist/hooks.cjs

USER node

Then configure your docker-compose.yml with OTLP settings:

YAML

services:
  n8n:
    build: .
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "https://www.comet.com/opik/api/v1/private/otel"
      OTEL_EXPORTER_OTLP_HEADERS: "Authorization=${OPIK_API_KEY},Comet-Workspace=default"
      N8N_OTEL_SERVICE_NAME: "my-n8n"
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "5678:5678"

volumes:
  n8n_data:

To log the traces to a specific project, you can add the projectName parameter to the OTEL_EXPORTER_OTLP_HEADERS environment variable:

YAML

OTEL_EXPORTER_OTLP_HEADERS: "Authorization=${OPIK_API_KEY},Comet-Workspace=default,projectName=my-n8n-project"

YAML

services:
  n8n:
    build: .
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "https://<comet-deployment-url>/opik/api/v1/private/otel"
      OTEL_EXPORTER_OTLP_HEADERS: "Authorization=${OPIK_API_KEY},Comet-Workspace=default"
      N8N_OTEL_SERVICE_NAME: "my-n8n"
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "5678:5678"

volumes:
  n8n_data:

YAML

services:
  n8n:
    build: .
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:5173/api/v1/private/otel"
      OTEL_EXPORTER_OTLP_HEADERS: "projectName=my-n8n-project"
      N8N_OTEL_SERVICE_NAME: "my-n8n"
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "5678:5678"

volumes:
  n8n_data:

Bare Metal / npm

If you're running n8n directly on your machine:

Bash

# Install globally
npm install -g n8n-observability

Then set the required environment variables:

wordWrap

export OTEL_EXPORTER_OTLP_ENDPOINT=https://www.comet.com/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
export N8N_OTEL_SERVICE_NAME=my-n8n
export EXTERNAL_HOOK_FILES=$(npm root -g)/n8n-observability/dist/hooks.cjs

# Start n8n
n8n start

wordWrap

export OTEL_EXPORTER_OTLP_ENDPOINT=https://<comet-deployment-url>/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
export N8N_OTEL_SERVICE_NAME=my-n8n
export EXTERNAL_HOOK_FILES=$(npm root -g)/n8n-observability/dist/hooks.cjs

# Start n8n
n8n start

Bash

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5173/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='projectName=my-n8n-project'
export N8N_OTEL_SERVICE_NAME=my-n8n
export EXTERNAL_HOOK_FILES=$(npm root -g)/n8n-observability/dist/hooks.cjs

# Start n8n
n8n start

Configuration

The following environment variables can be used to configure the integration:

Variable	Purpose	Default
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP exporter endpoint	—
`OTEL_EXPORTER_OTLP_HEADERS`	OTLP headers (e.g., auth tokens)	—
`N8N_OTEL_SERVICE_NAME`	Service name for telemetry	`n8n`
`N8N_OTEL_NODE_INCLUDE`	Only trace listed nodes (comma-separated)	—
`N8N_OTEL_NODE_EXCLUDE`	Exclude listed nodes (comma-separated)	—
`N8N_OTEL_CAPTURE_INPUT`	Capture node input data	`true`
`N8N_OTEL_CAPTURE_OUTPUT`	Capture node output data	`true`
`N8N_OTEL_AUTO_INSTRUMENT`	Enable HTTP/Express instrumentation	`false`
`N8N_OTEL_METRICS`	Enable metrics collection	`false`
`N8N_OTEL_DEBUG`	Enable debug logging	`false`
`EXTERNAL_HOOK_FILES`	Path to hooks.cjs (set automatically)	—

Node Filtering

You can filter which nodes are traced using environment variables:

Bash

# Only trace specific nodes
export N8N_OTEL_NODE_INCLUDE="OpenAI,HTTP Request"

# Exclude noisy nodes
export N8N_OTEL_NODE_EXCLUDE="Wait,Set"

# Disable I/O capture for privacy
export N8N_OTEL_CAPTURE_INPUT=false
export N8N_OTEL_CAPTURE_OUTPUT=false

What Gets Tracked

Workflow Spans

Each workflow execution creates a span with the following attributes:

n8n.workflow.id - Workflow ID
n8n.workflow.name - Workflow name
n8n.span.type - "workflow"

Node Spans

Each node operation creates a span with:

n8n.node.type - Node type (e.g., n8n-nodes-base.httpRequest)
n8n.node.name - Node name
n8n.span.type - "llm", "prompt", "evaluation", or undefined
n8n.node.input - JSON input (if capture enabled)
n8n.node.output - JSON output (if capture enabled)
gen_ai.system - AI provider (e.g., openai, anthropic)
gen_ai.request.model - Model name (e.g., gpt-4)

Verify Installation

Check that the package is installed correctly:

Bash

node -e "console.log(require.resolve('n8n-observability/hooks'))"

On startup, you should see logs similar to:

[otel-setup] OpenTelemetry initialized: my-n8n (OTLP export enabled, n8n spans only)
[n8n-observability] observability ready and patches applied

Further Improvements

If you would like to see us improve this integration, please open a new feature request on GitHub.

For issues specific to the n8n-observability package, visit the n8n-observability repository.