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:

$
# 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:

1
FROM n8nio/n8n:latest
2
3
USER root
4
RUN npm install -g n8n-observability
5
6
ENV EXTERNAL_HOOK_FILES=/usr/local/lib/node_modules/n8n-observability/dist/hooks.cjs
7
8
USER node

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

1
services:
2
  n8n:
3
    build: .
4
    environment:
5
      OTEL_EXPORTER_OTLP_ENDPOINT: "https://www.comet.com/opik/api/v1/private/otel"
6
      OTEL_EXPORTER_OTLP_HEADERS: "Authorization=${OPIK_API_KEY},Comet-Workspace=default"
7
      N8N_OTEL_SERVICE_NAME: "my-n8n"
8
    volumes:
9
      - n8n_data:/home/node/.n8n
10
    ports:
11
      - "5678:5678"
12
13
volumes:
14
  n8n_data:

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

Bare Metal / npm

If you’re running n8n directly on your machine:

$
# Install globally
$
npm install -g n8n-observability

Then set the required environment variables:

$
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

Configuration

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

Node Filtering

You can filter which nodes are traced using environment variables:

$
# 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:

$
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.