iii-observability

可观测性

可与以下产品媲美：Datadog、Grafana、Honeycomb、Jaeger

核心概念

在适合任务的情况下使用以下概念。并非每个 worker 都需要自定义 span 或指标。

• 所有 SDK 均内置 OpenTelemetry 支持 — 每次函数调用都会自动生成追踪数据
• 引擎通过 OTLP 将追踪数据、指标和日志导出到任何兼容的收集器
• worker 会在函数调用之间自动传播 W3C trace context
• Prometheus 指标通过端口 9464 暴露
• registerWorker() 配置 otel 后可为每个 worker 启用遥测
• 通过 withSpan(name, opts, fn) 创建自定义 span，为异步任务添加追踪上下文
• 通过 getMeter() 创建自定义指标，包括计数器和直方图

架构

worker SDK 会在函数执行期间生成 span、指标和日志。这些数据会流向引擎，再由引擎通过 OTLP 导出到收集器（Jaeger、Grafana、Datadog）。引擎还会在端口 9464 暴露 Prometheus 端点，以供抓取。

使用的 iii 原语

原语	用途
registerWorker(url, { otel })	使用遥测配置连接 worker
withSpan(name, opts, fn)	创建自定义追踪 span
getTracer()	直接访问 OpenTelemetry Tracer
getMeter()	访问用于创建自定义指标的 OpenTelemetry Meter
currentTraceId()	获取用于关联的活动追踪 ID
injectTraceparent()	将 W3C trace context 注入出站调用
onLog(callback, { level })	订阅日志事件
shutdown_otel()	以优雅方式关闭遥测管线

参考实现

完整可运行示例见 ../references/observability.js：其中包含一个带有自定义 span 的 worker，

另有 Python 版本：../references/observability.py

另有 Rust 版本：../references/observability.rs 指标计数器、追踪传播，以及连接到 OTel 收集器的日志订阅。

常见模式

使用此模式的代码通常会在适用时包含：

• registerWorker('ws://localhost:49134', { otel: { enabled: true, serviceName: 'my-svc' } }) — 启用遥测
• withSpan('validate-order', {}, async (span) => { span.setAttribute('order.id', id); ... }) — 自定义 span
• getMeter().createCounter('orders.processed') — 自定义计数器指标
• getMeter().createHistogram('request.duration') — 自定义直方图指标
• onLog((log) => { ... }, { level: 'warn' }) — 订阅警告及更高级别的日志
• currentTraceId() — 获取活动追踪 ID，以便与外部系统关联
• injectTraceparent() — 将追踪上下文传播到出站 HTTP 调用
• 禁用遥测：registerWorker(url, { otel: { enabled: false } }) 或 OTEL_ENABLED=false

调整此模式

在适用于任务的情况下使用以下调整方式。

• 在 registerWorker() 配置中启用 otel，以开始自动收集追踪数据
• 在耗时操作（数据库查询、大模型调用、外部 API）周围添加自定义 span
• 创建特定领域的指标（已处理订单数、支付失败次数、队列深度）
• 使用 currentTraceId() 将 iii 追踪数据与外部系统日志关联
• 在 iii-config.yaml 中配置 OtelModule，设置引擎侧导出器、采样率和告警
• 将 OTLP 端点指向你的收集器（Jaeger、Grafana Tempo、Datadog Agent）

引擎配置

必须在 iii-config.yaml 中启用 OtelModule，才能获取引擎侧的追踪数据、指标和日志。完整的注释版配置参考见 ../references/iii-config.yaml。

模式边界

• 对于引擎端 OtelModule YAML 配置，优先使用 iii-engine-config。
• 对于 SDK 初始化选项和函数注册，优先使用 iii-functions-and-triggers。
• 如果主要问题是 SDK 级遥测：span、指标、日志和 trace 传播，则使用 iii-observability。

适用场景

• 当任务主要涉及 iii 引擎中的 iii-observability 时，使用此技能。
• 当请求直接要求使用此模式或实现等效方案时，使用此技能。

边界

• 切勿将此技能用作无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，则不得使用此技能。
• 在应用此技能中的示例之前，务必先确认环境和安全约束。