Skip to content

Commit 0779a64

Browse files
nevikashahnevikashah
committed
WIP PR for tracing
1 parent fbe0bfb commit 0779a64

File tree

8 files changed

+211
-0
lines changed

8 files changed

+211
-0
lines changed

‎src/content/docs/workers/observability/exporting-opentelemetry-data/3rd-party-destinations/datadog.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Datadog
4+
sidebar:
5+
order: 1
6+
---

‎src/content/docs/workers/observability/exporting-opentelemetry-data/3rd-party-destinations/grafana.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Grafana
4+
sidebar:
5+
order: 4
6+
---

‎src/content/docs/workers/observability/exporting-opentelemetry-data/3rd-party-destinations/honeycomb.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Honeycomb
4+
sidebar:
5+
order: 2
6+
---

‎src/content/docs/workers/observability/exporting-opentelemetry-data/3rd-party-destinations/index.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
pcx_content_type: navigation
3+
title: 3rd party destinations
4+
sidebar:
5+
order: 2
6+
---
7+
8+
Third-party destinations for exporting OpenTelemetry data from Cloudflare Workers.

‎src/content/docs/workers/observability/exporting-opentelemetry-data/3rd-party-destinations/sentry.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Sentry
4+
sidebar:
5+
order: 3
6+
---

‎src/content/docs/workers/observability/exporting-opentelemetry-data/index.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
pcx_content_type: concept
3+
title: Exporting OpenTelemetry Data
4+
sidebar:
5+
order: 4
6+
---
7+
8+
import { Badge, DirectoryListing } from "~/components";
9+
10+
Cloudflare Workers supports exporting OpenTelemetry (OTel)-compliant telemetry data to any compatible destination, allowing you to integrate with your existing monitoring and observability stack.
11+
12+
### Supported telemetry types
13+
14+
You can export the following types of telemetry data:
15+
16+
- **Traces** - Traces showing request flows through your Worker and connected services
17+
- **Logs** - Application logs including `console.log()` output and system-generated logs
18+
- **Metrics** - Performance metrics and custom measurements (not yet supported - coming soon)
19+
20+
### Supported destinations
21+
22+
Cloudflare Workers can export data to any platform that supports the OpenTelemetry Protocol (OTLP), including:
23+
- Datadog
24+
- Honeycomb
25+
- Grafana Cloud
26+
- Sentry
27+
- Custom OTLP endpoints
28+
29+
## Setting up OpenTelemetry-compatible destinations
30+
31+
Before you can export telemetry data, you need to create and configure a destination in the Cloudflare dashboard.
32+
33+
### Creating a destination
34+
35+
1. Head to your account's Workers Observability section of the dashboard and add a new destination.
36+
2. **Configure your destination:**
37+
- **Destination Name** - A descriptive name (e.g., "Datadog APM", "Honeycomb Logs")
38+
- **Destination Type** - Choose between "Traces" or "Logs"
39+
- **OTLP Endpoint** - The URL where your observability platform accepts OTLP data. This endpoint should end in `/logs` or /traces`
40+
- **Custom Headers** (Optional) - Add any authentication headers or other required headers
41+
42+
## Enabling OpenTelemetry export for your Worker
43+
44+
After setting up destinations in the dashboard, configure your Worker to export telemetry data by updating your `wrangler.jsonc` configuration.
45+
46+
```jsonc title="wrangler.jsonc"
47+
{
48+
"observability": {
49+
"traces": {
50+
"enabled": true,
51+
"destinations": ["honeycomb-apm", "datadog-apm"],
52+
"head_sample_rate": 0.05
53+
},
54+
55+
"logs": {
56+
"enabled": true,
57+
"destinations": ["datadog-logs", "honeycomb-logs"],
58+
"head_sample_rate": 0.5
59+
}
60+
}
61+
}
62+
```
63+
Then redeploy your Worker for new configurations to take effect.
64+
65+
### Configuration options
66+
- **`enabled`** - Enable or disable telemetry collection
67+
- **`head_sample_rate`** - Percentage of requests to sample (0.0 to 1.0)
68+
- **`destinations`** - Array of destination names to export data to. These should be from the destination names created in the dashboard. Include `"cloudflare"` in this array to also send traces and logs to the Workers Dashboard.
69+

‎src/content/docs/workers/observability/traces/index.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Traces
4+
sidebar:
5+
order: 3
6+
group:
7+
hideIndex: false
8+
---
9+
10+
import { Badge, DirectoryListing } from "~/components";
11+
12+
Tracing gives you end-to-end visibility into the life of a request as it travels through your Workers application and connected services, helping you to identify performance bottlenecks, debug issues, and understand complex request flows.
13+
14+
With tracing you can answer questions such as:
15+
* What is the cause of a long-running request?
16+
* Where in the chain of services did a request fail?
17+
* How long do subrequests to my Worker take?
18+
* How long are my requests to my KV Namespace or R2 bucket taking?
19+
20+
## Automatic instrumentation
21+
22+
Each trace consists of one or more spans, representing the various calls made to different Worker services as part of the invocation. Cloudflare has automatically instrumented fetch calls and requests to Cloudflare resources (e.g. Workers KV, D1 Databases, Durable Objects) bound to your Workers application, without requiring you to install and configure an OpenTelemetry SDK.
23+
24+
Take for example, application that handles online ordering and makes request to a D1 Database to fetch customer information, an external API to validate payment information, and a Cloudflare Queue to submit the order.
25+
26+
Tracing lets you visualize an invocation call by call at each part of the request journey. Our example above may look something like this:
27+
28+
TODO: insert example of trace here
29+
30+
## How to enable tracing
31+
32+
If you would like to view traces in the Cloudflare Dashboard using Workers Observability, you can set the following in your Wrangler configuration file:
33+
34+
```jsonc title="wrangler.jsonc"
35+
36+
{
37+
"observability": {
38+
// enabling traces
39+
"traces": {
40+
"enabled": true,
41+
},
42+
}
43+
}
44+
```
45+
46+
You can also export OpenTelemetry traces to a 3rd party destination such as Datadog or Honeycomb.
47+
48+
### Exporting OpenTelemetry traces to a 3rd party destination
49+
50+
In addition to viewing traces in the Cloudflare Dashboard, you can export traces to any OpenTelemetry-compatible destination, including popular platforms such as Datadog and Honeycomb.
51+
52+
To configure trace export to external destinations, you'll need to set up a destination in the Cloudflare dashboard and set your desired destination within your Wrangler configuration.
53+
54+
55+
## Head-based sampling
56+
57+
Head-based sampling allows you to trace a percentage of incoming requests in your Cloudflare Worker. Most production applications at scale use head sampling because it is unnecessary and costly to trace every single request. With sampling, you can help reduce volume and manage costs, while still providing meaningful insights into your application.
58+
59+
You can configure head-based sampling for both tracing and logging separately on a per-Worker basis. The valid range is from 0 to 1, where 0 indicates zero out of one hundred invocations will be traced, and 1 indicates every requests will be traced. If head_sampling_rate is unspecified, it defaults to tracing 100% of requests.
60+
61+
You can configure this in your Wrangler configuration like this:
62+
63+
```jsonc title="wrangler.jsonc"
64+
65+
{
66+
"tracing": {
67+
//enables tracing (required field)
68+
"enabled": true
69+
"destinations": ["external", "cloudflare"]
70+
// set tracing sampling rate to 5%
71+
"head_sample_rate": 0.05
72+
},
73+
// optional override since {obs enabled:true}
74+
"logging": {
75+
"enabled": true
76+
// set logging sampling rate to 50%
77+
"head_sample_rate": 0.5
78+
}
79+
}
80+
```
81+
82+
## Limits & Pricing
83+
84+
Workers tracing is currently **free** during the early beta period. This includes all tracing functionality: collecting traces, storing them, and viewing them in the Cloudflare dashboard.
85+
86+
Starting on xx/xx/xxxx, tracing will be billed as part of Workers observability. Each span in a trace counts as one observability event, sharing the same monthly quota and pricing as [Workers logs](https://developers.cloudflare.com/workers/platform/pricing/#workers-logs):
87+
88+
| | Events (trace spans or log events) | Retention |
89+
| ---------------- | ------------------------------------------------------------------------- | --------- |
90+
| **Workers Free** | 100,000 per day | 3 Days |
91+
| **Workers Paid** | 10 million included per month <br /> +$0.05 per additional 100,000 events | 30 Days |
92+
93+
When billing begins on xx/xx/xxxx, you'll automatically start being charged based on your plan.
94+
95+
96+
## [Spans and attributes](/workers/observability/traces/spans-and-attributes)
97+
While our work for automatic instrumentation is ongoing, we've documented all existing spans and attributes currently instrumented today.
98+
99+
100+
<DirectoryListing />

‎src/content/docs/workers/observability/traces/spans-and-attributes.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
pcx_content_type: concept
3+
title: Spans and attributes
4+
sidebar:
5+
order: 2
6+
---
7+
8+
import { Render } from "~/components";
9+
10+
Cloudflare has automatically instrumented fetch calls and requests to Cloudflare resources (e.g. Workers KV, D1 Databases, Durable Objects) bound to your Workers application, without requiring you to install and configure an OpenTelemetry SDK.

0 commit comments

Comments
 (0)