iii 引擎可观测性实战基于 iii-observability Worker 的 OTel 追踪、日志、指标与告警指南【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iiiiii-observability是 iii 引擎内置的 OpenTelemetry 可观测性 Worker它以一组engine::*可调用函数加一个log响应式触发器的方式为引擎提供分布式追踪、结构化日志、带 rollup 的指标、告警规则、采样配置与 baggage 传播能力。阅读本篇后你将掌握该 Worker 的完整配置面含全部OTEL_*环境变量覆盖、OTLP 导出协议选择、九个函数子命名空间的具体用法以及如何在函数中实时响应日志事件如对error级别日志分页告警并理解其与pubsub、queue等独立 Compose Worker 的职责边界。一、Worker 概述与核心定位从 iii-observability SKILL.md 可以看到该 Worker 提供的可观测性能力全部面向「引擎内部可编程消费」设计发射通过engine::log::*发射结构化日志查询通过engine::logs::list、engine::traces::*、engine::metrics::list、engine::rollups::list读取已存储的遥测数据检查engine::sampling::rules、engine::health::check、engine::alerts::list用于运行态巡检响应log触发器在每条日志进入管道时触发对应函数实现零轮询的实时响应。其 Worker 声明文件 iii.worker.yaml 表明这是type: engine的内置 Worker由引擎自动注入不需要也不应该在config.yaml的engine.workers或项目containers:中显式声明。Worker 默认开启配置默认值见 config.rs 中的enabled: Some(true)当被显式禁用时发射与读取类函数仍会注册但退化为 no-op且log触发器永不触发。二、核心配置面与OTEL_*环境变量覆盖Worker 的完整配置在 README.md 中有明细表格下表整理了核心字段、默认值与环境变量覆盖字段类型说明默认值环境变量enabledboolean是否启用 OTel 追踪导出trueWorker 级默认OTEL_ENABLEDservice_name/service_version/service_namespacestringOTel resource 属性service.name/service.version/service.namespaceiii/ 引擎版本 / 无OTEL_SERVICE_NAME/SERVICE_VERSION/SERVICE_NAMESPACEexporterstring追踪导出器memory|otlp|bothmemoryOTEL_EXPORTER_TYPEendpointstringOTLP collector 基础端点http://localhost:4317OTEL_EXPORTER_OTLP_ENDPOINTsampling_rationumber全局追踪采样率0.0–1.01.0OTEL_TRACES_SAMPLER_ARGmemory_max_spansnumber内存保留的最大 span 数1000OTEL_MEMORY_MAX_SPANSmetrics_enabled/metrics_exporterboolean / string指标采集开关与导出器memory|otlpfalse/memoryOTEL_METRICS_ENABLED/OTEL_METRICS_EXPORTERmetrics_retention_seconds/metrics_max_countnumber指标内存保留时长与点数上限3600/10000OTEL_METRICS_RETENTION_SECONDS/OTEL_METRICS_MAX_COUNTlogs_enabled/logs_exporterboolean / string结构化日志存储开关与导出器memory|otlp|bothtrue/memoryOTEL_LOGS_EXPORTERlogs_max_count/logs_retention_seconds/logs_sampling_rationumber日志内存上限、保留时长、保留比例1000/3600/1.0—logs_console_outputboolean是否将摄入日志打印到控制台true—levelstring最小日志级别trace|debug|info|warn|errorinfo—formatstring日志输出格式default|jsondefault—alertsAlertRule[]针对指标的告警规则[]—字段的实际序列化与校验逻辑定义在 config.rs 中顶层配置结构体ObservabilityWorkerConfig标注了#[serde(deny_unknown_fields)]未知字段会在configuration::set时被 JSON Schema 拒绝sampling_ratio、logs_sampling_ratio等比率字段被#[schemars(range(min 0.0, max 1.0))]约束在0..1memory_max_spans、metrics_max_count等计数字段下限为 1。1.enabled默认值的两处口径需要注意README 配置表中enabled字段标注默认false对应 serde 的Option::None语义而 config.rs 的 Default 实现 在 Worker 自动注入且无config:块时使用enabled: Some(true)。因此实际行为是Worker 默认开启SKILL.md 中的「The worker is on by default (enabled: true)」即指此默认值。手动在config.yaml的对应配置块中显式设置enabled: false才会关闭。2. 配置的持久化与${VAR:default}占位符配置以iii-observability为 id 注册到内置configurationWorker见 configuration.rs 的CONFIG_ID存储的配置项是运行时的事实来源。首次启动时用config.yaml配置块或默认值做 seed之后仅当无存储值时才写入initial_value因此运行时编辑能跨引擎重启存活。使用默认的文件后端时配置持久化在./config/iii-observability.yaml每次引擎启动在日志/追踪初始化之前都会重新读取——这也意味着即使是「仅重启生效」的字段编辑后下次启动即可生效。字符串字段支持${VAR:default}占位符读取时展开。一个典型例子是 config.rs 默认值 中的service_version: ${SERVICE_VERSION:__III_ENGINE_VERSION__}seed 保留模板形态configuration::get读取时再按进程环境展开为实际引擎版本with_env_expanded方法会执行同样的展开见 config.rs。3. 越界值的归一化由于存储在磁盘上的条目可能早于 schema 收紧或被人手编辑每次读取都会经过normalized()config.rs比率被钳制到0..1零值计数回退为内置默认None避免创建零容量存储。若持久化值严重越界导致启动时 schema 刷新失败会以SCHEMA_INVALID错误 warn-and-continue读取仍可用。三、OTLP 传输gRPC 默认、HTTP/protobuf 可选、鉴权头追踪与指标默认走OTLP/gRPChttps://端点启用 TLS使用系统根证书http://端点使用明文传输。要改用 OTLP/HTTP protobuf在启动引擎前设置标准协议环境变量export OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf按信号分别覆盖信号级优先级更高export OTEL_EXPORTER_OTLP_TRACES_PROTOCOLgrpc export OTEL_EXPORTER_OTLP_METRICS_PROTOCOLhttp/protobuf当选择 HTTP/protobuf 时endpoint被视作 collector 基础 URLiii 会自动追加信号路径traces →/v1/tracesmetrics →/v1/metrics日志导出器固定走 OTLP/HTTPPOST 到/v1/logs。需要鉴权或路由头时使用标准 OTLP 头环境变量export OTEL_EXPORTER_OTLP_HEADERSAuthorizationBearer $OTLP_TOKEN信号级头变量OTEL_EXPORTER_OTLP_TRACES_HEADERS、OTEL_EXPORTER_OTLP_METRICS_HEADERS、OTEL_EXPORTER_OTLP_LOGS_HEADERS。日志导出器优先读OTEL_EXPORTER_OTLP_LOGS_HEADERS未设置时回退到OTEL_EXPORTER_OTLP_HEADERS。凭据务必放在环境变量或密钥管理器中不要提交进配置文件。生产环境如果既要导出到外部 collector、又要保持 iii Console 可查询应使用exporter: both追踪与logs_exporter: both日志——这也正是 README 的明确建议。四、配置热更新按字段分层的生效策略配置通过configuration:updated事件热应用README.md 给出了按字段分层的生效策略这是运维排障时的关键参考分层字段生效方式Live实时logs_console_output、logs_sampling_ratio、logs_enabled摄入闸门、enabled摄入闸门立即生效按使用点读取Limits限额memory_max_spans、logs_max_count、metrics_max_count、metrics_retention_seconds立即生效在下一次插入或 60s 清扫时执行Swap交换sampling_ratio、sampling.*、alerts、collapse_spans、level立即生效编译产物重建并交换存活的告警规则保持冷却/触发连续性Task rebuild任务重建logs_exporter、logs_batch_size、logs_flush_interval_ms、logs_retention_seconds以及logs_enabled的 false→true 切换后台任务以新设置重启logs_enabled从 false 切到 true 会复活日志存储、重建log触发器订阅者、OTLP 日志导出器与保留任务无需重启引擎Restart-only仅重启exporter、endpointtrace 与 logs 导出器、service_name/service_version/service_namespacetrace resource 与 logs 导出器身份、format、metrics_enabled、metrics_exporter、enabled管道构建记录 warning下次引擎启动通过持久化条目生效其中endpoint/service_name/service_version对所有信号都是仅重启层级目的是让 logs 与 traces 始终一起迁移到新 collector/身份避免编辑过程中出现分裂。底层实现上configuration.rs 的on_config_change处理函数会忽略触发器载荷、在 apply 锁下重新拉取权威配置值——这样任何调用方都不能仅凭发送 payload 就重定向遥测超时失败会延迟 5 秒重试一次其余失败保持旧配置。已知局限引擎配置文件重载若销毁并重建本 Worker会关闭 OTLP trace/metric provider 而不重建它们是进程级 set-once 状态此时 OTLP 导出需要引擎重启内存后端不受影响。五、何时使用与边界约束SKILL.md 明确列出了适用场景与边界避免误用适用场景在函数内部发射结构化日志、或读回已存储的日志/span/指标而不是 shell 出去调 collector对日志实时响应错误分页、全量归档而无需轮询运维巡检引擎健康、活跃采样规则或告警状态跨调用传播 OpenTelemetry baggage。边界约束来自 SKILL.mdengine::baggage::set不会向调用方回传——baggage 传播发生在 SDK/调用层通过 header内存查询函数logs、traces只有在配置了memory或both导出器时才有数据otlp-only 时数据在 collector 里logs_enabled关闭时日志管道休眠log触发器永不触发摄入时的level决定存储的最小严重级别本 Worker 只负责观察遥测不是通用事件总线那是pubsub也不是持久队列那是queue——后两者是独立的 Compose Worker。六、engine::*函数全览所有可调用函数在 mod.rs 中通过#[function(...)]宏注册九个子命名空间完整清单如下对应 SKILL.md 的 Functions 章节日志发射Logging函数说明engine::log::info/warn/error/debug/trace按命名级别发射日志输入形状相同仅级别不同以 mod.rs 的注册代码 为例每个级别映射到固定的 OTel severityTRACE1、DEBUG5、INFO9、WARN13、ERROR17。输入统一为OtelLogInputmessagestring必填、dataobject、trace_idstring、span_idstring、service_namestring。当logs_enabled为 false 或命中logs_sampling_ratio丢弃时函数是 no-op。日志查询Logs API函数说明engine::logs::list读取已存储的 OTel 日志可按时间、trace 关联或严重级别过滤engine::logs::clear清空内存日志存储logs::list支持过滤器start_time、end_time、trace_id、span_id、severity_min、severity_text、offset、limit。追踪查询Traces API函数说明engine::traces::list每条 trace 返回一条紧凑摘要子 span 贡献聚合状态/计数支持search_all_spans全 span 搜索与attribute_projection属性投影engine::traces::spans返回完整 span 记录含 attributes、events、links供详情/时间线消费engine::traces::tree将单条 trace 还原为父子层级树trace_id必填engine::traces::group_by按属性值聚合已存储 span各组计数、时长、错误数engine::traces::clear清空已存储 spantraces::list的输入结构mod.rs还包含statuserror/pending/ok/unset、min_duration_ms/max_duration_ms、start_time/end_time、sort_bystart_time/duration/service_name/name、sort_order、attributes/exclude_attributes过滤、include_internal是否包含engine.*内部 trace等。traces::group_by额外支持since_ms、label_attribute将某属性的值作为分组的可读label重命名会自动反映为最新值。指标与 rollupMetrics API函数说明engine::metrics::list列出带聚合统计的指标含引擎计数器invocations、workers、performance、SDK 指标以及可选的时间分桶聚合engine::rollups::list列出指标 rollup 聚合1 分钟、5 分钟、1 小时窗口其他 APIbaggage / sampling / health / alerts函数说明engine::baggage::get从当前 trace 上下文读取单个 baggage 值engine::baggage::get_all读取全部 baggage 键值对engine::baggage::set在当前 trace 上下文设置 baggage 值不回传调用方见上文边界engine::sampling::rules列出当前生效的采样规则engine::health::check返回引擎健康状态status、components、timestamp、versionengine::alerts::list列出已配置的告警规则与当前状态engine::alerts::evaluate手动触发一轮告警评估从源码实现看mod.rsbaggage 三个函数是「诊断用途」baggage::get/get_all读取的是当前进程上下文的 baggage而非逐次调用的 baggagebaggage::set由于 OTel baggage 不可变只在新 Context 上设置且不会传播回调用方其返回的note字段明确提示「For propagation, use SDK-level baggage headers.」——真正的跨服务传播要靠 SDK 层的 header。七、log响应式触发器零轮询实时响应日志log触发器在每一条日志进入引擎 OTel 日志管道时触发绑定函数——无论日志来自engine::log::*、OTLP 摄入还是任何使用结构化日志的 Worker。每个订阅者收到的是同一份 OTel 形状的记录因此处理器可以按严重级别、属性或 trace 关联路由。适用场景特定严重级别典型是error需要分页人工、发 Slack 或开 ticket把日志条目实时 fan-out 到下游 sink归档、分析、转换而不轮询engine::logs::list。若只是按需查询已存储条目则用engine::logs::list。绑定步骤与代码示例注册处理器iii.registerFunction(monitoring::on-error, handler)注册触发器SKILL.md 中的 TypeScript 示例iii.registerTrigger({ type: log, function_id: monitoring::on-error, config: { level: error, // optional. trace|debug|info|warn|error. Omit to fire on every level. }, });level是可选的省略则所有级别都触发指定后按该最小严重级别过滤。触发器仅在日志管道启用时触发处理器返回值被忽略每次条目存储后异步触发调用。README 提供了更完整的实战示例README.mdconst fn iii.registerFunction(monitoring::onError, async (logEntry) { await sendAlert({ message: logEntry.body, severity: logEntry.severity_text, traceId: logEntry.trace_id, }); return {}; }); iii.registerTrigger({ type: log, function_id: fn.id, config: { level: error }, });日志条目负载字段README.mdtimestamp_unix_nano、observed_timestamp_unix_nano、severity_number、severity_text、body、attributes、trace_id、span_id、resource、service_name、instrumentation_scope_name、instrumentation_scope_version。要查看触发类型或处理函数的完整 OTel 记录形状可运行iii get function info。实现上触发器类型常量LOG_TRIGGER_TYPE log与订阅者管理器OtelLogTriggers定义在 mod.rs订阅者在logs_enabled的 false→true 切换时会被重建配合上文的热更新分层。八、告警规则AlertRule 字段与动作类型告警规则结构体AlertRule定义在 config.rs字段如下字段类型说明namestring必填唯一规则名metricstring必填要监控的指标名如iii.invocations.errorthresholdnumber必填阈值operatorstring比较算子默认greaterthanwindow_secondsnumber评估时间窗口秒默认60cooldown_secondsnumber两次触发的最小间隔秒默认60enabledboolean规则是否激活默认trueactionAlertAction{ type: log }、{ type: webhook, url: ... }或{ type: function, path: ... }算子命名有讲究JSON Schema 只对外公布规范小写名greaterthan、greaterthanorequal、lessthan、lessthanorequal、equal、notequalconfiguration::set按 schema 校验远程编辑必须用这些规范名而config.yaml中作为 serde 便利还接受符号别名、、、、、!见 config.rs 的注释与别名定义。config.rs 的单测 专门断言 schema 的 enum 只含规范名、不含。AlertOperator::evaluateconfig.rs对equal/notequal使用f64::EPSILON容差比较。README 给出一个完整配置示例可通过configuration::set提交{ function_id: configuration::set, payload: { id: iii-observability, value: { enabled: true, service_name: my-service, service_version: 1.0.0, exporter: memory, metrics_enabled: true, logs_enabled: true, memory_max_spans: 1000, sampling_ratio: 1.0, alerts: [ { name: high-error-rate, metric: iii.invocations.error, threshold: 10, operator: greaterthan, window_seconds: 60, action: { type: log } } ] } } }九、高级采样规则、父级采样与限流除了全局sampling_ratio还可以用sampling块做精细控制README 示例sampling: default: 1.0 parent_based: true rules: - operation: api.* rate: 0.1 rate_limit: max_traces_per_second: 100对应结构体为 config.rs 中的 SamplingConfig / SamplingRule / RateLimitConfigsampling.default未命中任何规则时的默认采样率sampling.parent_based是否启用父级采样继承父 span 的采样决策sampling.rules[]按operation支持api.*通配符或service模式匹配的规则rate取值0.0–1.0按声明顺序求值sampling.rate_limit.max_traces_per_second全局每秒最大 trace 数限流。运行时由 sampler.rs 中的 AdvancedSampler 实现规则先被编译为CompiledRule命中规则则按should_sample_by_ratio采样之后若有rate_limiter令牌桶TokenBucket还要再经过每秒限流闸门。可以用engine::sampling::rules检查当前生效的规则。另外trace 树视图还支持collapse_spansSpanCollapseRule见 config.rs按 span 名模式如trigger *隐藏冗余的透传包装 span并把其子 span 重挂到最近的幸存祖先保持树连通——不修改 Worker 代码即可让 trace 视图更清爽。十、Livependingspans实时追踪视图memory导出器本地开发默认下span 在开始的瞬间就会被镜像为内存存储中的 pending 快照live_spans字段memory默认开启、both需显式live_spans: true或OTEL_LIVE_SPANStrue在生产环境开启、otlp-only 永不镜像。pending 快照以pending: true与end_time_unix_nano: 0标记只携带创建时已知的属性span 宏字段 baggage 印记的iii.*属性所以status读作unsetspan 关闭时最终 span原地替换快照同一存储位置每个 span id 一条记录。这一机制让 live 追踪视图能展示进行中的工作引擎侧父 spantrigger fn、enqueue、builtincall fn在子工作仍在运行时即可见trace 一启动就出现在列表视图中。OTEL 合规性pending 快照只存在于内存存储及其查询视图与 trace 触发器 tickOTLP 导出路径永不出现未完成 span——end_time_unix_nano在 OTLP 线上是语义必需字段。消费方应将pending: true或end_time_unix_nano 0视为「仍在运行」时长过滤与排序按已运行时长度量engine::metrics::list会把它们排除在延迟统计之外。十一、源码地图与延伸阅读Worker 技能文档本文主体engine/src/workers/observability/skills/SKILL.md详细配置表、热更新分层、函数与触发器全量文档engine/src/workers/observability/README.md配置结构体、默认值、告警/采样/span 折叠规则定义engine/src/workers/observability/config.rsconfiguration Worker 集成注册、读取、热应用engine/src/workers/observability/configuration.rs全部engine::*函数注册与log触发器实现engine/src/workers/observability/mod.rs高级采样器规则编译 令牌桶限流engine/src/workers/observability/sampler.rsOTel 初始化与全局配置管理engine/src/workers/observability/otel.rsWorker 声明engine/src/workers/observability/iii.worker.yaml综上iii-observability把 OpenTelemetry 的发射、存储、查询与实时响应全部收敛为引擎内可编程的engine::*函数与log触发器配合OTEL_*环境变量覆盖、按字段分层的热更新与高级采样/告警能力开发者可以在不额外部署 collector 基础设施的前提下memory/both导出器获得完整且可查询的可观测性闭环并在需要时平滑接入标准 OTLP 生态。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考