Cloudflare Workers 自动插桩 fetch 调用、KV 读取和 D1 查询等平台操作。自定义 span 让您将可见性扩展到自己的应用程序逻辑,以便在内置插桩的同时追踪自定义代码路径。
自定义 span API 有两种使用方式——两者提供相同方法,行为完全一致:
import { tracing } from "cloudflare:workers"— 可在代码库任意位置使用,包括工具函数、库以及无法访问处理程序上下文的模块。ctx.tracing— 在传递给处理程序的ExecutionContext上可用,在处理程序内部工作时更为便捷。
有三种创建 span 的方法:
enterSpan()— 创建在回调返回或其返回的 promise 完成时自动结束的 span。大多数插桩使用此方法。startActiveSpan()— 创建在回调期间活动的 span,并通过调用span.end()手动结束。当 span 必须比回调寿命更长时使用,例如为流或其他长生命周期操作插桩。startSpan()— 创建 span 但不使其成为活动 span,并通过调用span.end()手动结束。当你需要为操作计时但不需要其他 span 嵌套在其下时使用。
你还可以调用 getActiveSpan() 获取当前活动 span,以便添加属性或记录异常,而无需在代码中传递 span 对象。
自定义 span 需要在 Worker 上启用追踪。如果尚未启用,请在 Wrangler 配置文件 中将 observability.traces.enabled 设置为 true:
{
"$schema": "./node_modules/wrangler/config-schema.json",
"observability": {
"traces": {
"enabled": true
}
}
}[observability.traces]
enabled = true使用 tracing.enterSpan() 将一段代码包装在命名 span 中。span 会自动成为当前活动 span 的子 span,并在回调返回或其返回的 promise 完成时结束。
以下示例同时使用两种访问方式——cloudflare:workers 导入和 ctx.tracing——以表明两者可以互换:
import { tracing } from "cloudflare:workers";
export default {
async fetch(request, env, ctx) {
// Using the import
return tracing.enterSpan("handleRequest", async (span) => {
span.setAttribute("url.path", new URL(request.url).pathname);
const user = await ctx.tracing.enterSpan("auth", async () => {
// Using ctx.tracing
return authenticate(request, env);
});
return buildResponse(user);
});
},
};import { tracing } from "cloudflare:workers";
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
// Using the import
return tracing.enterSpan("handleRequest", async (span) => {
span.setAttribute("url.path", new URL(request.url).pathname);
const user = await ctx.tracing.enterSpan("auth", async () => {
// Using ctx.tracing
return authenticate(request, env);
});
return buildResponse(user);
});
},
};创建新 span 并在其中运行 callback。当回调返回(同步或异步)或抛出异常时,span 自动结束。
参数:
| 参数 | 类型 | 说明 |
|---|---|---|
name |
string |
span 的名称。会显示在追踪可视化中。 |
callback |
(span: Span, ...args: A) => T |
在 span 内执行的函数。第一个参数接收 Span 对象,后续为传递给 enterSpan 的额外参数。 |
...args |
A |
可选的额外参数,在 span 参数之后转发给回调。 |
返回值: callback 的返回值。
行为:
- 新 span 是当前异步上下文上活动 span 的子 span。如果没有活动 span,则成为请求根 span 的子 span。
- 在回调内运行的嵌套
enterSpan调用和运行时创建的 span(如fetch或 KV 操作)会自动成为此 span 的子 span。 - 当回调同步返回、同步抛出异常,或其返回的 promise 完成或拒绝时,span 结束。
// Synchronous callback — span ends when the function returns
const result = tracing.enterSpan("parse", (span) => {
span.setAttribute("format", "json");
return JSON.parse(body);
});
// Async callback — span ends when the promise settles
const data = await tracing.enterSpan("fetchData", async (span) => {
const res = await fetch("https://api.example.com/data");
span.setAttribute("http.response.status_code", res.status);
return res.json();
});
// Forwarding arguments
const doubled = tracing.enterSpan("compute", (span, x) => x * 2, 21);创建新 span,在 callback 运行期间使其成为活动 span,并返回回调结果,不会 自动结束 span。操作完成时必须显式调用 span.end()。
参数:
| 参数 | 类型 | 说明 |
|---|---|---|
name |
string |
span 的名称。会显示在追踪可视化中。 |
callback |
(span: Span, ...args: A) => T |
在 span 活动期间执行的函数。第一个参数接收 Span 对象,后续为额外参数。 |
...args |
A |
可选的额外参数,在 span 参数之后转发给回调。 |
返回值: callback 的返回值。
行为:
- 与
enterSpan不同,当回调返回或抛出时,span 不会 自动结束。你负责调用span.end()。 - 如果忘记调用
span.end(),当请求拥有的 span 对象被销毁时,span 仍会作为兜底提交。不要依赖此行为——始终显式调用span.end()。
当你需要 span 覆盖超出单个回调的操作时使用 startActiveSpan——例如,为流管道插桩,使 span 保持打开直到流被完全消费:
import { tracing } from "cloudflare:workers";
export default {
async fetch(request, env, ctx) {
const body = request.body;
if (!body) return new Response("No body", { status: 400 });
// The span is active during the callback, so the pipeThrough
// operation is correctly nested. The span stays open after
// the callback returns, until flush() calls span.end().
const stream = tracing.startActiveSpan("process-stream", (span) => {
span.setAttribute(
"request.content_type",
request.headers.get("content-type") ?? "unknown",
);
return body.pipeThrough(
new TransformStream({
transform(chunk, controller) {
// Process each chunk
controller.enqueue(chunk);
},
flush() {
span.setAttribute("stream.status", "complete");
span.end();
},
cancel() {
span.setAttribute("stream.status", "cancelled");
span.end();
},
}),
);
});
return new Response(stream);
},
};import { tracing } from "cloudflare:workers";
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const body = request.body;
if (!body) return new Response("No body", { status: 400 });
// The span is active during the callback, so the pipeThrough
// operation is correctly nested. The span stays open after
// the callback returns, until flush() calls span.end().
const stream = tracing.startActiveSpan("process-stream", (span) => {
span.setAttribute(
"request.content_type",
request.headers.get("content-type") ?? "unknown",
);
return body.pipeThrough(
new TransformStream({
transform(chunk, controller) {
// Process each chunk
controller.enqueue(chunk);
},
flush() {
span.setAttribute("stream.status", "complete");
span.end();
},
cancel() {
span.setAttribute("stream.status", "cancelled");
span.end();
},
}),
);
});
return new Response(stream);
},
};如果不需要 span 在回调期间处于活动状态,请改用 startSpan。
创建新 span 并返回它,不会 使其成为活动 span。操作完成时必须显式调用 span.end()。
参数:
| 参数 | 类型 | 说明 |
|---|---|---|
name |
string |
span 的名称。会显示在追踪可视化中。 |
返回值: 一个 Span。
行为:
- 新 span 是当前异步上下文上活动 span 的子 span。如果没有活动 span,则成为请求根 span 的子 span。
- span 永远不会成为活动 span。在它打开期间由
enterSpan、startActiveSpan和平台操作(如fetch或 KV 操作)创建的 span 不是 此 span 的子 span,而是兄弟 span。 - 如果忘记调用
span.end(),当请求拥有的 span 对象被销毁时,span 仍会作为兜底提交。不要依赖此行为——始终显式调用span.end()。
当你想测量开始和结束发生在不同位置的操作(例如事件回调或类的多个方法中),并且不需要其他 span 嵌套在其下时,使用 startSpan:
import { tracing } from "cloudflare:workers";
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
// ...
const span = tracing.startSpan("cache-warmup");
span.setAttribute("cache.keys", keys.length);
try {
await warmCache(keys);
span.setAttribute("cache.warmup.status", "complete");
} catch (err) {
span.recordException(err as Error);
throw err;
} finally {
span.end();
}
// ...
},
};返回当前在异步上下文上活动的 span。
返回值: 一个 Span,或 undefined。
行为:
- 在请求内,返回当前被视为活动的
Span。如果尚未使用enterSpan或startActiveSpan或系统本身显式创建 span,它会返回当前调用的根 span。你可以用它在根 span 上添加属性或记录异常。 - 在请求外返回
undefined,例如在模块顶层作用域,或在请求外捕获的异步上下文中运行的代码。 - 使用
startSpan创建的 span 永远不会变为活动,因此getActiveSpan永远不会返回它们。
使用 getActiveSpan 标注当前 span,而无需在代码中传递 span 对象:
import { tracing } from "cloudflare:workers";
export default {
async fetch(request, env, ctx) {
const user = await authenticate(request, env);
// No custom span is active, so this annotates the root span
tracing.getActiveSpan()?.setAttributes({
"user.id": user.id,
"user.plan": user.plan,
});
return tracing.enterSpan("render", async () => {
// ...
return new Response("OK");
});
},
};import { tracing } from "cloudflare:workers";
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const user = await authenticate(request, env);
// No custom span is active, so this annotates the root span
tracing.getActiveSpan()?.setAttributes({
"user.id": user.id,
"user.plan": user.plan,
});
return tracing.enterSpan("render", async () => {
// ...
return new Response("OK");
});
},
};enterSpan 和 startActiveSpan 会将 Span 对象传给回调,startSpan 和 getActiveSpan 会返回一个。它提供向 span 添加元数据并控制其生命周期的方法。
在 span 上设置 attribute。
| 参数 | 类型 | 说明 |
|---|---|---|
key |
string |
attribute 名称。 |
value |
string | number | boolean | undefined |
attribute 值。传入 undefined 时不执行任何操作。 |
返回值: 同一个 Span,因此可以链式调用。
Attributes 会随 span 一起显示在追踪和 OpenTelemetry 导出中。
span
.setAttribute("user.plan", "enterprise")
.setAttribute("item.count", 42)
.setAttribute("cache.hit", true);一次在 span 上设置多个 attribute。这与为每个条目调用 setAttribute 相同。
| 参数 | 类型 | 说明 |
|---|---|---|
attributes |
Record<string, string | number | boolean | undefined> |
将 attribute 名称映射到值的对象。值为 undefined 的条目会被忽略。 |
返回值: 同一个 Span,因此可以链式调用。
span.setAttributes({
"user.plan": "enterprise",
"item.count": 42,
"cache.hit": true,
"optional.field": undefined, // ignored
});在 span 上记录异常事件。该事件包含时间戳,并显示在追踪和 OpenTelemetry 导出中。
| 参数 | 类型 | 说明 |
|---|---|---|
exception |
Exception |
要记录的异常。 |
你可以传入以下任一内容:
Error对象。运行时记录其name、message和stack。- 字符串,运行时将其记录为异常消息。
- 至少包含
code、name或message之一以及可选stack的对象。code可以是字符串或数字。
如果 span 未被追踪或已经结束,或者你传入的对象不包含 code、name 或 message 中的任何一个,运行时会忽略该调用。
记录异常不会结束 span,也不会改变其结束方式。它也不会捕获或重新抛出错误。你仍需在自己的代码中处理错误。
await tracing.startActiveSpan("chargeCard", async (span) => {
try {
return await chargeCard(token, amount);
} catch (err) {
span.recordException(err as Error);
throw err;
} finally {
span.end();
}
});// Strings and plain objects are also accepted
span.recordException("Upstream returned an empty body");
span.recordException({ code: "RATE_LIMITED", message: "Too many requests" });设置 span 的状态。Span 状态遵循 OpenTelemetry span 状态 ↗模型。可用它将操作标记为失败或明确成功。
| 参数 | 类型 | 说明 |
|---|---|---|
status |
SpanStatus |
要在 span 上设置的状态。 |
SpanStatus 是包含以下字段的对象:
| 字段 | 类型 | 说明 |
|---|---|---|
code |
"unset" | "ok" | "error" |
状态代码。每个 span 的初始值都是 "unset"。 |
message |
string(可选) |
面向开发人员的错误说明。仅当 code 为 "error" 时保留。 |
返回值: 同一个 Span,因此可以链式调用。
行为:
"ok"是最终状态。将 span 的状态设为"ok"后,之后对该 span 的setStatus调用会被忽略。- 设置
"unset"不会产生效果,也不会清除之前的"error"状态。 - 除非
code为"error",否则会丢弃message。 - Span 结束后的调用会被忽略。
- 其他任何
code值都会抛出TypeError。代码必须使用小写,因此"OK"无效。 - 设置状态不会结束 span,也不会记录异常。如需同时记录错误详情,请调用
recordException。
await tracing.startActiveSpan("chargeCard", async (span) => {
try {
const result = await chargeCard(token, amount);
span.setStatus({ code: "ok" });
return result;
} catch (err) {
span.recordException(err as Error);
span.setStatus({ code: "error", message: "Card payment failed" });
throw err;
} finally {
span.end();
}
});Span 状态会包含在你导出到 OpenTelemetry 目标的跟踪中。Workers Observability 仪表板目前不会显示 span 状态,也无法按 span 状态查询或筛选跟踪。
更改 span 的名称。如果操作的最佳名称要等 span 开始后才能确定(例如请求匹配到路由之后),请使用此方法。
| 参数 | 类型 | 说明 |
|---|---|---|
name |
string |
span 的新名称。与创建 span 方法传入的名称一样,此名称最长为 64 字节。 |
返回值: 同一个 Span,因此可以链式调用。
行为:
- 新名称会替换 span 所有显示位置的原始名称,包括导出的跟踪。
- Span 结束后,对其进行的后续调用会被忽略。span 会保留
end()调用前的最后一个名称。 - 你也可以重命名
getActiveSpan()返回的调用根 span。
// Rename the invocation's root span to include the matched route
const route = router.match(request);
tracing.getActiveSpan()?.updateName(`${request.method} ${route.pattern}`);
const span = tracing.startSpan("job");
span.updateName(`job ${job.type}`);
await runJob(job);
span.end();
span.updateName("ignored"); // No effect, the span has already ended返回 span 的身份信息:其跟踪 ID、span ID 和跟踪标志。这些字段与 OpenTelemetry SpanContext ↗要求的字段相符。
返回值: 一个包含以下字段的 SpanContext 对象:
| 字段 | 类型 | 说明 |
|---|---|---|
traceId |
string |
跟踪 ID,由 32 个小写十六进制字符组成。同一次调用中的所有 span 都具有相同跟踪 ID。 |
spanId |
string |
Span ID,由 16 个小写十六进制字符组成。 |
traceFlags |
number |
此 span 的 W3C 跟踪标志 ↗。 |
行为:
- 跟踪 ID 和 span ID 与 Workers Observability 中以及导出到 OpenTelemetry 目标的跟踪中显示的 ID 相同。
- 即使 span 已结束,
spanContext()仍会返回其 ID。 - 对于未处于任何自定义 span 中时由
getActiveSpan()返回的根 span,spanContext()会返回此次调用的跟踪 ID 和根 span ID。 - 如果 Worker 已禁用监测功能,
traceId和spanId都会是零("00000000000000000000000000000000"和"0000000000000000")。 - 如果跟踪已禁用或请求未被抽样用于跟踪,但已启用 Workers Logs,
spanContext()仍会返回非零 ID。跟踪 ID 与附加到调用日志的 ID 相同,但不会存储任何 span。 traceFlags目前不会指示请求是否经过跟踪抽样。不要用它来决定是否记录遥测,也不要用它为下游服务构建traceparent标头。
使用 spanContext() 将请求与其跟踪相关联,例如记录跟踪 ID 或将其返回给客户端:
import { tracing } from "cloudflare:workers";
export default {
async fetch(request, env, ctx) {
const { traceId } = tracing.getActiveSpan()?.spanContext() ?? {};
const response = await handleRequest(request, env);
// Return the trace ID so that it can be looked up later
const headers = new Headers(response.headers);
if (traceId) headers.set("x-trace-id", traceId);
return new Response(response.body, { status: response.status, headers });
},
};import { tracing } from "cloudflare:workers";
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const { traceId } = tracing.getActiveSpan()?.spanContext() ?? {};
const response = await handleRequest(request, env);
// Return the trace ID so that it can be looked up later
const headers = new Headers(response.headers);
if (traceId) headers.set("x-trace-id", traceId);
return new Response(response.body, { status: response.status, headers });
},
};一个 readonly boolean,指示此次调用是否正在跟踪。Worker 禁用监测功能后,以及 span 结束后,isTraced 都为 false。当 isTraced 为 false 时,enterSpan 仍会运行回调,但不会记录遥测数据。
isTraced 目前不考虑头部抽样。未经过跟踪抽样的请求仍可能返回 true,其 span 会在调用结束后被丢弃。
您可以用此在请求未被追踪时跳过昂贵的 attribute 计算:
tracing.enterSpan("process", (span) => {
if (span.isTraced) {
span.setAttribute(
"request.body.preview",
JSON.stringify(body).slice(0, 200),
);
}
return processBody(body);
});结束 span 并将其 attributes 提交到追踪系统。此方法是幂等的。第一次调用之后再次调用没有效果。调用 end() 后,span.isTraced 返回 false,之后任何用于标注 span 的方法调用都会被静默忽略,包括尚未完成的进行中异步工作的调用。
- 对于使用
enterSpan创建的 span,你不需要调用end()。运行时会自动调用。自己调用end()是安全的,但可能提前结束 span。 - 对于使用
startActiveSpan或startSpan创建的 span,你必须 调用end()以提交 span。 - 对于在任何自定义 span 外由
getActiveSpan()返回的根 span,end()没有效果。运行时会在调用完成时结束根 span。
const span = tracing.startSpan("manual-op");
span.setAttribute("step", "processing");
await doWork();
// Later, when the work is truly complete:
span.end(); // Span is submitted
span.end(); // No-op, safe to call againSpan 根据 JavaScript 异步上下文自动嵌套。在回调内运行的任何 enterSpan 调用或平台操作(如 fetch 和 env.MY_KV.get())都会成为外层 span 的子 span。
import { tracing } from "cloudflare:workers";
async function handleOrder(env, orderId) {
return tracing.enterSpan("handleOrder", async (span) => {
span.setAttribute("order.id", orderId);
// This KV read is automatically a child of "handleOrder"
const order = await env.ORDERS_KV.get(orderId, "json");
// This nested span is also a child of "handleOrder"
const total = tracing.enterSpan("calculateTotal", (innerSpan) => {
innerSpan.setAttribute("item.count", order.items.length);
return order.items.reduce((sum, item) => sum + item.price, 0);
});
// This fetch is a child of "handleOrder"
await fetch("https://api.example.com/notify", {
method: "POST",
body: JSON.stringify({ orderId, total }),
});
return new Response(JSON.stringify({ orderId, total }));
});
}import { tracing } from "cloudflare:workers";
async function handleOrder(env: Env, orderId: string) {
return tracing.enterSpan("handleOrder", async (span) => {
span.setAttribute("order.id", orderId);
// This KV read is automatically a child of "handleOrder"
const order = await env.ORDERS_KV.get(orderId, "json");
// This nested span is also a child of "handleOrder"
const total = tracing.enterSpan("calculateTotal", (innerSpan) => {
innerSpan.setAttribute("item.count", order.items.length);
return order.items.reduce(
(sum: number, item: any) => sum + item.price,
0,
);
});
// This fetch is a child of "handleOrder"
await fetch("https://api.example.com/notify", {
method: "POST",
body: JSON.stringify({ orderId, total }),
});
return new Response(JSON.stringify({ orderId, total }));
});
}
console.log() 和其他 console 方法会发出自动归属于当前活动 span 的日志事件。这意味着在 enterSpan 或 startActiveSpan 回调内输出的日志会与该 span 关联,显示在追踪和 OpenTelemetry 导出中。
tracing.enterSpan("processPayment", async (span) => {
console.log("Starting payment processing"); // attributed to "processPayment"
const result = await chargeCard(token, amount);
console.log("Payment complete", result.id); // also attributed to "processPayment"
});自定义 span API 的完整类型声明:
declare module "cloudflare:workers" {
namespace tracing {
function enterSpan<T, A extends unknown[]>(
name: string,
callback: (span: Span, ...args: A) => T,
...args: A
): T;
function startActiveSpan<T, A extends unknown[]>(
name: string,
callback: (span: Span, ...args: A) => T,
...args: A
): T;
function startSpan(name: string): Span;
function getActiveSpan(): Span | undefined;
}
type Exception =
| string
| { code: string | number; name?: string; message?: string; stack?: string }
| { code?: string | number; name: string; message?: string; stack?: string }
| { code?: string | number; name?: string; message: string; stack?: string };
type SpanStatus = {
code: "unset" | "ok" | "error";
/** A developer-facing error message. Ignored unless code is "error". */
message?: string;
};
type SpanContext = {
traceId: string;
spanId: string;
traceFlags: number;
};
class Span {
readonly isTraced: boolean;
setAttribute(key: string, value: string | number | boolean): this;
setAttributes(
attributes: Record<string, string | number | boolean | undefined>,
): this;
recordException(exception: Exception): void;
setStatus(status: SpanStatus): this;
updateName(name: string): this;
spanContext(): SpanContext;
end(): void;
}
}相同的 API 在处理程序上下文中以 ctx.tracing 提供,类型相同。
enterSpan |
startActiveSpan |
startSpan |
|
|---|---|---|---|
| Span 结束 | 自动,当回调返回、抛出或其返回的 promise 完成时 | 手动,当你调用 span.end() 时 |
手动,当你调用 span.end() 时 |
| 活动上下文范围 | 回调期间 | 回调期间 | 永不活动 |
| 使用场景 | 大多数插桩——适合放在单个回调内的同步和异步工作 | 超出回调寿命的操作,例如流管道 | 为没有嵌套 span 的操作计时,并自行管理开始和结束 |
| 错误处理 | 抛出时 span 自动结束 | 抛出时 span 保持打开。调用 span.end() 或依赖运行时兜底 |
抛出时 span 保持打开。调用 span.end() 或依赖运行时兜底 |
enterSpan 和 startActiveSpan 仅在回调期间 将 span 设为活动上下文父级。回调返回后,span 不再是活动父级。对于 enterSpan,这一区别无关紧要,因为 span 也会结束。对于 startActiveSpan,span 保持打开但不再是上下文父级——回调返回后创建的新 span 不是此 span 的子 span。startSpan 永远不会将 span 设为活动上下文父级,因此永远不会创建其子 span。
运行时限制你可以添加到自定义 span 的数据量:
- Span 名称会被截断为 64 字节。
- 每个 span 大约可以保存 64 KB 的 attribute 和异常数据。 Attribute 键和值,以及记录的异常的
code、name、message和stack,都计入此限制。
span 达到数据限制后,运行时会忽略该 span 上后续的 setAttribute、setAttributes 和 recordException 调用。它会向 span 添加两个 attribute,以便你知道数据被丢弃:
| 属性 | 值 |
|---|---|
cloudflare.warning.type |
span_data_limit_exceeded |
cloudflare.warning.message |
被丢弃的 attribute 或异常的描述及其大小。 |
- 不支持手动设置父子关系。 父子关系由 JavaScript 异步上下文自动确定。
- 代码无法查看抽样决策。
span.isTraced和spanContext().traceFlags不会反映头部抽样。跟踪上下文也不会自动传播。请参阅已知限制。 - 仪表板不会显示 span 状态。
setStatus()设置的状态会包含在导出的跟踪中,但 Workers Observability 仪表板目前不会显示该状态,也无法按此状态查询或筛选。
其他追踪限制请参阅已知限制页面。