进阶 celld.dev 2026-10-11 10:08:47 · 37 阅读

第4章 Telemetry(遥测)配置与数据记录机制

第4章 Telemetry(遥测)

文档 · Telemetry

celld 可以记录其处理请求的 trace 和日志。遥测默认关闭,关闭时不产生任何开销。设置 CELLD_OTEL=1 会把 Parquet 文件写入 fleet bucket 的 telemetry/ 前缀下,DuckDB 可以直接查询;设置 CELLD_OTEL=http://collector:4318 则把同样的数据发送到 OpenTelemetry collector。

数据模式版本为 v0-unstable,在正式版发布前列名可能变动。每个文件的元数据字段 celld-schema 中带有版本号(在 az:// bucket 上字段名为 celld_schema)。

配置

| 变量 | 默认值 | 说明 | |---|---|---| | CELLD_OTEL | 0 | 0 表示关闭遥测;1 表示把 Parquet 写入 fleet bucket;设置为 HTTP(S) collector 的 base URL 则使用 OTLP/HTTP protobuf。 | | CELLD_OTEL_BUCKET | fleet bucket | 为 Parquet 文件指定另一个 bucket,使用相同的 endpoint 和凭证。 | | CELLD_OTEL_RETENTION | 30d | celld 会删除超过该时限的遥测文件。设为 none 则不删除,由你自己的生命周期规则管理数据。 | | CELLD_OTEL_FLUSH_MS | 300000 | 缓冲事件累积到该毫秒数后写出一个 Parquet 文件。 | | CELLD_OTEL_FLUSH_BYTES | 5242880 | 缓冲事件的估算字节数达到该值时,提前触发落盘。 | | OTEL_TRACES_SAMPLER | parentbased_always_on | 标准 sampler 名称。配合 OTEL_TRACES_SAMPLER_ARG 使用 traceidratio 可按比例采样。 | | OTEL_EXPORTER_OTLP_HEADERS | 未设置 | 发送给 collector 的 name=value 请求头,逗号分隔。 | | OTEL_EXPORTER_OTLP_TIMEOUT | 10000 | collector 请求超时时间,单位毫秒。 | | OTEL_SERVICE_NAME | celld | 导出 resource 中的服务名称。 |

bucket sink 需要 CELLD_BUCKET,OTLP sink 则不需要。collector URL 不能带 query 或 fragment,celld 会在路径后追加 /v1/traces 和 /v1/logs,并忽略 OTEL_EXPORTER_OTLP_ENDPOINT。

CELLD_OTEL_SINK 已被移除,设置了该变量的节点无法启动。请把 collector base URL 写入 CELLD_OTEL,或者保留 CELLD_OTEL=1 使用 bucket。

celld 记录哪些内容

celld 会为以下内容记录 span:每个无状态 Worker 请求、每个 cell 事件(fetch、alarm、RPC、WebSocket 消息)、每次出站 fetch(),以及每次 cell 启动。span 中包含请求 id、cell、isolate、排队等待时间、出站 URL 及状态码,以及已知的持久化事实。

每条 console.log 都会成为一条日志记录,带上其 handler 的 trace id 和 span id,并跨越 await 保持关联。console 方法的严重级别记录在 severity_number 和 severity_text 中(分别是 OTLP 字段和 Parquet 列)。body 中只保存消息本身。

| 方法 | severity number | severity text | |---|---|---| | console.debug | 5 | DEBUG | | console.log、console.info | 9 | INFO | | console.warn | 13 | WARN | | console.error | 17 | ERROR |

早期 celld 版本的日志文件没有 severity 列,可用 union_by_name = true 混合读取不同版本。

celld 会读取入站请求中的 W3C traceparent 头,并在出站 fetch() 中透传。头格式错误时会开启新 trace。Worker 调用 Durable Object 属于同一 trace。

sampler 在请求开始时决定是否采样,未采样的请求不记录任何内容。比率为 0 时不记录任何 trace,为 1 时全部记录。中间值则在每个节点上对相同 trace id 做出相同判断。即使入站上下文有效但被 sampler 拒绝,celld 也会保留它:出站 fetch() 或 Durable Object 调用会沿用原 trace id、使用新的 span id,并保持 sampled 标志为未采样。

高负载时,遥测会先于请求被削减,celld 会统计削减量。celld 目前不记录 metrics。

用 DuckDB 查询 bucket

INSTALL httpfs; LOAD httpfs; CREATE SECRET celld_telemetry ( TYPE s3, KEY_ID '...', SECRET '...', ENDPOINT 's3.example.com', URL_STYLE 'path' ); CREATE VIEW traces AS SELECT * FROM read_parquet('s3://YOUR-BUCKET/telemetry/traces/*/*/*/*/*/*.parquet'); CREATE VIEW logs AS SELECT * FROM read_parquet('s3://YOUR-BUCKET/telemetry/logs/*/*/*/*/*/*.parquet');

-- 最慢的请求。 SELECT name, duration_us, trace_id FROM traces ORDER BY duration_us DESC LIMIT 20;

-- 错误日志。 SELECT time_unix_us, body FROM logs WHERE severity_number >= 17;

-- 每条日志,关联到产生它的 span。 SELECT l.body, t.name, t.duration_us FROM logs l JOIN traces t ON l.trace_id = t.trace_id AND l.span_id = t.span_id;

非 AWS 的 S3 兼容 endpoint 需要 URL_STYLE 'path';纯 HTTP 的 endpoint 还需要 USE_SSL false。

文件按节点和小时分区:telemetry/traces////

//.parquet。

落盘与投递

celld 每次落盘写一个 Parquet 文件,触发条件是 5 分钟(CELLD_OTEL_FLUSH_MS=300000)或缓冲事件估算达到 5 MiB(CELLD_OTEL_FLUSH_BYTES=5242880),以先到者为准。触发落盘的那个事件可能会让这批数据略微超出阈值。

如果没有运行压缩任务,建议保持默认值。默认值产出较大的文件,但数据最多可能延迟 5 分钟到达。CELLD_OTEL_FLUSH_MS=5000 可改为 5 秒间隔(再加上上传或 collector 的延迟)。间隔过短会产生大量小文件,几小时内就会拖慢查询,所以应先启动压缩任务。如需近乎实时的视图,可使用 OTLP sink 并配合同样的短间隔。

OTLP sink 在遇到瞬时故障(HTTP 408、429、502、503 或 504)时,每批最多重试 5 次,采用带抖动的指数退避并遵循 Retry-After,每次延迟上限 30 秒。被永久拒绝则丢弃该批数据。

exporter 同时只持有一个重试中的批次,输入通道可容纳 8192 个新事件。通道满时,celld 会丢弃并统计新的遥测数据,请求处理不受影响。

保留期清理在启动时运行,之后每完成一次清理,6 小时后再次运行。

压缩

celld 不会自己压缩文件。请在维护节点上每小时运行一次压缩任务,处理刚结束的那个小时。不要压缩当前小时,因为节点仍在向其中写入。

COPY ( SELECT * FROM read_parquet('s3://YOUR-BUCKET/telemetry/traces//2026/08/09/22/*.parquet') ORDER BY start_unix_us ) TO 's3://YOUR-BUCKET/telemetry/traces//2026/08/09/22/compacted.parquet' (FORMAT parquet, COMPRESSION zstd);

DuckDB 写出压缩文件后,再删除源文件。

本篇用到的工具

评论 (0)