hubspot-observability

用途

HubSpot Observability 用于为 HubSpot 集成建立可观测性，通过指标（metrics）、链路追踪（traces）和告警（alerts）来监控 CRM 集成的健康状况。当需要为 HubSpot API 操作实现监控、搭建监控体系时，可使用该技能。

主要能力

• Prometheus 指标：使用 prom-client 定义四类核心指标——请求总数计数器（按 method、object_type、status 打标签）、请求延迟直方图（按 method、object_type 打标签，含预设 buckets）、速率限制剩余量仪表（按 type 打标签）、错误计数器（按 status_code、category 打标签）。
• 带埋点的客户端封装：封装 HubSpot 官方 @hubspot/api-client，通过 tracked() 方法统一记录每次操作的延迟、成功或失败，并自动提取错误的状态码与分类。示例包含联系人的查询、创建、搜索和批量读取等操作。
• 结构化日志：使用 pino 记录 HubSpot 操作日志，包含 service、operation、durationMs 等上下文，并通过序列化器将 accessToken 从日志中移除，错误日志记录 statusCode、category、correlationId 和 message。
• 告警配置：提供 Prometheus AlertManager 规则示例，覆盖高错误率（>5%）、高 P95 延迟（>3s）、每日速率限制偏低（低于 50000）以及认证失败（401 错误增加）等场景，并标注严重级别。
• 指标端点：提供 Express 的 /metrics 路由，返回 registry 的指标内容供 Prometheus 抓取；并定时（每 60 秒）请求 HubSpot 接口读取响应头中的每日剩余配额，更新速率限制仪表。

使用方式

按步骤实施：

1. 配置 Prometheus 指标（Step 1），使用 prom-client 创建 Counter、Histogram、Gauge、Registry。
2. 创建带埋点的客户端封装（Step 2），将 HubSpot 调用包装在 tracked() 中执行。
3. 配置结构化日志（Step 3），使用 pino，并对敏感字段做脱敏。
4. 编写 AlertManager 告警规则（Step 4），以 YAML 形式定义告警组与规则。
5. 暴露指标端点（Step 5），通过 Express 提供 /metrics 并定期更新速率限制仪表。

前置条件（Prerequisites）：Prometheus 或兼容的指标后端；OpenTelemetry SDK（可选，用于 tracing）；结构化日志库（推荐 pino）。

输出结果

• Prometheus 指标：请求计数、延迟直方图、错误率、速率限制仪表
• 跟踪所有 HubSpot 操作的带埋点客户端封装
• 带 correlation ID 且脱敏密钥的结构化日志
• 针对错误率、延迟、速率限制和认证失败的 AlertManager 规则
• 供 Prometheus 抓取的 /metrics 端点

适用场景

需要监控 HubSpot CRM 集成的 API 健康度、排查延迟与错误、在错误率或延迟异常时自动告警，以及追踪速率限制使用情况的场景。

错误处理与限制

常见问题与解决方案：

• 指标缺失：操作未使用带埋点客户端——将所有调用通过 tracked() 包装。
• 高基数：标签值过多——将标签限制为 method + object_type。
• 告警风暴：阈值过于敏感——调整 for 时长和百分比阈值。
• 日志泄露 PII：日志中出现联系人数据——使用序列化器脱敏敏感字段。

资源

• Prometheus Client for Node.js
• OpenTelemetry JS
• Pino Logger

后续步骤

如需事件响应，可参考 hubspot-incident-runbook。

（注：关于收费、价格、平台等信息，资料中暂未提供。）