AI Skills
opentelemetry

opentelemetry

熱門

使用 OpenTelemetry 檢測任何應用程式，並將指標、日誌、追蹤傳送至 Grafana Cloud 或自建的 Mimir、Loki、Tempo、Pyroscope。涵蓋 Go、Java（Grafana JVM agent）、Python（`opentelemetry-instrument`）、Node.js、.NET（`Grafana.OpenTelemetry`）的 SDK 自動檢測，以及 Beyla eBPF 零程式碼方案；Grafana Cloud OTLP 閘道 + 基本認證（instanceID + API key，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。

203星標
17分支
更新於 2026/7/28
獲取技能源代碼

相關技能

flox-environments24萬cloud11萬api-security-testing5.9萬
SKILL.md
唯讀
名稱
opentelemetry
描述

使用 OpenTelemetry 檢測任何應用程式，並將指標、日誌、追蹤傳送至 Grafana Cloud 或自建的 Mimir、Loki、Tempo、Pyroscope。涵蓋 Go、Java（Grafana JVM agent）、Python（`opentelemetry-instrument`）、Node.js、.NET（`Grafana.OpenTelemetry`）的 SDK 自動檢測，以及 Beyla eBPF 零程式碼方案；Grafana Cloud OTLP 閘道 + 基本認證（instanceID + API key，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
  • 基本認證憑證：數字 instance ID + 具有 MetricsPublisher、LogsPublisher、TracesPublisher 角色的 API token
  • 一個要檢測的應用程式

常見工作流程

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 測試憑證（空 body）
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（格式錯誤的 payload）— 不是 401（認證失敗）或 404（錯誤端點）。

2. 自動檢測 Java 應用程式並驗證

# 1. 下載 Grafana JVM agent（單一 jar）
curl -sLO https://github.com/grafana/grafana-opentelemetry-java/releases/latest/download/grafana-opentelemetry-java.jar

# 2. 使用 agent 和步驟 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 已注入 agent
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 → instance ID 不是數字，或 API key 缺少 publisher 角色
  • 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 providers

資源