故障排除
在本页，您将了解如何诊断和解决常见的 OBI 错误和问题。
排障工具
OBI 提供多种工具和配置选项来帮助诊断和排查问题。
详细日志记录
您可以通过将 log_level 配置或 OTEL_EBPF_LOG_LEVEL 环境变量设置为 debug 来提高 OBI 的日志详细程度。这将提供更详细的日志，有助于诊断问题。
要启用 BPF 程序的日志记录，请将 ebpf.bpf_debug 配置或 OTEL_EBPF_BPF_DEBUG 环境变量设置为 true。仅用于调试，因为它可能生成大量日志。
配置日志记录
默认情况下，OBI 将其配置从三个不同的来源合并，优先级从低到高：
- 内置默认配置
- 配置文件，通过
--config标志或OTEL_EBPF_CONFIG_PATH提供 - 环境变量，通常以
OTEL_EBPF_开头
查看最终合并的配置通常很有帮助。使用 log_config 配置值（或 OTEL_EBPF_LOG_CONFIG 环境变量），您可以指示 OBI 在启动时记录最终配置。
log_config 支持以下值：
yaml— 以 YAML 格式记录最终配置；最适合人类阅读，因为它与配置文件结构匹配json— 以 JSON 格式记录最终配置；最适合日志收集器，因为它是一行结构化的数据
内部指标
您可以配置和使用 OBI 内部指标来监控性能和内部状态。
要开启内部指标，请将 internal_metrics.exporter 配置为以下值之一：
none（默认）：禁用内部指标prometheus：通过 HTTP 服务器以 Prometheus 格式导出内部指标otlp：通过 OTLP 导出器导出内部指标
调试跟踪导出器
要调试 OBI 生成的原始跟踪跨度，您可以将 otel_traces_exporter.protocol 配置值或 OTEL_EXPORTER_OTLP_TRACES_PROTOCOL 环境变量设置为 debug。这将以人类可读的格式将原始跟踪跨度记录到控制台，与 OTel Collector 的 verbosity: detailed 调试导出器相匹配。控制台的示例跨度如下所示：
Traces {"resource spans": 1, "spans": 1}
ResourceSpans #0
Resource SchemaURL:
Resource attributes:
-> service.name: Str(flagd)
-> telemetry.sdk.language: Str(go)
-> telemetry.sdk.name: Str(opentelemetry-ebpf-instrumentation)
-> telemetry.sdk.version: Str(main)
-> host.name: Str(flagd-5cccb4c4f5-sfkcm)
-> os.type: Str(linux)
-> service.namespace: Str(opentelemetry-demo)
-> k8s.owner.name: Str(flagd)
-> k8s.kind: Str(Deployment)
-> k8s.replicaset.name: Str(flagd-5cccb4c4f5)
-> k8s.pod.name: Str(flagd-5cccb4c4f5-sfkcm)
-> k8s.container.name: Str(flagd)
-> k8s.deployment.name: Str(flagd)
-> service.version: Str(2.0.2)
-> k8s.namespace.name: Str(default)
-> otel.library.name: Str(go.opentelemetry.io/obi)
ScopeSpans #0
ScopeSpans SchemaURL:
InstrumentationScope
Span #0
Trace ID : 63a2723a58e0033170e58b1ff27ef03d
Parent ID :
ID : fab47609b60cc4e0
Name : /opentelemetry.proto.collector.metrics.v1.MetricsService/Export
Kind : Client
Start time : 2025-11-28 16:10:35.4241749 +0000 UTC
End time : 2025-11-28 16:10:35.42555658 +0000 UTC
Status code : Unset
Status message :
Attributes:
-> rpc.method: Str(/opentelemetry.proto.collector.metrics.v1.MetricsService/Export)
-> rpc.system: Str(grpc)
-> rpc.grpc.status_code: Int(0)
-> server.address: Str(otel-collector.default)
-> peer.service: Str(otel-collector.default)
-> server.port: Int(4317)
性能分析器 (pprof)
OBI 可以公开一个 pprof 端口以允许性能分析。要启用它，请将 profile_port 配置值或 OTEL_EBPF_PROFILE_PORT 环境变量设置为所需的端口。
这是一个高级用例，通常不需要。
常见的 OBI 问题
本节介绍如何解决常见的 OBI 问题。
运行 OBI 时 Node.js 服务崩溃或无响应
为了在 Node.js 应用程序中实现更好的上下文传播，OBI 会注入自定义代码来跟踪当前的执行上下文。它通过 Node.js 检查器协议来实现这一点，并向 Node 进程发送 SIGUSR1 信号以打开检查器。
但是，如果应用程序定义了自己的 SIGUSR1 信号处理程序，它会以自定义方式处理 OBI 的信号，这可能会导致目标应用程序崩溃或无响应。例如：
process.on('SIGUSR1', () => {
process.exit(0);
});
或者通过使用注册了自己的信号处理程序的 Node.js 标志，例如：
node --heapsnapshot-signal=SIGUSR1
解决方案
- 使用
discovery配置排除特定的 Node.js 应用程序，使其不被 OBI 跟踪，从而防止 OBI 发送SIGUSR1。 - 通过在配置文件中设置
nodejs.enabled:false或环境变量OTEL_EBPF_NODEJS_ENABLED=false完全禁用 Node.js 上下文传播。
运行 OBI 时 ClickHouse 实例崩溃
如果您在与 OBI 相同的节点上运行 Clickhouse，您可能会看到 ClickHouse 崩溃，日志显示如下：
Application: Code: 246. DB::Exception: Calculated checksum of the executable (...) does not correspond to the reference checksum ...
该问题很可能由 OBI 将 eBPF uprobe 附加到 ClickHouse 二进制文件引起。 相关的 GitHub 问题解释了这种行为。
当附加 uprobe 时，内核将修改目标进程内存，在附加地址处插入一个陷阱指令。这会导致 ClickHouse 二进制文件的校验和验证在启动时失败。
解决方案
使用 skip_binary_checksum_checks 标志启动 ClickHouse。
Go 应用程序或 TLS 请求缺少遥测数据
如果您发现来自 Go 应用程序或 TLS 请求（如 HTTPS 通信）的遥测数据丢失，可能是由于附加 uprobe 的权限不足。由于一些最近的内核安全更改，这些更改已被回溯到许多旧内核版本，uprobe 现在需要 CAP_SYS_ADMIN 能力。OBI 使用 uprobe 来检测 Golang 应用程序和 TLS 请求，以及其他运行时/语言特定的检测。如果您的 OBI 部署安全配置未使用特权操作（例如 privileged:true 或 Docker 和 Kubernetes），或者它没有提供 CAP_SYS_ADMIN 作为安全能力，您可能会看不到部分或全部遥测数据。
要排查此问题，请使用 OTEL_EBPF_LOG_LEVEL=debug 启用详细的 OBI 日志记录。如果您看到所有 uprobe 注入都因错误“setting uprobe (offset)…”而失败，那么您很可能遇到了此问题。
解决方案
您可以选择：
- 以特权模式运行 OBI。
- 在您的部署安全配置的能力列表中添加
CAP_SYS_ADMIN。