AI Skills
opentelemetry

opentelemetry

热门

使用 OpenTelemetry 检测任何应用，并将指标/日志/追踪发送到 Grafana Cloud 或自托管的 Mimir/Loki/Tempo/Pyroscope。涵盖 Go、Java（Grafana JVM 代理）、Python（`opentelemetry-instrument`）、Node.js、.NET（`Grafana.OpenTelemetry`）的 SDK 自动检测，以及 Beyla eBPF 零代码方案；Grafana Cloud OTLP 网关 + 基本认证（实例 ID + API 密钥，base64）；环境变量配置（`OTEL_EXPORTER_OTLP_*`、`OTEL_RESOURCE_ATTRIBUTES`）；Alloy/OTel-Collector 管道；Kubernetes Operator 注入注解；以及头部采样和尾部采样。适用于检测服务、将 OTLP 指向 Grafana Cloud、从 Jaeger/Datadog/New Relic 迁移、选择头部采样与尾部采样，或调试“Explore 中不显示 spans”的场景——即使用户说“自动检测我的 Java 应用”、“发送追踪到 Grafana”、“我该设置哪些环境变量”、“OTLP 端点”或“Operator 注入”而未明确提及 OpenTelemetry。

203Star
17Fork
更新于 2026/7/28
获取 Skill源代码

相关 Skills

fastapi10万image-generation7.8万zustand8.1万
SKILL.md
readonly只读
name
opentelemetry
description

使用 OpenTelemetry 检测任何应用，并将指标/日志/追踪发送到 Grafana Cloud 或自托管的 Mimir/Loki/Tempo/Pyroscope。涵盖 Go、Java（Grafana JVM 代理）、Python（`opentelemetry-instrument`）、Node.js、.NET（`Grafana.OpenTelemetry`）的 SDK 自动检测，以及 Beyla eBPF 零代码方案；Grafana Cloud OTLP 网关 + 基本认证（实例 ID + API 密钥，base64）；环境变量配置（`OTEL_EXPORTER_OTLP_*`、`OTEL_RESOURCE_ATTRIBUTES`）；Alloy/OTel-Collector 管道；Kubernetes Operator 注入注解；以及头部采样和尾部采样。适用于检测服务、将 OTLP 指向 Grafana Cloud、从 Jaeger/Datadog/New Relic 迁移、选择头部采样与尾部采样，或调试“Explore 中不显示 spans”的场景——即使用户说“自动检测我的 Java 应用”、“发送追踪到 Grafana”、“我该设置哪些环境变量”、“OTLP 端点”或“Operator 注入”而未明确提及 OpenTelemetry。

使用 Grafana 的 OpenTelemetry

文档: https://grafana.com/docs/opentelemetry/

厂商无关的检测管道。应用通过 OTLP 协议发送数据 → Alloy（或直接）→ Grafana Cloud（Mimir / Loki / Tempo / Pyroscope）。

后端

信号 后端
指标 Grafana Mimir
日志 Grafana Loki
追踪 Grafana Tempo
性能分析 Grafana Pyroscope

前提条件

  • Grafana Cloud 堆栈 或 自托管的 Mimir / Loki / Tempo
  • Cloud OTLP 端点: https://otlp-gateway-<region>.grafana.net/otlp
  • 基本认证凭据: 数字实例 ID + 具有 MetricsPublisher + LogsPublisher + TracesPublisher 角色的 API 令牌
  • 一个待检测的应用

常见工作流

1. 认证到 Grafana Cloud OTLP 端点

# 1. 构建认证头
INSTANCE_ID=123456
API_KEY="glc_eyJ..."
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic $(echo -n "${INSTANCE_ID}:${API_KEY}" | base64)"
export OTEL_RESOURCE_ATTRIBUTES="service.name=myapp,service.namespace=myteam,deployment.environment=prod"

# 2. 使用 curl POST 对 OTLP 追踪端点进行冒烟测试（空请求体）
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST -H "Content-Type: application/x-protobuf" \
  -H "Authorization: Basic $(echo -n "${INSTANCE_ID}:${API_KEY}" | base64)" \
  "$OTEL_EXPORTER_OTLP_ENDPOINT/v1/traces" --data-binary '\n'
# 期望返回 400（格式错误的有效负载）—— 而不是 401（认证失败）或 404（端点错误）。

2. 自动检测 Java 应用并验证

# 1. 下载 Grafana JVM 代理（单个 jar）
curl -sLO https://github.com/grafana/grafana-opentelemetry-java/releases/latest/download/grafana-opentelemetry-java.jar

# 2. 使用代理和步骤 1 中的环境变量运行
java -javaagent:./grafana-opentelemetry-java.jar -jar myapp.jar

# 3. 生成流量，然后在 Grafana → Explore → Tempo 中验证：
#    TraceQL: { resource.service.name = "myapp" }
#    期望约 30 秒内出现 spans。同时验证指标：
#    PromQL: count by (service_name)({service_name="myapp"})

3. 自动检测 Python 应用

pip install "opentelemetry-distro[otlp]"
opentelemetry-bootstrap -a install

# 使用与步骤 1 相同的环境变量，然后：
opentelemetry-instrument python app.py

# 以相同方式验证 —— Explore → Traces 过滤 service.name=myapp。

4. 添加 Alloy 作为缓冲/采样收集器

# 应用指向本地 Alloy（gRPC 最快）
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Alloy 环境变量用于转发到 Cloud
export GRAFANA_CLOUD_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
export GRAFANA_CLOUD_INSTANCE_ID=$INSTANCE_ID
export GRAFANA_CLOUD_API_KEY=$API_KEY
alloy run /etc/alloy/config.alloy

# 验证 Alloy 已接收并转发
curl -s http://localhost:12345/metrics | grep otelcol_exporter_sent_spans

完整的 Alloy 配置 + 尾部采样块 + OTel Collector YAML + K8s Operator 安装: references/collector-config.md。

各语言 SDK 详情（Go 完整代码、Node 手动设置、.NET ASP.NET Core、所有环境变量细节）: references/instrumentation.md。

5. Kubernetes —— 通过 Operator 自动注入

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata: { name: my-instrumentation }
spec:
  exporter: { endpoint: http://otelcol:4317 }
  propagators: [tracecontext, baggage]
  java:
    image: us-docker.pkg.dev/grafanalabs-global/docker-grafana-opentelemetry-java-prod/grafana-opentelemetry-java:2.3.0-beta.1
  nodejs: {}
  python: {}

然后为 Pod 添加注解：

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    # 或: inject-nodejs, inject-python, inject-dotnet

# 验证 Operator 已注入代理
kubectl describe pod <pod> | grep -A2 'opentelemetry-auto-instrumentation'
# 然后运行相同的 Grafana Explore 检查。

采样 —— 何时选择哪种

# 头部采样（成本低，在开始时决定；可能丢失罕见错误）
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1   # 10%

尾部采样（在查看整个追踪后决定 —— 保留错误并采样其余部分）需要 Alloy / OTel-Collector 的 tail_sampling 处理器；完整配置块在 references/collector-config.md 中。

关键环境变量

变量 示例
OTEL_EXPORTER_OTLP_ENDPOINT https://otlp-gateway-prod-us-east-0.grafana.net/otlp
OTEL_EXPORTER_OTLP_PROTOCOL grpc 或 http/protobuf
OTEL_EXPORTER_OTLP_HEADERS Authorization=Basic <base64>
OTEL_RESOURCE_ATTRIBUTES service.name=app,service.namespace=team,deployment.environment=prod
OTEL_SERVICE_NAME service.name 的简写
OTEL_TRACES_SAMPLER / _ARG parentbased_traceidratio / 0.1

故障排除

  • OTLP 网关返回 401 → 实例 ID 不是数字，或 API 密钥缺少发布者角色
  • 404 → 端点 URL 错误（必须以 /otlp 结尾）
  • Spans 缺失 → 检查 OTEL_EXPORTER_OTLP_PROTOCOL 是否与传输协议匹配（Cloud OTLP 网关 = http/protobuf，本地 Alloy = grpc）
  • Node.js 自动检测在打包后失效 → 像 @vercel/ncc 这样的打包工具会破坏 require 钩子
  • Python 在 Gunicorn / uWSGI 下不显示 spans → 在 post-fork 钩子中重新初始化 OTel 提供者

资源