Cloudflare Trace Getting Started Guide: First Request (2026)

Getting started overview

Cloudflare Trace is an observability feature integrated within the Cloudflare Workers platform, designed to provide distributed tracing, log analysis, and metrics for serverless applications. Getting started with Cloudflare Trace primarily involves configuring an existing Cloudflare Worker or deploying a new one, then enabling and accessing the tracing data through the Cloudflare dashboard or API. It is tailored for developers working on edge applications who require insights into function execution paths and performance characteristics.

The initial setup process focuses on ensuring your Cloudflare account is active, a Worker service is deployed, and that you understand how to generate traffic to observe traces. This guide walks through the essential steps to achieve your first successful trace, providing a foundation for deeper performance monitoring and debugging within the Cloudflare ecosystem.

Quick reference table

Create an account and get keys

To begin using Cloudflare Trace, you must have an active Cloudflare account. If you do not have one, you can sign up for a free account through the Cloudflare website. Cloudflare Trace is an integral part of the Cloudflare Workers platform, which offers a free tier that includes a basic allowance for Workers, Logs, and Traces, making it accessible for initial experimentation.

Account setup

1. Sign Up for Cloudflare: Navigate to the Cloudflare homepage and complete the registration process. This typically involves providing an email address and creating a password.
2. Verify Email: Follow the instructions to verify your email address, which is a standard security measure for new accounts.
3. Access Dashboard: Once registered and verified, log in to the Cloudflare dashboard. This is your central hub for managing all Cloudflare services.

API tokens and keys

While direct API keys are not always required for enabling Trace on a Worker via the dashboard, understanding Cloudflare API tokens is crucial for programmatic interaction, such as deploying Workers with Wrangler, the Cloudflare Workers CLI, or fetching trace data directly. For the purpose of getting started with Trace, you will primarily use the Cloudflare dashboard. However, if you plan to automate deployments or integrate with CI/CD pipelines, you will need to generate an API token.

1. Generate an API Token: In the Cloudflare dashboard, go to "My Profile" > "API Tokens".
2. Create Token: Select "Create Token" and choose a template or create a custom token. For Worker deployment and management, a token with "Worker Scripts" permissions (Edit) and "Account" > "Workers R2 Storage" (Edit) might be necessary, depending on your setup. Refer to the Cloudflare API Token documentation for specific permission requirements.
3. Record Token: Copy the generated token immediately, as it will only be shown once. Store it securely.

Your first request

After setting up your Cloudflare account, the next step is to deploy a Cloudflare Worker and enable Trace. This example uses a basic "Hello World" Worker to demonstrate the process.

Deploy a Cloudflare Worker

1. Create a New Worker:
   • From the Cloudflare dashboard, navigate to "Workers & Pages" on the left sidebar.
   • Click "Create application" and then "Create Worker".
   • You can use the default "Hello World" template. Give your Worker a unique name (e.g., my-first-trace-worker).
   • Click "Deploy".
2. Access Worker Settings:
   • Once deployed, select your Worker from the "Workers & Pages" list.
   • Go to the "Settings" tab.
3. Enable Trace:
   • Under the "Observability" section, locate "Cloudflare Trace".
   • Ensure the toggle for "Trace" is enabled. This will start collecting trace data when your Worker is invoked.

Generate traffic and view trace

With your Worker deployed and Trace enabled, you can now send a request to it to generate trace data.

1. Get Worker URL: On your Worker's overview page in the Cloudflare dashboard, you'll find its unique URL (e.g., https://my-first-trace-worker.yourusername.workers.dev).
2. Send a Request:
   • Open your web browser and navigate to your Worker's URL.
   • Alternatively, use a tool like curl from your terminal:

     curl https://my-first-trace-worker.yourusername.workers.dev

   You should see the "Hello World!" response.

3. View Traces in Dashboard:
   • Return to your Worker's page in the Cloudflare dashboard.
   • Click on the "Observability" tab.
   • You should see recent requests displayed in the "Traces" section. Each entry represents a unique invocation of your Worker.
   • Click on a specific trace ID to view its detailed execution timeline, including duration, events, and sub-requests. This detailed view provides insights into the lifecycle of your Worker's execution, which is particularly useful for debugging complex logic or external API calls.

Programmatic tracing with context

For more advanced tracing, Cloudflare Workers support trace context propagation, allowing you to link traces across different services or external APIs. This is often done using W3C Trace Context headers (traceparent and tracestate).

Consider a Worker that makes an external fetch request:

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  const upstreamResponse = await fetch('https://api.example.com/data', {
    headers: {
      // Propagate trace context if available
      'traceparent': request.headers.get('traceparent'),
      'tracestate': request.headers.get('tracestate')
    }
  });

  const text = await upstreamResponse.text();
  return new Response(`Response from upstream: ${text}`, { status: 200 });
}

When you invoke this Worker, and if the upstream service also supports W3C Trace Context, Cloudflare Trace will attempt to link the Worker's execution with the upstream service's trace, providing an end-to-end view of the transaction. This is a fundamental concept in distributed tracing and helps in understanding performance bottlenecks across microservices.

Common next steps

Once you have successfully generated your first trace, several common next steps can enhance your use of Cloudflare Trace for more complex applications:

• Explore Detailed Trace Views: Spend time examining the individual trace details in the Cloudflare dashboard. Understand the timeline, events, and any logs associated with specific spans. This will help you identify slow operations or errors.
• Integrate with Logs: Cloudflare Trace works in conjunction with Cloudflare Logs. Ensure your Workers are emitting relevant logs (e.g., using console.log()) to provide contextual information within your traces. This combined view is powerful for debugging.
• Set Up Custom Spans: For more granular control over what gets traced, you can instrument your Worker code with custom spans using the Cloudflare Workers Trace API. This allows you to define specific operations within your Worker that you want to monitor, providing deeper insights into internal function execution.
• Connect External Tracing Systems: If you are already using an external observability platform like Datadog or New Relic, explore integrations. Cloudflare Trace can often export or propagate trace context to these systems, allowing you to maintain a unified view of your application's performance across different environments.
• Configure Alerts: Based on the metrics and trace data, configure alerts in the Cloudflare dashboard or via external monitoring tools. This proactive approach can notify you of performance degradations or error rates before they impact users significantly.
• Review Pricing: Understand the Cloudflare Workers and Pages pricing model, especially regarding trace and log data retention and volume, to manage costs as your application scales.
• Explore OpenTelemetry: For a vendor-neutral approach to observability, investigate OpenTelemetry. Cloudflare Workers can be configured to export data in OpenTelemetry format, offering flexibility and avoiding vendor lock-in for your tracing infrastructure.

Troubleshooting the first call

Encountering issues during the initial setup is common. Here are some troubleshooting steps for your first call with Cloudflare Trace:

• Worker Not Responding:
  • Check Worker Deployment Status: In the Cloudflare dashboard, ensure your Worker shows as "Deployed". If not, try redeploying it.
  • Verify Route Configuration: If you're using custom routes, confirm that the route pattern correctly matches your Worker's URL and that the Worker is associated with the correct route.
  • DNS Propagation: If you've recently changed DNS records for a custom domain, allow time for DNS propagation.
• No Traces Appearing:
  • Ensure Trace is Enabled: Double-check the "Observability" settings for your Worker in the Cloudflare dashboard and confirm that "Trace" is toggled on.
  • Generate Traffic: Make sure you are actually sending requests to your Worker's URL. Traces are only generated upon invocation.
  • Time Delay: There might be a slight delay (typically a few seconds) for traces to appear in the dashboard. Try refreshing the "Observability" tab after a short wait.
  • Worker Errors: If your Worker is throwing unhandled exceptions, it might prevent traces from being fully captured or displayed. Check the "Logs" tab for any runtime errors.
  • Free Tier Limits: While the free tier includes Trace, there are usage limits. If you're making an extremely high volume of requests, you might hit a soft limit. For initial testing, this is unlikely to be an issue.
• Incomplete Trace Data:
  • Worker Runtime Issues: If a Worker terminates unexpectedly (e.g., due to an unhandled promise rejection), the trace might not be fully recorded. Ensure your Worker code handles errors gracefully.
  • External API Call Issues: If your Worker makes external API calls and you expect to see those as part of the trace, ensure proper trace context propagation (e.g., W3C traceparent headers) is implemented in both your Worker and the upstream service. If the external service doesn't support trace context, its internal operations won't appear as part of your Cloudflare trace.
• Permission Errors with API Tokens:
  • If you are using Wrangler CLI or the API to deploy/manage Workers and encounter permission issues, verify that your API token has the necessary "Worker Scripts" and "Account" permissions. Refer to the Cloudflare API Token documentation for detailed requirements.