iii-observability 是 iii 引擎的可观测性 worker，基于 OpenTelemetry 提供分布式追踪、结构化日志、带汇总的指标、告警规则、采样配置与 baggage 传播。每个能力面都是可调用的 engine::* 函数，另有一个日志响应式触发器，在每条写入的日志条目上触发。函数覆盖九个命名空间，用于发出、查询已存储的遥测数据、检查配置以及传播上下文。
用途
- 在函数内部发出结构化日志，或读回已存储的日志、span、指标，而不必调用外部 collector。
- 实时响应日志条目（例如错误告警、全量归档），无需轮询。
- 运维性地检查引擎健康、当前采样规则或告警状态。
- 跨调用传播 OpenTelemetry baggage，用于横切上下文。
主要能力
日志：engine::log::info、engine::log::warn、engine::log::error、engine::log::debug、engine::log::trace 按对应严重级别发出日志条目，输入结构相同，仅级别不同。engine::logs::list 读取已存储的 OTel 日志，可按时间、trace 关联或严重级别过滤；engine::logs::clear 清空内存日志存储。
追踪：engine::traces::list 列出紧凑的 trace 摘要，含聚合状态/计数与可选属性投影；engine::traces::spans 列出完整 span 记录，供详情/时间线消费；engine::traces::tree 以父子树形式遍历单个 trace；engine::traces::group_by 按属性值聚合已存储 span（每组计数、时长、错误）；engine::traces::clear 清空已存储 span。
指标与汇总：engine::metrics::list 列出指标及聚合统计，可选时间分桶；engine::rollups::list 列出 1 分钟、5 分钟、1 小时窗口的指标汇总聚合。
Baggage：engine::baggage::get、engine::baggage::get_all 读取单个或全部 OpenTelemetry baggage 键；engine::baggage::set 在本地设置 baggage 键（不会传播回调用方）。
采样、健康与告警：engine::sampling::rules 列出当前生效的采样规则；engine::health::check 返回引擎健康状态（状态、各组件明细、版本）；engine::alerts::list 检查已配置的告警规则与当前状态；engine::alerts::evaluate 手动执行一次告警评估。
响应式触发器
当函数需要在每次日志条目进入引擎 OTel 日志管道时运行时，可绑定日志触发器。日志来源包括通过 engine::log::* 发出、通过 OTLP 摄入，或任何使用结构化日志的 worker 记录。每个订阅收到相同的 OTel 形状记录，处理程序可按严重级别、属性或 trace 关联进行路由。
适用场景：特定严重级别（通常是 error）需要通知人工、发到 Slack 或开单；希望将日志条目实时扇出到下游 sink（归档、分析、转换），而不轮询 engine::logs::list。若需要按需查询已存储条目而非逐条响应，应使用 engine::logs::list。
绑定方式：先注册处理函数 iii.registerFunction('monitoring::on-error', handler)，再注册触发器 iii.registerTrigger({ type: "log", function_id: "monitoring::on-error", config: { level: "error" } })。level 可选，取值 trace|debug|info|warn|error，省略则在所有级别触发。日志触发器仅在日志管道启用时触发，level 过滤到该最低严重级别。处理函数的返回值被忽略；每次条目存储后异步派生调用。OTel 日志记录形状可通过 iii get function info 查询触发器类型或处理函数 id 获取。
配置与导出
worker 默认启用（enabled: true）。禁用后 emit 与读取函数仍注册但变为空操作，触发器不再触发。核心配置：service_name/service_version/service_namespace（OTel 资源属性）、exporter（memory | otlp | both）、endpoint（OTLP collector URL，默认 http://localhost:4317）、sampling_ratio（0.0–1.0）、memory_max_spans，以及各支柱的开关/上限（metrics_enabled、logs_enabled、保留与数量上限）。多数字段接受 OTEL_* 环境变量覆盖。内存查询函数（logs、traces）需要 memory 或 both exporter。
追踪与指标默认使用 OTLP/gRPC；https:// 端点启用 TLS，http:// 端点使用明文。设置 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf 可对追踪与指标使用 OTLP/HTTP protobuf，或用 OTEL_EXPORTER_OTLP_TRACES_PROTOCOL / OTEL_EXPORTER_OTLP_METRICS_PROTOCOL 做信号级覆盖。当配置的端点是基础 collector URL 时，HTTP/protobuf 路径会自动追加（/v1/traces、/v1/metrics）。日志通过 OTLP/HTTP 导出到 /v1/logs。
collector 头可使用 OTEL_EXPORTER_OTLP_HEADERS，必要时使用信号级 OTEL_EXPORTER_OTLP_TRACES_HEADERS、OTEL_EXPORTER_OTLP_METRICS_HEADERS 或 OTEL_EXPORTER_OTLP_LOGS_HEADERS。日志导出器优先读取 OTEL_EXPORTER_OTLP_LOGS_HEADERS，回退到 OTEL_EXPORTER_OTLP_HEADERS。凭据应放在环境变量或密钥管理器中，不要写入配置文件。
限制
- engine::baggage::set 不会传播回调用方；baggage 传播发生在 SDK/调用层，通过 headers 完成。
- 除非配置了 memory（或 both）exporter，否则内存查询函数不会返回有用数据；仅 otlp 时数据位于你的 collector 中。
- logs_enabled 关闭时日志管道休眠，日志触发器永不触发；摄入级别决定存储的最低严重级别。
- 该 worker 用于观测遥测，不是通用事件总线（pubsub）或持久队列（queue）；后两者是独立的 Compose worker。