用途：为 Intercom 集成提供生产环境可观测性，覆盖 Prometheus 指标、OpenTelemetry 链路追踪、结构化日志，以及针对错误率、延迟和限流用量的告警规则。
主要能力（按六层依次构建）：1）在共享 Registry 上定义五个 Prometheus 指标：请求计数器、时长直方图、错误计数器、限流 Gauge、Webhook 计数器，按 endpoint/method/status 打标签，不使用无界 ID 以免标签基数过高。2）用 Proxy 包装 IntercomClient，自动为所有服务方法计时、累加成功/错误计数、记录 IntercomError 的错误码与状态码，并在收到 429 时将限流 Gauge 置零。3）用 Pino 配置结构化日志，接触器序列化仅输出 id/role，不记录 email、name、phone；提供 logIntercomOp 与 logWebhook 辅助函数。4）用 tracedIntercomCall 包裹调用，为每次操作开启 intercom.* span，设置 OK/ERROR 状态、记录异常并附加 status_code/error_code/request_id 属性。5）提供 Prometheus 规则组，含五条告警：错误率 >5%、P95 延迟 >3s、剩余限流 <1000、401 认证失败、Webhook 失败。6）在 GET /metrics 暴露 Registry 供 Prometheus 抓取。
使用方式：安装前置项（Prometheus 或兼容后端、可选 OpenTelemetry SDK、Pino 等结构化日志器、Grafana 或告警系统），按六层顺序实现。最小骨架示例： const client = instrumentedClient(new IntercomClient({ token: process.env.INTERCOM_ACCESS_TOKEN! })); const contact = await tracedIntercomCall("contacts.find", { "intercom.contact_id": contactId }, () => client.contacts.find({ contactId }));
适用场景：需要为 Intercom 集成搭建监控面板、指标埋点、链路追踪与告警的生产系统。
限制与注意：高基数标签需改用 endpoint 分组；未埋点调用会导致指标缺失，需用代理包装客户端；阈值错误可能引发告警风暴，应基于基线调优；生产环境调试日志过多可设 LOG_LEVEL=info。详细代码见 references/implementation.md，端到端场景见 references/examples.md。后续可结合 intercom-incident-runbook 技能做告警响应。