跳转到主要内容
数据通常通过 OpenTelemetry (OTel) Collector 发送到 ClickStack,既可以直接来自语言 SDK,也可以先经过作为 agent 运行的中间 OpenTelemetry Collector,例如用于采集基础设施指标和日志。 语言 SDK 负责从应用内部采集遥测数据,最主要的是 链路追踪日志,并通过 OTLP 端点将这些数据导出到 OpenTelemetry Collector,由其负责将数据摄取到 ClickHouse。 在基于浏览器的环境中,SDK 还可能负责收集 会话数据,包括 UI 事件、点击和导航,从而支持用户会话回放。

工作原理

  1. 您的应用程序使用 ClickStack SDK (例如 Node.js、Python、Go) 。这些 SDK 基于 OpenTelemetry SDK,并提供了额外功能和更好的易用性。
  2. SDK 通过 OTLP (HTTP 或 gRPC) 收集并导出链路追踪和日志。
  3. OpenTelemetry Collector 接收遥测数据,并通过已配置的导出器将其写入 ClickHouse。

支持的语言

OpenTelemetry 兼容性虽然 ClickStack 提供了自有语言 SDK,具备增强的遥测能力和更多功能,但你也可以无缝使用现有的 OpenTelemetry SDK。

语言描述链接
AWS Lambda为 AWS Lambda 函数添加遥测采集文档
Browser用于浏览器应用的 JavaScript SDK文档
ElixirElixir 应用文档
GoGo 应用和微服务文档
JavaJava 应用文档
NestJSNestJS 应用文档
Next.jsNext.js 应用文档
Node.js用于服务端应用的 JavaScript 运行时文档
DenoDeno 应用文档
PythonPython 应用和 Web 服务文档
React NativeReact Native 移动应用文档
RubyRuby on Rails 应用和 Web 服务文档

使用 API key 进行安全防护

:::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

Kubernetes 集成

所有 SDK 都支持在 Kubernetes 环境中自动关联 Kubernetes 元数据 (pod 名称、命名空间等) 。这样您就可以:
  • 查看与您的服务相关的 Pod (容器组) 和节点的 Kubernetes 指标
  • 将应用日志和链路追踪与基础设施指标关联
  • 跟踪整个 Kubernetes 集群中的资源使用情况和性能表现
要启用此功能,请配置 OpenTelemetry Collector,将资源标签转发到 pod (容器组) 。有关详细设置说明,请参阅 Kubernetes 集成指南
最后修改于 2026年6月10日