SuperAPI AI 工具集

maple-telemetry-conventions

通用与其它

查看项目

更新于 10-16 07:08

技能介绍

用途

Maple Telemetry Conventions 是 Maple 团队内部使用的一套 OpenTelemetry 约定参考,目标是在多语言代码库中保持遥测数据的一致性。它适用于 TypeScript(apps/api、packages/effect-sdk/ 下的 Cloudflare Workers)、Rust(apps/ingest)以及未来可能的 Python 服务。

这些约定是「承重」的:Tinybird 物化视图(MV)会预先将某些属性键抽取为列,仪表盘基于 Title Case 状态字符串做过滤,采样感知的吞吐量计算依赖 SampleRate 列。因此每一门语言都必须使用这里规定的精确属性拼写。

适用时机

  • 在任何代码路径中添加 setAttribute / Effect.annotateCurrentSpan / Span::current().record(...) / #[instrument(fields(...))]
  • 设置 span 状态(Ok / Error / Unset)
  • 通过 WarehouseQueryService.compiledQuery() 接入新查询(其 context 与 profile 选项会变成 span 属性)
  • 配置 OTLP exporter、tracer provider 或 resource builder
  • 引入新的预抽取 MV 列,或新增 maple.* 下的厂商属性
  • 审查涉及 apps/api/src/services/WarehouseQueryService.ts、apps/ingest/src/main.rs、apps/api/src/app.ts、packages/effect-sdk/src/cloudflare/、packages/domain/src/tinybird/materializations.ts 的 PR

规则文档索引

  • rules/span-attributes.md — Maple 发出的所有自定义属性键的主参考,按命名空间分组,并附 file:line 引用。
  • rules/status-and-kind.md — Title Case 状态码规则(Ok/Error/Unset)以及 span kind 约定(Server / Client / Internal)。
  • rules/resource-attributes.md — service.* 身份、deployment.environment.name 解析顺序、已弃用的 deployment.environment 双写与读取端合并,以及 maple_org_id。
  • rules/language-bindings.md — 并行给出 TypeScript / Rust / Python 代码片段,发出相同属性键。
  • rules/mv-first-class-columns.md — 说明哪些 span 与资源属性会被 Tinybird MV 预抽取为列(以及新增列的规则)。
  • rules/service-map-attribution.md — 服务地图渲染边、运行时图标与平台徽章所需的 span 与资源属性,包含规范的 peer.service 注册表。
  • rules/loop-prevention.md — 防止 Maple 自身流量形成反馈回路的三重防护:API TracerDisabledWhen、ingest 回环防护、采样。

快速参考

主题 规则
状态码 始终使用 Title Case:"Ok"、"Error"、"Unset"。绝不使用 OK、ERROR、SUCCESS、FAILED。
厂商命名空间 自定义属性放在 maple.* 下。子命名空间:maple.ingest.、maple.cloudflare.。
标准 semconv 逐字使用 OTel semconv 键:service.name、http.request.method、db.system.name、error.type。
组织身份 TypeScript span 中用 orgId(camelCase),Rust span 中用 maple.org_id(点号分隔)。在 MV 迁移前不要统一。
部署环境 发出 deployment.environment.name(同时双写已弃用的 deployment.environment)。通过 DEPLOYMENT_ENV_SQL / deploymentEnvExpr 读取两者,绝不使用裸 map 查找。
数仓 SQL span 来自 WarehouseQueryService.executeSql 的每个 span 都携带 db.system.name、peer.service、db.query.text、db.query.fingerprint、db.duration_ms、result.rowCount、orgId、query.context、query.profile。旧 span(2026-06 之前)使用 db.statement*/db.system;数仓读取端对两者做合并。
服务地图 出站 span 需要在 Client/Producer span 上带 peer.service(HTTP/RPC)或 db.system.name(DB)。资源属性需要 process.runtime.name、cloud.platform、maple.sdk.type,用于运行时图标与平台徽章。参见 rules/service-map-attribution.md。
回环防护 绝不移除 HttpMiddleware.TracerDisabledWhen(apps/api/src/app.ts:169-175)或 ingest 回环防护(apps/ingest/src/main.rs:499-514)。

规范引用(不要从本技能中修改)

  • apps/api/src/services/WarehouseQueryService.ts:441-510 — executeSql span 发出(TS 的规范示例)。
  • apps/ingest/src/otel.rs — Rust 的 Resource builder + 平台检测 + forward-span 助手,是 Rust 资源与出站 span 归因的规范示例。
  • apps/ingest/src/main.rs — handle_signal 与 handle_cloudflare_logpush(搜索带 otel.kind = "server" 的 tracing::info_span!)——用于 OTLP 入站的 Server-kind span 宏。
  • apps/api/src/app.ts:169-175 — TracerDisabledWhen 过滤器。
  • packages/effect-sdk/src/cloudflare/index.ts — MapleCloudflareSDK tracer 设置。
  • packages/domain/src/tinybird/materializations.ts — 将属性键预抽取为列的 MV SELECT 列表。

限制

本技能是 Maple 内部代码库相关的遥测约定参考,内容围绕其自身的服务、模块与 Tinybird 物化视图展开。除资料中给出的规则、路径与引用外,其他具体实现细节、配置参数、收费或版本信息暂未提供。