本技能是 @adobe/aio-lib-telemetry 的交互式安装配置指南，用途是在 Adobe App Builder 运行时动作中加入 OpenTelemetry 可观测性（追踪、指标、日志等信号）。它通过对话收集需求，再生成对应实现。
一、交互流程 引导会先确认缺失的输入：项目当前状态、使用的后端、希望采集的信号、是否集成 commerceEvents() 或 commerceWebhooks()、追踪链路是否需要向上下游延续，以及本地开发是否需要 Docker 或隧道。若用户已提供这些信息，则一次性生成实现。对于固定选项的问题，使用运行环境提供的可选问题工具；除非用户要求生成具体文件，否则按增量方式生成。
二、配置步骤 第 1 步：安装。执行 npm install @adobe/aio-lib-telemetry。 第 2 步：启用遥测。在 app.config.yaml 中为每个动作添加 ENABLE_TELEMETRY: true，或在 package 层级为所有动作统一添加。示例：runtimeManifest 下 packages 的 my-package 中 actions 的 my-action 在 inputs 中加入 ENABLE_TELEMETRY: true。资料特别强调：该环境变量未设为 true 时遥测会静默不生效，这是最常见的配置错误。 第 3 步：创建遥测配置。创建 telemetry.{ts,js} 文件。最小配置（尚无后端）使用 defineTelemetryConfig，配合 getPresetInstrumentations("simple") 与 getAioRuntimeResource()，设置 serviceName 等 sdkConfig。后端专属导出器配置需阅读相应参考：Grafana 见 references/grafana-backend.md，New Relic 见 references/new-relic-backend.md，其他 OTLP 后端可参照 Grafana 模式，替换为对应后端的 OTLP 端点 URL 与鉴权头。环境相关行为建议在同一个共享 defineTelemetryConfig 中通过 params 或 isDev 处理，拆分多个配置文件的情况较少。 第 4 步：为入口函数接入埋点。导入 instrumentEntrypoint 与 telemetryConfig，用 instrumentEntrypoint(main, telemetryConfig) 包裹原 main 函数并导出为 main。若使用集成，可合并进配置，例如 integrations: [commerceEvents()]，详见 references/integrations.md。放置方式只选一种：共享遥测配置或具体 instrumentEntrypoint。对于会调用另一个动作的 Commerce 处理器，应在处理器上使用 commerceEvents()，并在下游 OpenWhisk 调用中转发 contextCarrier，新代码中不要引入 x-telemetry-context 或 __telemetryContext。 第 5 步：动作内埋点（后续技能）。入口包裹后动作会生成 root span；更深入的埋点使用 aio-telemetry-instrument。至此基础安装完成，后续步骤为可选。
三、可选项 上下文传播（第 6 步）：当运行时动作调用其他已埋点服务（其他 App Builder 动作、外部 API、微服务或任何支持 W3C Trace Context 的系统）时需要。发送端通过 getInstrumentationHelpers() 的 contextCarrier 序列化上下文写入出站请求头；对 OpenWhisk 动作间调用，应把 carrier 放入 params 而非 HTTP 头。接收端：其他 App Builder 动作在使用 instrumentEntrypoint 且 carrier 在常规 params 或 headers 中时会自动提取，仅自定义 carrier 形态才用 propagation.getContextCarrier；具备 OTel 的外部服务会由其 SDK 自动提取 W3C 头；自定义方案则需自行从 headers 提取 traceparent/tracestate。手动传播、非 HTTP 场景或关闭传播详见 references/propagation.md。 本地开发（第 7 步）：如需在本地查看遥测数据，参考 references/local-dev-setup.md，其中涵盖 Docker LGTM 栈（一体化本地采集器与后端）、带隧道用于测试已部署动作的 Docker Compose，以及 isDev 条件配置模式。
四、埋点函数内可用助手 getInstrumentationHelpers() 返回：currentSpan（当前活动 span，可设属性、加事件）、contextCarrier（预序列化的 W3C 头，用于传播）、tracer（全局 tracer，用于创建自定义 span）、meter（全局 meter，用于创建自定义指标）、logger（与当前 trace 关联的自动配置日志器）。在未埋点函数中调用会抛错。
五、故障排查快速参考 完全无遥测：ENABLE_TELEMETRY 未设为 true。内部函数无 span：使用了 instrument 但函数未在 instrumentEntrypoint 上下文中被调用，见 aio-telemetry-instrument。跨服务链路未关联：出站头未发送 context carrier。信号偶发缺失：容器在 flush 完成前被关闭（已知限制）。启用诊断可设置 diagnostics: { logLevel: "debug" }。
六、参考文件 references/documentation-sources.md（原始 GitHub 文档路径与 OpenTelemetry JS 文档）、references/grafana-backend.md（配置 Grafana，Docker LGTM 或 Grafana Cloud 作为后端）、references/new-relic-backend.md（配置 New Relic 后端）、references/local-dev-setup.md（搭建本地可观测性栈、Docker Compose、隧道）、references/integrations.md（Adobe Commerce Events 与 Webhooks 集成）、references/propagation.md（服务间上下文传播、手动传播）、references/api-surface.md（完整 API 参考：函数、类型、导入）。
关于收费、价格、具体支持平台或效果表现，本资料暂未提供。