ITADN
grafana/otel-checker
代码 动态 Issues5 合并请求125 版本1
grafana/otel-checker · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

OTel Me If It's Right

通过扫描仓库中的代码、检查环境变量、 验证你的 Grafana token 等， 检查 OpenTelemetry instrumentation 的实现是否正确。

用法

对于源码安装，你需要 Go 1.25 或更高版本。预构建的二进制文件也可 从 GitHub Releases 页面获取。

安装

预构建二进制文件

从最新 release 下载适用于你的操作系统和 CPU 架构的归档文件， 解压它，并将 otel-checker 二进制文件放到你的 PATH 上。Release 归档 文件提供适用于 amd64 和 arm64 的 Linux、macOS 和 Windows 版本。静态 链接的 Linux 归档文件适用于基于 glibc 和 musl 的发行版，例如 Alpine Linux。checksums.txt 包含用于验证的 SHA-256 校验和。

Go 安装

  1. 安装 otel-checker 二进制文件

    go install github.com/grafana/otel-checker/cmd/otel-checker@latest

  2. 您可以通过以下方式确认其已安装：

    ❯ ls $GOPATH/bin
otel-checker

命令

otel-checker check                  # all components
otel-checker check sdk              # SDK only
otel-checker check collector        # Collector config only
otel-checker check beyla            # Beyla only
otel-checker check alloy            # Grafana Alloy only
otel-checker check grafana-cloud    # Grafana Cloud connectivity only
otel-checker serve                  # web UI for a previously-saved JSON result
otel-checker explain                    # show explanations for every finding from a saved results file
otel-checker explain <id>               # show the explanation for a single ID
otel-checker explain list               # list every available explain ID
otel-checker version                    # print the binary version
otel-checker completion <shell>         # generate shell completion script

check 命令接受一个可选的、以逗号分隔的组件列表 （check sdk,collector,beyla）。如果不提供参数，则检查所有组件。

运行 otel-checker check --help 或 otel-checker check sdk --help 以查看每个子命令的完整 标志集。

示例

# Single-component checks
otel-checker check sdk --language=js
otel-checker check sdk --language=java --manual-instrumentation
otel-checker check collector --collector-config-path=./otel/config.yaml
otel-checker check grafana-cloud --language=python

# Multi-component (positional, comma-separated, no spaces)
otel-checker check sdk,collector,beyla --language=js

# Every component at once
otel-checker check --language=js

说明

每个可操作的发现（错误和警告）都会在其行末的方括号中标注一个稳定的 explain ID：

✖ SDK: package.json missing on path /src/inst [js.package-json.unreadable]

使用以下命令查找任何发现的指导：

otel-checker explain js.package-json.unreadable

或枚举所有可用的 explain ID：

otel-checker explain list

要查看上一次运行中所有发现的解释，请保存 JSON 输出 一次，并在不指定 ID 的情况下调用 explain：

otel-checker check --language=js --format=json > results.json
otel-checker explain

在没有 ID 的情况下，explain 默认读取 ./results.json（以及 ./results.yaml / ./results.yml）—— 即 serve 所监视的同一文件 —— 并依次打印每个 explain 文档， 对重复的 ID 进行去重，并跳过没有 ID 的发现。 传入 --data=<path> 以指向不同的文件。

当使用 --format=json 或 --format=yaml 时，相同的 ID 也会作为每个条目上的 explain_id 字段出现， 以便下游工具可以以编程方式将发现与 explain 目录进行匹配。

输出格式

默认情况下，结果以彩色文本形式打印。使用 --format=json 或 --format=yaml 以获取适用于 CI 流水线的机器可读输出：

otel-checker check sdk --language=go --format=json

Web UI

向任何 check 调用传递 --web-server，以同时在 http://127.0.0.1:8080 上提供结果。使用 --listen=host:port 覆盖绑定地址； 默认仅绑定到回环地址。按 Ctrl-C 可干净地关闭服务器。

提供结果文件

otel-checker serve 监视磁盘上的 JSON 或 YAML 结果文件，并在 Web UI 中渲染它。页面每隔几秒轮询一次，因此当文件 被创建或重写时，浏览器会自动获取新内容。

默认情况下，serve 会在当前目录中查找 ./results.json，然后是 ./results.yaml，然后是 ./results.yml。如果这些文件尚不存在，服务器仍会 启动并显示一个指向预期路径的占位符——这对于 在长时间运行的管道写入结果时保持 UI 打开非常有用。

# Start the server (looks for ./results.json by default)
otel-checker serve

# In another terminal, write the file; the UI updates on the next poll
otel-checker check sdk --language=go --format=json > results.json

# Point at a specific file or a different format
otel-checker serve --data=./out/results.yaml

检查

通用环境变量

这些检查会自动针对所有语言和组件执行。

  • 信号导出器（OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER、 OTEL_LOGS_EXPORTER）：必须为 otlp、console 或未设置；none 将被拒绝。
  • 服务名称：OTEL_SERVICE_NAME（或在 OTEL_RESOURCE_ATTRIBUTES 中的 service.name）。
  • 资源属性检查：
    • 验证推荐的 OpenTelemetry 资源属性是否存在
    • 检查以下属性：
      • service.name（通过 OTEL_SERVICE_NAME 或在 OTEL_RESOURCE_ATTRIBUTES 中）
      • service.namespace（例如，shop）
      • deployment.environment.name（例如，production）
      • service.instance.id（例如，checkout-123）
      • service.version（例如，1.2）
    • 对于缺失的属性，提供带有示例值的具体建议
    • 遵循 OpenTelemetry 规范 关于优先级的规定（例如，在 OTEL_RESOURCE_ATTRIBUTES 中 OTEL_SERVICE_NAME 优先于 service.name）
    • 警告示例：Set OTEL_RESOURCE_ATTRIBUTES="service.namespace=shop": An optional namespace for service.name

Grafana Cloud

运行 otel-checker check grafana-cloud --language=<lang>（或向 check 传递 --components=grafana-cloud）：

  • OTEL_EXPORTER_OTLP_ENDPOINT 与 https://otlp-gateway-<zone>.grafana.net/otlp 匹配。
  • OTEL_EXPORTER_OTLP_PROTOCOL 为 http/protobuf。
  • OTEL_EXPORTER_OTLP_HEADERS 包含一个 Authorization=Basic <token> 条目。
  • 凭据验证：使用提供的令牌测试端点。

SDK

JavaScript

运行 otel-checker check sdk --language=js：

  • Node 版本 — 必须是 Active LTS 版本（偶数主版本，当前为 22、24 或 26）。奇数主版本的 Current 版本（23、25）也会被标记。
  • @opentelemetry/api 依赖项位于 package.json 中。
  • 自动插桩模式（默认）：
    • @opentelemetry/auto-instrumentations-node 依赖项。
    • NODE_OPTIONS 包含 --require @opentelemetry/auto-instrumentations-node/register。
    • OTEL_NODE_RESOURCE_DETECTORS 设置为 all 或覆盖 env,host,os,serviceinstance。
  • 手动插桩模式（--manual-instrumentation）：
    • 不通过 NODE_OPTIONS 进行并发自动插桩。
    • 使用 @opentelemetry/exporter-trace-otlp-http（而非 -otlp-proto）。
    • 在调试之外使用 ConsoleSpanExporter / ConsoleMetricExporter 时发出警告。
  • 支持的库：package.json 依赖项与 OpenTelemetry JS contrib 注册表进行匹配。

Python

运行 otel-checker check sdk --language=python：

  • 支持的库：requirements.txt 依赖项与 OpenTelemetry Python contrib 注册表进行匹配。

.NET

运行 otel-checker check sdk --language=dotnet：

  • .NET 版本（>= 8.0）。
  • 自动插桩环境变量：
    • CORECLR_ENABLE_PROFILING = 1
    • CORECLR_PROFILER = {918728DD-259F-4A6A-AC2B-B85E1B658318}
    • 已设置 CORECLR_PROFILER_PATH
    • 已设置 OTEL_DOTNET_AUTO_HOME
  • 支持的插桩：.csproj NuGet 依赖项与 OpenTelemetry .NET 自动插桩库列表进行匹配。

[!NOTE] 仅支持 .NET 8.0 及更高版本

Java

运行 otel-checker check sdk --language=java：

  • Java 版本（>= 8）。
  • 支持的库（从本地运行的 Maven 或 Gradle 中发现， 如果在当前目录或父目录中找到包装器，则包括包装器）：
    • 没有 --manual-instrumentation：由 Java Agent 支持的库。
    • 有 --manual-instrumentation：支持手动插桩的库。

Go

运行 otel-checker check sdk --language=go：

  • 基于当前目录中 go.mod 的手动插桩支持的库。

Ruby

运行 otel-checker check sdk --language=ruby：

  • Ruby 版本（CRuby >= 3.3，JRuby >= 9.4，或 TruffleRuby >= 22.1）。
  • 已安装 Bundler。
  • Gemfile 和 Gemfile.lock 存在。
  • 必需的 gems：opentelemetry-api、opentelemetry-sdk、 opentelemetry-exporter-otlp。
  • 自动插桩（默认）：opentelemetry-instrumentation-all 或至少一个特定的插桩 gem（例如 -rack、-rails）。

PHP

运行 otel-checker check sdk --language=php：

  • PHP 版本（>= 8.0）。
  • 已安装 Composer。
  • composer.json 和 composer.lock 存在。
  • 必需的包：open-telemetry/api、open-telemetry/sem-conv、 open-telemetry/sdk、open-telemetry/exporter-otlp。
  • 自动插桩（默认）：至少一个插桩包（例如 symfony、pdo、laravel、wordpress、guzzle）。

Collector

运行 otel-checker check collector：

  • config.yaml 存在且可读，并解析为有效的 YAML。
  • 至少一个 otlp 接收器已配置 http 协议。
  • 至少一个 otlphttp / otlp_http 导出器具有匹配 Grafana Cloud 格式（https://*.grafana.net/otlp）的端点；当设置为 localhost 时发出警告。
  • 对于 traces、metrics 和 logs 管道中的每一个：导出器列表 包含一个 otlphttp / otlp_http 导出器，且接收器列表 包含一个 otlp 接收器。

支持命名组件（例如 otlphttp/grafana_cloud、otlp/app）。

Beyla

[!NOTE] 待定

Alloy

[!NOTE] 待定