Cloudflare Workers OpenTelemetry Instrumentation

This document explains how to instrument Cloudflare Workers with OpenTelemetry using Community or Official methods and send traces to SigNoz.

Prerequisites

You will need the following in place before moving on to the next step:

• A Cloudflare account (Paid plan or higher in case of Official)
• Wrangler, the CLI tool for Cloudflare.

Send traces to SigNoz

{
  "observability": {
    "traces": {
      "enabled": true,
      "destinations": ["signoz-traces"]
    }
  }
}

npm i @microlabs/otel-cf-workers

compatibility_flags = [ "nodejs_compat" ]

import { instrument, ResolveConfigFn } from '@microlabs/otel-cf-workers'

const handler = {
    async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
        // your cloudflare worker code
    },
}

const config: ResolveConfigFn = (env: Env, _trigger) => {
    return {
        exporter: {
            url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
            headers: { 'signoz-ingestion-key': '<your-ingestion-key>' },
        },
        service: { name: '<service-name>' },
    }
}

export default instrument(handler, config)

npm run deploy

Validate

After deploying your Worker, verify that traces are being sent to SigNoz:

1. Access SigNoz UI and generate traces: Navigate to the Traces tab in your SigNoz dashboard and send requests to your Cloudflare Worker to generate trace data

2. View traces: Within a few minutes, traces from your Worker should appear in the Traces view

Expected behavior: You should see traces with attributes like worker_name, script_name, and any custom fields from your Worker code.

You can click on a particular TraceID in the Traces view to get the detailed view of the Cloudflare Worker as shown below.

Troubleshooting

Traces not appearing in SigNoz

Symptom: No traces visible in SigNoz UI after deploying the Worker.

Things to investigate:

1. Check destination status

   • In your Cloudflare dashboard under Workers Observability > Destinations, verify the status:
     • Last: n minutes ago - Data is being delivered successfully
     • Never run - No data has been delivered yet (check if your Worker is receiving traffic or review sampling rates)
     • Error - Delivery failed (verify OTLP endpoint and authentication headers)

2. Incorrect OTLP endpoint

   • Wrong region or endpoint format
   • Verify the endpoint matches your SigNoz setup: SigNoz Ingestion Docs

3. Missing or invalid ingestion key

   • Incorrect or missing signoz-ingestion-key header
   • Copy the correct ingestion key from SigNoz settings and update the destination header

4. Worker not receiving traffic

   • No requests to the Worker means no traces generated
   • Send test requests to your Worker endpoint

5. Sampling rate too low

   • Low head_sampling_rate means fewer traces are sent
   • Increase the sampling rate in your wrangler.jsonc configuration

6. Network/connectivity issues

   • Firewall or network blocking OTLP traffic
   • Verify your OTel collector is accessible from Cloudflare Workers

Verification: Check the destination status in Cloudflare dashboard (Workers Observability > Destinations) to see delivery status and any errors.

Next steps

• Set up logs: Send Cloudflare Worker logs to SigNoz by following the Cloudflare logs guide
• Create dashboards: Build custom dashboards to visualize your Worker performance
• Set up alerts: Configure alerts based on trace data to monitor Worker health
• Analyze traces: Use the Trace Explorer to debug issues and optimize performance