opentelemetry-instrumentation

Coralogix 的 OpenTelemetry SDK 插桩

何时使用此技能

使用场景	操作
选择语言 / 决定从何处开始	首先加载 language-selector.md — 其中包含有关语言、信号、模式和导出路径的决策树
为特定语言生成设置	确认 SDK 后，加载相应语言参考：java.md、python.md、nodejs.md、dotnet.md、go.md
配置 OTLP 端点、区域或身份验证	加载 coralogix-endpoints.md — 其中涵盖区域域名、OTLP 主机:端口和身份验证标头格式
生成完整的面向用户的回答	加载 output-templates.md — 其中包含带有假设、代码和验证步骤的检查清单结构
诊断 SDK 未能上报跟踪、指标或日志的问题	加载 troubleshooting.md — 其中包含 SDK 端故障的症状 → 根因表

加载顺序：language-selector.md → 语言参考 → coralogix-endpoints.md → output-templates.md（始终最后加载）。仅在调试时加载 troubleshooting.md。

回答规则

回答前（Agent 模式）：

• 始终先调用 list_references()，再对相关文件调用 read_reference(...)（语言选择器 + 目标语言 + 端点；仅在调试时添加故障排查）。如果参考资料可能影响准确性，请勿凭记忆作答。
• 对任何面向用户的回复，使用 output-templates.md 中的结构/检查清单；尽量简洁，并提供可执行的建议。

生成的回答必须始终包含：

• 必需的环境变量（仅名称） — 在任何“复制/粘贴”设置中包含以下变量： OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS、OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES （选择信号/协议时，还需包含 OTEL_*_EXPORTER / OTEL_EXPORTER_OTLP_*_PROTOCOL）。有关各语言对应的确切端点格式以及 Python %20 环境变量规则，请参阅 coralogix-endpoints.md。

• 必需的资源属性 — service.name（APM 目录/事务）、cx.application.name + cx.subsystem.name（路由、TCO、APM 分组）、telemetry.sdk.language（自动设置；请勿移除）。缺少其中任何一项都会导致 APM 功能悄然降级。有关其他 k8s/主机属性，请参阅各语言参考。

• 遥测质量。 使用低基数的 span 名称，不包含敏感数据，限制指标属性的取值范围，使用带有 trace/span ID 的结构化单行日志，并提供信号验证步骤。切勿批准将用户级值（user_id、tenant_id、request_id、session_id）用作指标标签 — 它们会导致基数无上限，并使指标存储量激增。

• 直连与通过收集器的路由规则： 对于开发/测试环境、简单的单服务生产部署，或没有收集器基础设施的情况，默认采用直连 OTLP。对于需要 Pod/命名空间增强（k8sattributes）、尾部采样、多服务共享密钥管理，或缓冲重试/文件持久化功能的 Kubernetes 工作负载，默认采用通过收集器。部署环境未知时，使用 language-selector.md 中的权衡表展示两种选项。

• 收集器配置不在此范围内。 请引导用户查看 opentelemetry-collector — 不要对管道或处理器问题作部分解答。

高风险注意事项（不要猜测）

仅在用户遇到的症状与此列表相符时才使用，并保持列表简短。详情请参阅相应语言的参考资料。

• Java Agent： opentelemetry-javaagent.jar + JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"。
• Java/.NET gRPC 端点： 必须使用完整 URI https://ingress.<region>.coralogix.com:443（URI 解析无法处理裸 host:port）。
• Python 身份验证标头： 环境变量需要 %20（Authorization=Bearer%20<KEY>）；以编程方式设置标头时，使用键名小写且包含字面空格的元组序列（("authorization", f"Bearer {token}")）。
• Node.js HTTP/proto： 导出器的 url 必须包含 /v1/traces（https://ingress.<region>.coralogix.com:443/v1/traces）；gRPC 不需要。
• Go gRPC： 使用 credentials.NewTLS(nil) 和裸端点 ingress.<region>.coralogix.com:443（WithEndpoint 中不要包含 https://）。
• Go 指标基数： sdk/metric 的默认基数限制为 2000；只有在确实需要无限序列时才使用 WithCardinalityLimit(0)，达到限制时会出现 otel.metric.overflow=true。
• .NET OTLP 磁盘重试： OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY=disk 现在需要设置 OTEL_DOTNET_EXPERIMENTAL_OTLP_DISK_RETRY_DIRECTORY_PATH；不要依赖隐式的临时目录回退。
• 事务： 需要 CoralogixTransactionSampler（Node.js：@coralogix/opentelemetry）；捆绑的 NODE_OPTIONS 自动插桩不支持事务。
• 短生命周期 Python 脚本： 在 SimpleSpanProcessor 与 BatchSpanProcessor 之间选择；指标需要使用 PeriodicExportingMetricReader 刷新／等待。
• .NET Framework 入站传播： 使用 OpenTelemetry.Instrumentation.AspNet + AddAspNetInstrumentation()。

工作流

• 新设置： language-selector.md → 语言参考资料 + coralogix-endpoints.md → 使用 output-templates.md 生成。
• 代码审查： 语言参考资料 → 查看 output-templates.md 中的审查清单。
• 调试： 优先查看 troubleshooting.md；只有在确认问题源于 SDK 时，才进一步查阅语言参考资料。

限制

• OTel Collector / OTTL — 使用 opentelemetry-collector 或 opentelemetry-ottl。
• Lambda / 无服务器 — 使用 Coralogix Lambda 层文档；Payload Too Large OTLP 错误属于 Lambda 层问题，而非 SDK 问题。
• PHP、eBPF 自动插桩 — 不在涵盖范围内。
• Coralogix 平台内部内容（数据路由、索引策略、APM UI 配置）— 属于平台主题。

已弃用的原生 SDK

Coralogix 原生 SDK 将于 June 30, 2026 结束生命周期（EOL）——请引导用户改用 OTel，不要提供旧版软件包的配置。

上游参考资料

Coralogix OTel 插桩：Java · Python · Node.js · .NET · Go

Coralogix OTel 文档 · OpenTelemetry 官方文档