通过 Odigos 将 OpenTelemetry 发送到 ClickStack

Odigos 是一个面向 Kubernetes 和 VM 的插桩控制平面，通过 eBPF 在内核层为应用实现插桩。由于采集在内核中运行，应用开销能够保持很低，同时仍具备很强的可观测性。你无需在应用代码中接入新的 agent，也不必等待所有服务完成库升级，就能获得生产级的 OpenTelemetry 链路追踪、指标、日志和 profile。

正是这一 eBPF layer，让大规模实现深入且一致的观测数据采集成为可能。Odigos 可以在需要时自动开启或关闭更深层的插桩，帮助调试或排查问题：

• 代码级上下文 — 与函数和运行时行为关联的属性
• HTTP 流量 — 服务之间的请求与响应
• 消息系统 — 来自 Kafka 和类似消息代理的载荷与消息
• 详细错误信息 — 出现故障时的堆栈跟踪
• 自定义插桩 — 在 auto-instrumentation 覆盖不到的地方继续扩展，无需修改代码或重启

在底层，Odigos 会为你的集群创建并管理一整套 OpenTelemetry 管道：可随负载扩缩的 collectors、将数据路由到你选择的后端，以及可在 UI 中控制的管道逻辑。你可以定义 采样 来控制数据量，配置 PII masking 以避免敏感数据被导出，并使用 OTTL 规则 在观测数据离开集群之前对其进行过滤、转换或增强。

在众多服务中部署 OpenTelemetry 往往既耗时，又只能提供较浅层的应用可观测性。Odigos 通过 eBPF 实现更深层的插桩，并负责 Kubernetes 上 collector 的运行；ClickStack 则提供基于 ClickHouse 的存储，以及用于大规模查询遥测数据的 HyperDX UI。

• 已安装 ClickStack，并且可从你的 Kubernetes 集群访问。参见 开始使用开源 ClickStack 或 开始使用托管 ClickStack。
• 你的 ClickStack OTLP HTTP 端点 (端口 4318) ，以及 Odigos 将在 Authorization 请求头中传递的身份验证值。对于开源 ClickStack，这个值是 HyperDX UI 中 Team Settings → API Keys 里的 API 摄取密钥。对于托管 ClickStack，这个值是你在启动自己的独立 ClickStack 收集器时设置的 OTLP_AUTH_TOKEN。
• 一个 Kubernetes 集群 (用于 eBPF instrumentation 的 Linux 节点内核版本需为 4.18 或更高)
• 要安装到 odigos-system 命名空间所需的 Helm、kubectl 和集群凭证
• 一个 Odigos Enterprise 本地部署 token —— 联系 Odigos team 获取访问权限

export ODIGOS_ONPREM_TOKEN="<your-enterprise-token>"

helm repo add odigos https://odigos-io.github.io/odigos/
helm repo update

helm upgrade --install odigos odigos/odigos \
  --namespace odigos-system \
  --create-namespace \
  --set onPremToken=$ODIGOS_ONPREM_TOKEN

kubectl get pods -n odigos-system

kubectl port-forward svc/ui -n odigos-system 3000:3000

如果你使用 Odigos 原生的 ClickHouse 目标端直接将数据导出到 ClickHouse (而不是通过 OTLP HTTP 导出到 ClickStack) ，请启用 HyperDX 日志规范化器 (HYPERDX_LOG_NORMALIZER: true) 。它会解析 JSON 格式的日志正文，并对属性进行规范化，以便在 ClickStack UI 中更高效地查询。

当集群可直接访问 ClickHouse 时，可以使用 Odigos 的原生 ClickHouse 目标端，而不是 OTLP HTTP。在 UI 中或通过清单配置 ClickHouse 端点、数据库名和 schema 选项——请参阅 Odigos ClickHouse destination。

• 生产 schema：将 CLICKHOUSE_CREATE_SCHEME 设置为 false，并使用你自己的 DDL。
• TLS / 认证：使用 CLICKHOUSE_TLS_ENABLED、CLICKHOUSE_USERNAME，并通过 Kubernetes Secret 提供密码。

OTLP HTTP (ClickStack)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickstack
  namespace: odigos-system
spec:
  type: otlphttp
  destinationName: otlphttp
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    OTLP_HTTP_ENDPOINT: 'http://clickstack.example.com:4318'
    # 开源 ClickStack 的 API 摄取密钥，或托管 ClickStack 的 OTLP_AUTH_TOKEN
    OTLP_HTTP_HEADERS: 'Authorization:<YOUR_AUTHORIZATION_VALUE>'

ClickHouse (直连)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickhouse
  namespace: odigos-system
spec:
  type: clickhouse
  destinationName: clickhouse
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    CLICKHOUSE_ENDPOINT: 'http://clickstack.example.com:8123'
    CLICKHOUSE_DATABASE_NAME: 'otel'
    CLICKHOUSE_CREATE_SCHEME: 'true'

应用此清单：

kubectl apply -f destination.yaml

Odigos VM Agent 使用 eBPF 为 Linux 进程、systemd 服务和/或 Docker 容器添加遥测采集能力。遥测数据会导出到与基于集群的 Odigos 相同的目标端，包括通过 OTLP HTTP 导出到 ClickStack。

VM Agent 是 Odigos Pro 的一部分。有关设置、数据源和目标端配置，请参阅 VM Agent 概述。

Odigos Central 是一个集中式控制平面，可通过单一 UI 统一管理多个 Kubernetes 集群中的插桩、目标端和管道配置，而无需逐个集群分别配置。

Odigos Central 在 Odigos Enterprise 中可用。有关多集群管理、SSO 和统一采样规则，请参阅 Central 概述。

• 在 ClickStack 中查看已插桩服务的链路追踪
• 为 Odigos 导出的指标创建仪表盘
• 根据您的保留策略和查询模式，优化 ClickHouse schema 和生存时间 (TTL)

• Odigos Enterprise 安装
• Odigos ClickHouse 目标端
• Odigos VM Agent 概述
• Odigos Central 概述
• 告别生产环境中的盲目猜测：使用 ClickHouse 和 Odigos 实现大规模全保真追踪
• 开源 ClickStack 入门