opentelemetry-collector

OpenTelemetry Collector

Coralogix 定制版 OpenTelemetry Collector——coralogix exporter、适用于 Kubernetes 的 otel-integration Helm chart、适用于 ECS 的 CDOT，以及适用于独立主机的通用安装程序。当用户部署、配置或排查向 Coralogix 发送数据的 Collector 时，请加载此技能。大多数故障都归结为少数几个 Coralogix 特有的默认设置，而通用 OpenTelemetry 文档并未涉及这些设置。

何时使用此技能

使用场景	参考资料
配置 coralogix exporter（域名、私钥、应用/子系统）	config-exporters.md · config-processors.md
Infrastructure Explorer / Resource Catalog	preset-kubernetes.md
选择部署模式	setup-index.md
Kubernetes — otel-integration Helm chart（EKS/GKE/AKS/OpenShift/Autopilot/EKS Fargate）	setup-kubernetes.md
OpenTelemetry Operator / Target Allocator	setup-opentelemetry-operator.md
ECS EC2（Linux daemonset）	setup-ecs-ec2.md
ECS Fargate（sidecar）	setup-ecs-fargate.md
Linux / macOS 独立部署	setup-linux-standalone.md
Windows 独立部署	setup-windows-standalone.md
通用安装程序（所有操作系统）	setup-installer.md
spanmetrics、tail_sampling、k8sattributes 的放置位置	config-connectors.md
Span Metrics DB 标签在 calls_total 和 db_calls_total 之间存在差异	config-connectors.md — 将 DB 标签兼容性转换放在顶层 spanMetrics.transformStatements 下
基数、URL/Span 名称清理和 PII 脱敏路由	data-safety-cardinality.md
Collector 组件成熟度、alpha/beta/stable/deprecated 指南	component-stability.md
内存 — memory_limiter 触发、RSS 与 Go 堆	ops-memory-performance.md
排查“无数据”“无追踪数据”“Resource Catalog 为空”	ops-troubleshooting.md
OpAMP supervisor / Fleet Manager 配置重叠	preset-fleet-management.md

高优先级回答规则

对于以下常见情况，最终回答中必须包含确切的修正细节。这些内容也是 Coralogix 特有默认设置的权威说明——回答中的其他内容不得与之矛盾。

Exporter 和路由

• domain: 必须是裸主机名，而不是 URL。 使用 eu2.coralogix.com，而不是 https://ingress.eu2.coralogix.com，也不是 UI 主机名。
• 环境变量必须加括号。 使用 ${env:CORALOGIX_PRIVATE_KEY}，而不是 $CORALOGIX_PRIVATE_KEY——在 v0.76+ 中，不带括号的形式会静默失效。最小 exporter 配置块：domain: "<region>.coralogix.com" 和 private_key: "${env:CORALOGIX_PRIVATE_KEY}"。
• 对于 Infrastructure Explorer，使用专用的 coralogix/resource_catalog exporter 并设置 x-coralogix-ingress: metadata-as-otlp-logs/v1 标头。默认的 coralogix exporter 不会启用实体视图。
• resourcedetection/resource_catalog 在 daemonset 上崩溃——错误 can't get K8s Instance Metadata; node name is empty 表示此处理器运行在 daemonset Agent 上。它只能放在 opentelemetry-cluster-collector Deployment 上。修复方法：从 daemonset 配置中移除它。不要将它与 coralogix/resource_catalog exporter 混为一谈，后者是另一个独立组件。
• 无数据 + transform/OTTL： 明确建议停止尝试 OTTL；优先检查 receiver/exporter 连接、DNS/TLS/代理/出口、私钥以及区域/域名。

组件稳定性

• 在给出生产环境建议前，先检查稳定性。 Collector 组件按信号划分的稳定性信息见其上游 README。alpha 适用于有限的非关键用途，beta 适用范围更广，但仍可能发生破坏性变更；stable 是生产环境的默认选择，deprecated 表示应避免新部署并规划迁移。配置通过验证并不足以证明该组件适合用于生产环境。
• 推荐使用 alpha/beta 组件时，说明相关风险。 固定 Collector 版本，在预发布环境的流量上测试确切配置，升级前阅读发行说明；如果工作负载对业务至关重要，还应提供稳定的替代方案。

流水线放置位置（Kubernetes）

• memory_limiter 放在最前，batch 放在最后。
• 由一个角色负责完整的 k8sattributes 提取——通常是网关；Agent 使用 passthrough: true。
• 在 Agent 上运行 spanmetrics（采样前），在网关上运行 tail_sampling。 在 spanmetrics 之前运行 transactions/groupbytrace/transactions；绝不要同时在 Agent 和网关上运行——这会导致重复计数，因为每一层都会看到所有 Span，并发出会累积的独立指标序列。在 DaemonSet Agent 上运行 tail_sampling 会导致链路不完整，因为每个 Agent 只能看到来自自身节点的 Span——单条链路会被拆分到多个 Agent 上，采样器只能根据不完整的数据作出判断。解决方法：将 tail_sampling 移到中心网关层，并在 Agent 上添加 loadbalancing exporter，按 trace_id 将 Span 路由到网关，确保同一条链路的所有 Span 都到达同一个网关副本。
• Span Metrics DB 标签兼容性转换应放在顶层的 spanMetrics.transformStatements 下。 不要只将它们放在 spanMetrics.dbMetrics.transformStatements 下；否则可能会填充 db_calls_total，但普通的 calls_total 中 db_namespace 仍为空。
• 不要整体替换 service.pipelines——使用 extraProcessors/extraReceivers 钩子；整体覆盖会悄悄破坏 resource/metadata（cx.agent.type），并影响图表升级。

基数和脱敏

• 指标维度遵循 100 条规则。 如果某个属性可能有约 100 个以上的唯一值，就不要将其添加为 Span Metrics 维度。将 ID、原始 URL、电子邮件、请求 ID、会话 ID 和 trace_id 保留在 Span/日志中，或在生成指标前对其进行规范化。
• url.full、k8s.pod.name 和 k8s.pod.ip 是危险的 Span Metrics 维度。 优先使用 http.route、低基数的主机/操作标签，以及稳定的服务/资源标签。如果客户坚持使用 url.full，应在 spanmetrics 处理 Span 之前对其进行清理，并明确说明风险。
• aggregation_cardinality_limit 是一道防护措施，不是解决方案。 对于 Helm 的 spanMetrics.aggregationCardinalityLimit / Collector 的 aggregation_cardinality_limit， 可用它合并溢出的序列，但仍应移除或规范化高基数标签。
• 在导出和派生指标之前进行脱敏。 应在 Collector 流水线中、在 spanmetrics、batch 和 coralogix 之前移除、屏蔽或哈希 PII/机密信息。对于范围较广的 URL 类 Span 名称或 URL 属性，应明确建议使用 redactionprocessor，并使用字面键 url_sanitizer 和 sanitize_span_name；除非有意使用明确的 allowed_keys 白名单，否则应包含 allow_all_keys: true，否则未指定的属性会被丢弃。提醒用户，范围较广的清理器可能会过度清理，并应验证处理前后的示例。使用 opentelemetry-ottl 技能进行有针对性的转换，例如 SHA256、replace_pattern、replace_all_patterns、delete_key 和空值安全保护。

平台特定规则

• GKE Autopilot Warden： 设置 logsCollection.storeCheckpoints: false；在 Agent 上禁用 coralogix-ebpf-profiler、hostMetrics、hostEntityEvents 和 resourceDetection；在 cluster-collector 上禁用 resourceDetection。使用 gke-autopilot-values.yaml。
• ECS EC2 daemonset localhost： 应用必须将 EC2 主机 IP（而非 localhost）设为目标；daemonset 需要 networkMode: host。从 resourcedetection.detectors 中移除 ecs——它会记录采集器自身的容器 ID。
• ECS Fargate 启动时数据丢失： 为应用添加 sidecar healthCheck，并设置 dependsOn: [{containerName: otel-collector, condition: HEALTHY}]。使用 CDOT 镜像。
• 独立安装程序： 建议使用 otel-installer/单行命令，并同时设置 CORALOGIX_PRIVATE_KEY 和 CORALOGIX_DOMAIN。
• Infrastructure Explorer（Kubernetes）： 图表中默认启用 kubernetesResources 和 hostEntityEvents——不要禁用它们。kubernetesResources 必须只在 opentelemetry-cluster-collector 上启用（在 Agent 上启用会导致崩溃，并显示 can't get K8s Instance Metadata; node name is empty）。使用专用的 coralogix/resource_catalog exporter，并设置 x-coralogix-ingress: metadata-as-otlp-logs/v1。
• Resource Catalog daemonset 崩溃： resourcedetection/resource_catalog 只能配置在 opentelemetry-cluster-collector Deployment 上；从 daemonset Agent 中移除它。
• 完整的 k8sattributes： 只能由一个角色执行完整提取；在其他角色上设置 passthrough: true。
• OpAMP supervisor 端点： 它与 exporter 的 domain: 不同，需要完整 URL，例如 https://ingress.eu2.coralogix.com/opamp/v1。
• 旧镜像固定版本下 Windows 的 extensions: [opamp] 会失败： K8s Windows 子预设默认使用 coralogixrepo/opentelemetry-collector-contrib-windows:0.92.0，该版本早于 Windows 上的 OpAMP——在此启用 extensions: [opamp] 会导致采集器拒绝启动。解决方法：将镜像升级到 ≥ v0.130。如果无法升级镜像（例如生产冻结期间版本已锁定），请改用 -Supervisor wrapper——它会将 opampsupervisor 作为独立 Windows Service 运行，不受采集器版本影响。
• Java 多行堆栈跟踪未合并（Kubernetes）： CRI 会将每行日志都标记为 F（完整/最终），因此标准的 P→F 重组操作不会触发。使用 filelog recombine 操作符中的 firstEntryRegex，根据时间戳模式检测新条目。
• spanNameReplacePattern 转义： 有两层要求：YAML/OTTL 反斜杠需要使用单引号或块标量；反向引用要写为 $$1/$$2，因为采集器的 envprovider 会展开 $...；请使用 helm template 验证。
• Target Allocator 调试： 将 svc/coralogix-opentelemetry-targetallocator 的端口转发到 8080；检查 /jobs 和 /scrape_configs；然后检查 RBAC、选择器和受监控的命名空间。

常见工作流

1. 排查“没有数据到达 Coralogix”的报告

在修改任何管道配置之前，请按顺序完成以下步骤：

步骤 1 — 确认采集器正在运行并导出数据

# Kubernetes: check exporter metrics
kubectl exec -n <namespace> <collector-pod> -- wget -qO- http://localhost:8888/metrics \
  | grep -E 'otelcol_exporter_(sent|send_failed|enqueue_failed|queue)'
# Success: otelcol_exporter_sent_* > 0 and climbing
# Failure indicator: otelcol_exporter_send_failed_* > 0 — proceed to Step 2

步骤 2 — 验证 DNS 和 TLS 是否能连接到数据摄取端点

# From inside the collector pod / host
nslookup ingress.<domain>          # e.g. ingress.coralogix.com
curl -v https://ingress.<domain>   # expect 400/401, NOT a TLS or connection error

如果 DNS 解析失败 → 属于网络、VPC 或代理问题，而非采集器配置问题。 如果 TLS 连接失败 → 可能是证书包问题或代理执行了中间人攻击；检查 NO_PROXY / HTTPS_PROXY 环境变量。

步骤 3 — 确认私钥已正确展开

# Kubernetes: inspect the live env
kubectl exec -n <namespace> <collector-pod> -- env | grep CORALOGIX
# The key must appear as a 36-char UUID-like string, not the literal "${env:...}" text
# Literal text → bracket syntax wrong, or Secret not mounted

步骤 4 — 检查导出器的 domain: 值

在运行中的配置（/etc/otelcol-contrib/config.yaml 或 kubectl get cm）中，验证：

• domain: 是不带其他内容的主机名，例如 eu2.coralogix.com — 不带 https:// 前缀，也不能使用 UI 主机名（app.coralogix.com 就不正确）
• private_key: 已解析为实际密钥（步骤 3）

步骤 5 — 启用调试日志一分钟

service:
  telemetry:
    logs:
      level: debug

查找 Exporting failed 或 grpc status 日志行。StatusUnauthenticated 表示密钥与区域不匹配。context deadline exceeded 则可能说明出站流量或代理有问题，也可能是入口侧延迟 — 同时检查 coralogix.timeout（默认值为 5s；可增至 30s）。

步骤 6 — 仅在步骤 1–5 均通过后检查管道连接

如果导出正常，但 Coralogix UI 中缺少数据：检查接收器连接、处理器过滤器（filter 处理器是否丢弃了所有数据），以及管道是否已在 service.pipelines 中连接。完整的症状 → 根因对照表：references/ops-troubleshooting.md。

2. 使用 otel-integration 启动新的 Kubernetes 集群

安装流程、各平台变体、Target Allocator 和图表特定故障模式，请参阅 references/setup-kubernetes.md。 如果问题涉及 Helm 预设或 Infrastructure Explorer，请参阅 references/preset-kubernetes.md。

3. 启动 ECS Fargate（Sidecar 模式）

请参阅 references/setup-ecs-fargate.md。容易出问题的部分包括 Sidecar 健康检查、dependsOn: HEALTHY、essential 标志，以及仅在 Sidecar 模式下启用 ecs 检测器。

4. 排查 memory_limiter 持续触发的问题

请参阅 references/ops-memory-performance.md。在修改 Pod 限制或 memory_limiter 设置前，先比较 Go 堆指标与 RSS。

5. 降低 Span Metrics 基数或清理 PII

请参阅 references/data-safety-cardinality.md。回答应分层说明：在检测埋点阶段防止不良标签，在 spanmetrics 之前进行规范化和清理，最后再讨论采集器／后端的基数限制。

限制

• 编写 OTTL — 请使用 opentelemetry-ottl 技能。
• OpAMP / Fleet Manager 内部机制 — preset-fleet-management.md 仅涵盖与采集器配置重叠的部分（端点格式、values 与 UI 的优先级、Windows 镜像陷阱）；深入的 supervisor/CDOT 工作不在范围内。
• SDK 检测埋点问题 — 请使用 opentelemetry-instrumentation 技能。
• 上游基础设施（DNS、TLS、代理、IAM/IRSA、NAT、VPC 端点）— 排查到边界后再升级处理。

参考资料

上游链接：

• Coralogix OpenTelemetry 文档
• telemetry-shippers（Helm 图表、ECS 任务定义、安装程序）
• integration-definitions（UI 向导）
• OpenTelemetry Collector（上游）
• OTel Collector Contrib