Overview
This guide walks you through setting up monitoring and observability for n8n Cloud using OpenTelemetry and exporting traces to SigNoz. With this integration, you can observe and track various metrics for your n8n workflow executions.
Monitoring n8n cloud workflows with telemetry ensures full observability across your executions. By leveraging SigNoz, you can analyze traces in unified dashboards, configure alerts, and gain actionable insights to continuously improve reliability, responsiveness, and user experience.
Prerequisites
- A SigNoz Cloud account with an active ingestion key or Self Hosted SigNoz instance
- Docker and Docker Compose installed
- An n8n Cloud account and API key. You can get the API key from
<YOUR_N8N_INSTANCE_URL>.n8n.cloud/settings/api
Monitoring n8n Cloud
This setup uses the n8n-opentelemetry execution poller - a lightweight service that polls n8n's API for workflow executions and exports telemetry data to SigNoz via OpenTelemetry.
Step 1: Clone the Repository
Clone the n8n-opentelemetry repository to your local machine:
git clone https://github.com/SigNoz/n8n-opentelemetry.git
cd n8n-opentelemetry
Step 2: Configure Environment Variables
Copy the example environment file and create the data directory:
cp .env.example .env
mkdir -p ./data
Edit the .env file with your configuration:
# Required: Your n8n instance URL (no trailing slash)
N8N_HOST=https://your-instance.n8n.cloud
# Required: n8n API key from Settings → API
N8N_API_KEY=n8n_api_xxxxxxxxxxxxx
# Required: SigNoz ingestion endpoint
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.signoz.cloud:443/v1/traces
# Required: Your SigNoz ingestion key
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<your-ingestion-key>
# Optional: Service name in traces (default: n8n-cloud)
OTEL_SERVICE_NAME=n8n-cloud
# Optional: Poll interval in seconds (default: 60)
POLL_INTERVAL_SECONDS=60
# Optional: Retry attempts for failed API calls (default: 5)
MAX_RETRIES=5
<region>: Your SigNoz Cloud region<your-ingestion-key>: Your SigNoz ingestion key
Step 3: Launch with Docker
Start the poller service using Docker Compose:
docker-compose up -d
View the logs to verify it's running correctly:
docker-compose logs -f
You should see output indicating successful polling and trace exports.
To stop the service:
docker-compose down
The poller maintains state in ./data/last_execution_id.txt to track the last processed execution. This file persists across container restarts, ensuring no duplicate processing and no missed executions.
Alternative: Local Development Setup
If you prefer to run without Docker:
# Create virtual environment
python -m venv .venv
# Activate virtual environment
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure .env as shown in Step 2
cp .env.example .env
# Run the poller
python poller.py
View Traces in SigNoz
Your n8n usage should now automatically emit traces.
You should be able to view traces in SigNoz Cloud under the traces tab:
When you click on a trace in SigNoz, you'll see a detailed view of the trace, including all associated spans, along with their events and attributes.
Troubleshooting
If you don't see your telemetry data:
- Verify network connectivity - Ensure your application can reach SigNoz Cloud endpoints
- Check ingestion key - Verify your SigNoz ingestion key is correct
- Wait for data - OpenTelemetry batches data before sending, so wait 10-30 seconds after making API calls
- Try a console exporter — Enable a console exporter locally to confirm that your application is generating telemetry data before it’s sent to SigNoz
Next Steps
Check out the n8n dashboard template for specialized visualizations of your n8n workflow performance. The dashboard includes pre-built charts for workflow monitoring, along with import instructions to get started quickly.
Setup OpenTelemetry Collector (Optional)
What is the OpenTelemetry Collector?
Think of the OTel Collector as a middleman between your app and SigNoz. Instead of your application sending data directly to SigNoz, it sends everything to the Collector first, which then forwards it along.
Why use it?
- Cleaning up data — Filter out noisy traces you don't care about, or remove sensitive info before it leaves your servers.
- Keeping your app lightweight — Let the Collector handle batching, retries, and compression instead of your application code.
- Adding context automatically — The Collector can tag your data with useful info like which Kubernetes pod or cloud region it came from.
- Future flexibility — Want to send data to multiple backends later? The Collector makes that easy without changing your app.
See Switch from direct export to Collector for step-by-step instructions to convert your setup.
For more details, see Why use the OpenTelemetry Collector? and the Collector configuration guide.
Additional resources:
- Set up alerts for high latency or error rates
- Learn more about querying traces
- Explore log correlation
