Skip to content

Commit 2f3af5e

Browse files
mikenomitchmikenomitch
committed
Various tweaks to tracing docs
1 parent 179131d commit 2f3af5e

File tree

3 files changed

+168
-117
lines changed

3 files changed

+168
-117
lines changed

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

Lines changed: 75 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -3,102 +3,124 @@ pcx_content_type: navigation
33
title: Traces
44
sidebar:
55
order: 3
6-
6+
badge:
7+
text: Beta
78
---
9+
810
import { WranglerConfig } from "~/components";
911

10-
### What is Workers tracing?
12+
### What is Workers tracing?
1113

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. With tracing you can answer questions such as:
13-
* What is the cause of a long-running request?
14-
* How long do subrequests to my Worker take?
15-
* How long are my calls to my KV Namespace or R2 bucket taking?
14+
Tracing gives you end-to-end visibility into the life of a request as it travels through your Workers application and connected services. This helps you identify performance bottlenecks, debug issues, and understand complex request flows. With tracing you can answer questions such as:
1615

16+
- What is the cause of a long-running request?
17+
- How long do subrequests from my Worker take?
18+
- How long are my calls to my KV Namespace or R2 bucket taking?
1719

1820
![Example trace showing a POST request to a cake shop with multiple spans including fetch requests and durable object operations](~/assets/images/workers-observability/trace-waterfall-example.png)
1921

20-
### Automatic instrumentation
22+
### Automatic instrumentation
2123

22-
Cloudflare Workers provides automatic tracing instrumentation **out of the box** - no code changes or no SDK installation required. Simply enable tracing on your Worker and Cloudflare automatically captures telemetry data for:
24+
Cloudflare Workers provides tracing instrumentation **out of the box** - no code changes or SDK are required. Simply enable tracing on your Worker and Cloudflare automatically captures telemetry data for:
2325

24-
- **Fetch calls** - All outbound HTTP requests, capturing timing, status codes, and request metadata. This enables you to quickly identify which external dependencies are affecting your application's performance.
25-
- **Binding calls** - Interactions with various Worker bindings such as KV reads and writes, R2 object storage operations and Durable Object invocations
26-
- **Handler calls** - The complete lifecycle of each Worker invocation, including triggers such as fetch handlers, scheduled handlers, and queue handlers.
26+
- **Fetch calls** - All outbound HTTP requests, capturing timing, status codes, and request metadata. This enables you to quickly identify how external dependencies affect your application's performance.
27+
- **Binding calls** - Interactions with various Worker bindings such as KV reads and writes, R2 object storage operations and Durable Object invocations.
28+
- **Handler calls** - The complete lifecycle of each Worker invocation, including triggers such as [fetch handlers](/workers/runtime-apis/handlers/fetch/),
29+
[scheduled handlers](/workers/runtime-apis/handlers/scheduled/), and [queue handlers](/queues/configuration/javascript-apis/#consumer).
2730

28-
While our work for automatic instrumentation is ongoing, we've [documented](/workers/observability/traces/spans-and-attributes) all existing spans and attributes currently instrumented today.
31+
For a full list of instrumented operations , see the [spans and attributes documentation](/workers/observability/traces/spans-and-attributes).
2932

3033
### How to enable tracing
3134

32-
To view traces in the Workers dashboard, set the following in your Wrangler configuration file:
35+
If you have already set `observability.enabled = true` in your [wrangler configuration file](/workers/wrangler/configuration/#observability), tracing **and** logs will be automatically enabled.
3336

3437
<WranglerConfig>
3538

3639
```json
3740
{
38-
"observability": {
39-
"traces": {
40-
"enabled": true,
41-
// optional sampling rate
42-
"head_sampling_rate": 0.05
43-
}
44-
}
41+
"observability": {
42+
"enabled": true
43+
}
4544
}
4645
```
4746

4847
</WranglerConfig>
4948

50-
Or if you have already set `observability.enabled = true` in your wrangler configuration file, tracing **and** logs will be automatically enabled.
49+
You can also configure tracing independently by setting `observability.traces.enabled = true` in your [wrangler configuration file](/workers/wrangler/configuration/#observability).
50+
51+
<WranglerConfig>
52+
53+
```json
54+
{
55+
"observability": {
56+
"traces": {
57+
"enabled": true,
58+
// optional sampling rate (recommended for high-traffic workloads)
59+
"head_sampling_rate": 0.05
60+
}
61+
}
62+
}
63+
```
64+
65+
</WranglerConfig>
5166

5267
### Exporting OpenTelemetry traces to a 3rd party destination
53-
Workers tracing follows [OpenTelemetry (OTel) standards](https://opentelemetry.io/), making it compatible with popular observability platforms while requiring zero development effort from you.
54-
If your observability provider has an available OpenTelemetry endpoint, you can export traces (and logs!)
5568

56-
Learn more about exporting OpenTelemetry data from Workers to your provider of choice [here](/workers/observability/exporting-opentelemetry-data/).
69+
Workers tracing follows [OpenTelemetry (OTel) standards](https://opentelemetry.io/). This makes it compatible with popular observability platforms,
70+
such as [Honeycomb](/workers/observability/exporting-opentelemetry-data/honeycomb/), [Grafana Cloud](/workers/observability/exporting-opentelemetry-data/grafana-cloud/), and
71+
[Axiom](workers/observability/exporting-opentelemetry-data/axiom/), while requiring zero development effort from you. If your observability provider has an available OpenTelemetry endpoint, you can export traces (and logs)!
72+
73+
Learn more about exporting OpenTelemetry data from Workers [here](/workers/observability/exporting-opentelemetry-data/).
74+
75+
### Sampling
76+
77+
:::note[Default Sampling Rate]
78+
79+
The default sampling rate is `1`, meaning 100% of requests will be traced if tracing is enabled. Set `head_sampling_rate` if
80+
you want to trace fewer requests.
5781

58-
### Sampling
82+
:::
5983

60-
#### Head-based sampling
61-
With head-based sampling, you can trace a percentage of incoming requests in your Cloudflare Worker to manage volume and costs, while still providing meaningful insights into your application.
84+
With sampling, you can trace a percentage of incoming requests in your Cloudflare Worker.
85+
This allows you to manage volume and costs, while still providing meaningful insights into your application.
6286

63-
The valid sampling 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.
87+
The valid sampling 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,
88+
and a number such a `0.05` indicates five out of one hundred requests will be traced.
89+
90+
If you have not specified a sampling rate, it defaults to `1`, meaning 100% of requests will be traced.
6491

6592
<WranglerConfig>
6693

6794
```json
6895
{
69-
"observability": {
70-
"traces": {
71-
"enabled": true,
72-
// set tracing sampling rate to 5%
73-
"head_sampling_rate": 0.05
74-
},
75-
"logs": {
76-
"enabled": true,
77-
// set logging sampling rate to 60%
78-
"head_sampling_rate": 0.6
79-
}
80-
}
96+
"observability": {
97+
"traces": {
98+
"enabled": true,
99+
// set tracing sampling rate to 5%
100+
"head_sampling_rate": 0.05
101+
},
102+
"logs": {
103+
"enabled": true,
104+
// set logging sampling rate to 60%
105+
"head_sampling_rate": 0.6
106+
}
107+
}
81108
}
82109
```
83110

84111
</WranglerConfig>
85112

86-
If you have `head_sampling_rate` configured for logs, you can also create a separate rate for traces.
113+
If you have `head_sampling_rate` configured for logs, you can also create a separate rate for traces.
87114

88-
#### Default sampling
89-
TODO: update this --> If `head_sampling_rate` is unspecified, it defaults to tracing 100% of requests.
115+
Sampling is [head-based](https://opentelemetry.io/docs/concepts/sampling/#head-sampling), meaning that non-traced requests do not incur any tracing overhead.
90116

91-
### Limits & Pricing
117+
### Limits & Pricing
92118

93-
Workers tracing is currently **free** during the early beta period. This includes all tracing functionality such as collecting traces, storing them, and viewing them in the Cloudflare dashboard.
119+
Workers tracing is currently **free** during the initial beta period. This includes all tracing functionality such as collecting traces, storing them, and viewing them in the Cloudflare dashboard.
94120

95121
Starting on January 15, 2026, tracing will be billed as part of your usage on the Workers Free Paid and Enterprise plans. Each span in a trace represents one observability event, sharing the same monthly quota and pricing as [Workers logs](/workers/platform/pricing/#workers-logs):
96122

97-
| | Events (trace spans or log events) | Retention |
98-
| ---------------- | ------------------------------------------------------------------------- | --------- |
99-
| **Workers Free** | 200,000 per day | 3 Days |
100-
| **Workers Paid** | 10 million included per month +$0.60 per additional million events | 7 Days |
101-
102-
103-
104-
123+
| | Events (trace spans or log events) | Retention |
124+
| ---------------- | ------------------------------------------------------------------ | --------- |
125+
| **Workers Free** | 200,000 per day | 3 Days |
126+
| **Workers Paid** | 10 million included per month +$0.60 per additional million events | 7 Days |

‎src/content/docs/workers/observability/traces/known-limitations.md‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,51 @@
11
---
22
pcx_content_type: navigation
3-
title: Known limitations
3+
title: Known limitations
44
sidebar:
55
order: 3
66
group:
77
hideIndex: false
88
---
99

10-
Workers tracing is currently in open beta. This page documents current limitations and any upcoming features on our roadmap. To provide more feedback and feature requests please reach out to us.
10+
Workers tracing is currently in open beta. This page documents current limitations and any upcoming features on our roadmap.
11+
12+
To provide more feedback and send feature requests, head to the [Workers tracing GitHub discussion](https://github.com/cloudflare/workers-sdk/discussions/TODO-GET-THE-LINK).
13+
14+
### Non-I/O operations may report time of 0 ms
15+
16+
Due to [security measures put in place to prevent Spectre attacks](workers/reference/security-model/#step-1-disallow-timers-and-multi-threading), the Workers
17+
Runtime does not update time until I/O events take place. This means that some spans will return a length of `0 ms` even when the operation took longer.
18+
19+
The Cloudflare Workers team is exploring security measures that would allow exposing time lengths at milisecond-level granularity in these cases.
1120

1221
### Trace context propagation not yet supported
13-
One of the key aspects of distributed tracing is ensuring trace context flows across service boundaries and automatically linking spans together to create complete, end-to-end visibility. When fully implemented, our automatic trace context propagation will follow [W3C standards](https://www.w3.org/TR/trace-context/) to ensure compatibility across your existing tools and services.
1422

15-
Without trace context propagation, you will also see an additional trace whenever your Worker is making a call to another Worker via service bindings or to a Durable Object.
23+
Currently, Workers tracing does not propagate trace IDs to different platforms or accept trace IDs from other platforms.
24+
25+
This means that spans from Workers will not be nested within traces from services that call Workers (or vice versa).
26+
27+
Ideally, trace context can flow across service boundaries and automatically link spans together to create complete, end-to-end visibility.
28+
When fully implemented, our automatic trace context propagation will follow [W3C standards](https://www.w3.org/TR/trace-context/) to ensure compatibility across your existing tools and services.
29+
This will allow for traces to include spans from both Workers and other services.
1630

17-
### Missing instrumentation for some spans and attributes
18-
We are adding more automatic instrumentation for every part of the Workers platform. While we first want to give you visibility into the duration of every operation within your request, we also planning to add more detailed attributes on each span. You can find a complete list of what is already instrumented [here](/workers/observability/traces/spans-and-attributes). Your feedback on what’s missing will help us prioritize accordingly.
31+
Without trace context propagation, calls to separate Workers and to Durable Objects create separate traces, rather than nested spans.
1932

20-
### Support for custom spans and attributes:
21-
While automatic instrumentation covers the platform interactions, we know you need visibility into your own application logic too. We're working to support the [OpenTelemetry API](https://www.npmjs.com/package/@opentelemetry/api) to make it easier for you to instrument custom spans within your application.
33+
### Incomplete spans attributes
34+
35+
We are planning to add more detailed attributes on each span. You can find a complete list of what is already instrumented [here](/workers/observability/traces/spans-and-attributes).
36+
37+
Your feedback on any missing information will help us prioritize additions and changes. Please comment on the [Workers tracing GitHub discussion](https://github.com/cloudflare/workers-sdk/discussions/TODO-GET-THE-LINK)
38+
if specific attributes would be helpful to use tracing effectively.
39+
40+
### Support for custom spans and attributes
41+
42+
Automatic instrumentation covers many platform interactions, but we know you need visibility into your own application logic too. We're working to support the [OpenTelemetry API](https://www.npmjs.com/package/@opentelemetry/api) to make it easier for you to instrument custom spans within your application.
2243

2344
### Span and attribute names subject to change
45+
2446
As Workers tracing is currently in beta, span names and attribute names are not yet finalized. We may refine these names during the beta period to improve clarity and align with OpenTelemetry semantic conventions. We recommend reviewing the [spans and attributes documentation](/workers/observability/traces/spans-and-attributes) periodically for updates.
2547

26-
### Known bugs and other call outs
27-
* There are currently are a few pieces of metadata that only apply to spans (e.g.`service.name`, `faas.name`), however, some may apply across all events. For example, when filtering/grouping on the Worker name across traces and logs, use `$metadata.service` as it will apply consistently across all event types.
28-
* While a trace is in progress, the event will show `Trace in Progress` on the root span. Please wait a few moments for the full trace to become available
48+
### Known bugs and other call outs
49+
50+
- There are currently are a few attributes that only apply to some spans (e.g.`service.name`, `faas.name`). When filtering or grouping by the Worker name across traces and logs, use `$metadata.service` instead, as it will apply consistently across all event types.
51+
- While a trace is in progress, the event will show `Trace in Progress` on the root span. Please wait a few moments for the full trace to become available

0 commit comments

Comments
 (0)