数据通常通过 OpenTelemetry (OTel) Collector 发送到 ClickStack,既可以直接来自语言 SDK,也可以先经过作为 agent 运行的中间 OpenTelemetry Collector,例如用于采集基础设施指标和日志。
语言 SDK 负责从应用内部采集遥测数据,最主要的是 链路追踪 和 日志,并通过 OTLP 端点将这些数据导出到 OpenTelemetry Collector,由其负责将数据摄取到 ClickHouse。
在基于浏览器的环境中,SDK 还可能负责收集 会话数据,包括 UI 事件、点击和导航,从而支持用户会话回放。
- 您的应用程序使用 ClickStack SDK (例如 Node.js、Python、Go) 。这些 SDK 基于 OpenTelemetry SDK,并提供了额外功能和更好的易用性。
- SDK 通过 OTLP (HTTP 或 gRPC) 收集并导出链路追踪和日志。
- OpenTelemetry Collector 接收遥测数据,并通过已配置的导出器将其写入 ClickHouse。
OpenTelemetry 兼容性虽然 ClickStack 提供了自有语言 SDK,具备增强的遥测能力和更多功能,但你也可以无缝使用现有的 OpenTelemetry SDK。
| 语言 | 描述 | 链接 |
|---|
| AWS Lambda | 为 AWS Lambda 函数添加遥测采集 | 文档 |
| Browser | 用于浏览器应用的 JavaScript SDK | 文档 |
| Elixir | Elixir 应用 | 文档 |
| Go | Go 应用和微服务 | 文档 |
| Java | Java 应用 | 文档 |
| NestJS | NestJS 应用 | 文档 |
| Next.js | Next.js 应用 | 文档 |
| Node.js | 用于服务端应用的 JavaScript 运行时 | 文档 |
| Deno | Deno 应用 | 文档 |
| Python | Python 应用和 Web 服务 | 文档 |
| React Native | React Native 移动应用 | 文档 |
| Ruby | Ruby on Rails 应用和 Web 服务 | 文档 |
:::Not required for Managed ClickStack
托管 ClickStack 不需要 API key。
:::
为了通过 OpenTelemetry Collector 将数据发送到 ClickStack,SDKs 需要指定摄取 API key。可以通过 SDK 中的 init 函数或 OTEL_EXPORTER_OTLP_HEADERS 环境变量进行设置:
OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'
此 API 密钥由 ClickStack UI (HyperDX) 应用生成,可在应用的 Team Settings → API Keys 中找到。
对于大多数支持 OpenTelemetry 的语言 SDK和遥测库,你只需在应用中设置 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量,或在 SDK 初始化时指定该端点:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
所有 SDK 都支持在 Kubernetes 环境中自动关联 Kubernetes 元数据 (pod 名称、命名空间等) 。这样您就可以:
- 查看与您的服务相关的 Pod (容器组) 和节点的 Kubernetes 指标
- 将应用日志和链路追踪与基础设施指标关联
- 跟踪整个 Kubernetes 集群中的资源使用情况和性能表现
要启用此功能,请配置 OpenTelemetry Collector,将资源标签转发到 pod (容器组) 。有关详细设置说明,请参阅 Kubernetes 集成指南。