用途
本技能用于排查 Adobe App Builder 运行时 action 中 @adobe/aio-lib-telemetry 的遥测问题。当用户报告遥测不工作、没有数据、数据不完整、出现错误或数据异常时，可借助本技能进行交互式诊断。
核心原则
@adobe/aio-lib-telemetry 主要把 sdkConfig 转发给 OpenTelemetry 的 NodeSDKConfiguration。应直接校验配置结构，尤其是在没有类型检查的 JavaScript 项目中。
使用方式
不要一上来就翻代码库。先通过对话理解用户的问题，收集足够上下文后再做有针对性的代码检查。对于固定选项的问题，使用运行时的可选问题工具。
阶段一：分诊
请用户描述问题，了解：症状（完全没有数据、部分数据、报错、数据错误）、发生了什么变化（新搭建、之前正常、部署后、改配置后）、环境（本地 aio app dev 还是部署到 I/O Runtime）、后端（Grafana/Docker LGTM、New Relic、Grafana Cloud 或其他 OTLP）。
先检查常见快速问题：app.config.yaml 的 inputs 中是否设置 ENABLE_TELEMETRY: true（这是“完全不工作”的首要原因）；入口是否被包装（export const main = instrumentEntrypoint(handler, { ...telemetryConfig })）；sdkConfig 中是否至少配置了一个 exporter（traceExporter、metricReaders 或 logRecordProcessors）。如果用户有错误信息，可在 references/error-messages.md 中查找确切原因和修复方法。
阶段二：收集证据
尽早获取诊断信息。若未启用诊断，请用户在遥测配置中加入 diagnostics: { logLevel: "debug" } 并重新运行，详见 references/diagnostics-guide.md。
获取 activation 日志：尽可能自行检索，先找到 activation（向用户要 activation ID，或用 aio rt activation list 帮助识别），再运行 aio rt activation logs <activation_id> 分析输出。若日志不可用，用 aio app config get log-forwarding 检查日志转发，或退回到代码、配置、错误信息和后端证据。
添加临时日志：在关键点加 console.log 验证执行顺序；记录（脱敏后的）参数验证环境变量是否到达 action；记录 exporter 配置验证 URL 和请求头；添加 getLogger() 调用追踪数据流。加完后让用户触发 action 并分享输出，问题解决后移除这些日志。
校验配置：阅读用户代码时，始终对照已知 schema 校验配置。许多问题来自静默失败的无效配置，尤其是没有类型检查的纯 JS 用户。用 references/config-validation.md 检查：导入路径（只存在 @adobe/aio-lib-telemetry、/otel 和 /integrations）；导入名称（是否导入了实际存在的东西，例如 OTLPTraceExporterProto 而非 OTLPTraceExporter）；配置结构（defineTelemetryConfig 是否返回 { sdkConfig: { ... } } 而非扁平属性）；sdkConfig 属性（是否只有有效的 NodeSDKConfiguration 属性，没有臆造的键）；信号接线（metrics 需要 reader 包装 exporter，logs 需要 processor 包装 exporter，traces 直接接收 exporter）；app.config.yaml（ENABLE_TELEMETRY、用 $VAR_NAME 映射环境变量）。若配置无效，很可能就是根因。说明问题所在，展示正确结构；若是重大搭建问题，可提及 aio-telemetry-setup 技能帮助重新开始。
定向阅读代码：在理解症状后，再阅读遥测配置（defineTelemetryConfig 调用）、app.config.yaml（环境变量、ENABLE_TELEMETRY）、入口（instrumentEntrypoint 包装）、exporter 配置（URL、认证请求头）。
阶段三：诊断
将发现与 references/common-scenarios.md 中的已知场景匹配：完全没有数据（ENABLE_TELEMETRY、缺少 exporter、URL 错误、认证失败）；无效配置（属性错误、嵌套错误、不存在的导入）；部分信号（一个 exporter 配置错误而其他正常）；本地正常但部署后不正常（exporter 指向 localhost、缺少环境变量）；链路断裂（服务间未设置上下文传播）；热重载异常（重启开发服务器）；间歇性数据丢失（关闭时机）；本地搭建问题（Docker 未运行、隧道断开、端口被占、隧道 URL 过期）。
本地搭建排查：Docker 容器是否运行（docker ps | grep otel-lgtm）；collector 是否可达（curl -s -o /dev/null -w "%{http_code}" http://localhost:4318/v1/traces，应返回 200 或 405）；隧道是否存活（查看隧道容器日志，如 docker logs cloudflared 或 docker logs ngrok）；隧道 URL 是否最新（隧道重启后确认配置指向新 URL）；端口冲突（其他服务可能占用 3000、4317 或 4318）。对于超出基本连通性的隧道问题（Cloudflare 账户问题、ngrok 限制等），引导用户查阅相应工具的文档或支持渠道。
用诊断做根因分析：诊断输出会说明发生了什么——SDK 是否启动（查找“OpenTelemetry automatic instrumentation started successfully”）；是否有错误（error 级别消息含根因）；exporter 问题（debug 级别下 OTel 记录 HTTP 请求，查找 connection refused、401、429、超时）；关闭是否完成（“shutdown successful”表示数据已刷新）。
阶段四：修复或升级
给出具体修复。若是搭建问题（缺少配置、结构错误），说明问题所在，并建议 aio-telemetry-setup 技能帮助从头正确搭建。若某个 OTel SDK 选项不清楚，查阅 references/documentation-sources.md。
谨慎升级（最后手段，而非第一反应）：升级前先排除瞬时故障、本地环境问题和一次性故障。只有在配置、代码和本地环境检查都已穷尽后才升级：后端提供商支持（New Relic、Grafana、Splunk）——配置已验证但数据仍不到达或后端特定功能失败；Adobe 支持——运行时问题，如环境变量未到达 action、日志转发未生效，或与代码无关的可重复部署失败；在 @adobe/aio-lib-telemetry 上提 GitHub issue——未记录的库错误或可复现但未按描述工作的功能。库和 OpenTelemetry 文档来源见 references/documentation-sources.md。
参考资料
references/documentation-sources.md：原始 GitHub 文档路径和 OpenTelemetry JS 文档。references/config-validation.md：校验用户配置——导入路径、schema、有效属性、常见错误。references/error-messages.md：用户报告具体错误信息时。references/diagnostics-guide.md：需要启用/解读诊断输出，或需要向用户索要日志时。references/common-scenarios.md：将症状匹配到已知原因和修复。