Go OpenTelemetry 指標實作:指標類型、View 與 OTLP
用 OpenTelemetry Go Metrics SDK 量測 HTTP 請求與訂單,透過 View 捨棄不需要的指標流,並在本機驗證 OTLP/gRPC 匯出。
結帳端點變慢時,成立的訂單數仍可能維持原樣。請求耗時直方圖能看出回應時間的變化,訂單計數器則回答實際成立了幾筆訂單。Go 的 OpenTelemetry Metrics SDK 可以在同一個應用程式收集兩種指標,再用 OTLP 送出。
本文讓兩筆合成 HTTP 請求從 Go SDK 送到本機的 OpenTelemetry Collector。一筆成功,另一筆回傳 503。從這兩筆資料就能對照自動 HTTP 指標、業務指標,以及用來捨棄無用資料流的 View。
啟動本機 OTLP 接收端
將下列設定存成 collector.yaml,執行 otelcol-contrib --config=collector.yaml。gRPC 接收端在本機回送位址監聽,debug 匯出器會印出收到的資料,不需要另外接後端。
receivers:
otlp:
protocols:
grpc:
endpoint: 127.0.0.1:14317
exporters:
debug:
verbosity: detailed
service:
pipelines:
metrics:
receivers: [otlp]
exporters: [debug]
範例以 Go 1.26、OpenTelemetry Go SDK 1.47.0、Go contrib 0.72.0 和 Collector Contrib 0.165.0 核驗。請在空目錄安裝相依套件。
go mod init example.com/otel-order-metrics
go get go.opentelemetry.io/otel/metric@v1.47.0 \
go.opentelemetry.io/otel/sdk@v1.47.0 \
go.opentelemetry.io/otel/sdk/metric@v1.47.0 \
go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc@v1.47.0 \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@v0.72.0 \
go.opentelemetry.io/contrib/instrumentation/runtime@v0.72.0
將 MeterProvider 接到處理函式
MeterProvider 為應用程式設定資源名稱、定期讀取器和 View。讀取器透過 OTLP/gRPC 匯出指標點。程式執行期間每 30 秒讀取一次。這個短程式會先關閉測試 HTTP 伺服器,再用有獨立逾時的 Shutdown 完成最後一次收集。將程式存為 main.go 後,執行 go run .。
package main
import (
"context"
"errors"
"fmt"
"io"
"log"
"net/http"
"net/http/httptest"
"strings"
"time"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
otelruntime "go.opentelemetry.io/contrib/instrumentation/runtime"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
"go.opentelemetry.io/otel/metric"
sdkmetric "go.opentelemetry.io/otel/sdk/metric"
"go.opentelemetry.io/otel/sdk/resource"
)
func orderHandler(meter metric.Meter) (http.Handler, error) {
created, err := meter.Int64Counter("orders.created", metric.WithUnit("{order}"))
if err != nil {
return nil, err
}
inFlight, err := meter.Int64UpDownCounter("orders.inflight", metric.WithUnit("{request}"))
if err != nil {
return nil, err
}
queueDepth, err := meter.Int64Gauge("orders.queue.depth", metric.WithUnit("{order}"))
if err != nil {
return nil, err
}
duration, err := meter.Float64Histogram("orders.process.duration", metric.WithUnit("s"),
metric.WithExplicitBucketBoundaries(0.05, 0.1, 0.25, 0.5, 1, 5))
if err != nil {
return nil, err
}
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
started := time.Now()
inFlight.Add(ctx, 1)
defer inFlight.Add(ctx, -1)
defer func() { duration.Record(ctx, time.Since(started).Seconds()) }()
queueDepth.Record(ctx, 2)
if _, err := io.Copy(io.Discard, r.Body); err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
if r.URL.Query().Get("fail") == "1" {
w.WriteHeader(http.StatusServiceUnavailable)
return
}
created.Add(ctx, 1, metric.WithAttributes(attribute.String("channel", "app")))
w.WriteHeader(http.StatusCreated)
}), nil
}
func run() (err error) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
exporter, err := otlpmetricgrpc.New(ctx, otlpmetricgrpc.WithEndpoint("127.0.0.1:14317"),
otlpmetricgrpc.WithInsecure())
if err != nil {
return err
}
mp := sdkmetric.NewMeterProvider(
sdkmetric.WithResource(resource.NewSchemaless(attribute.String("service.name", "order-service"))),
sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter, sdkmetric.WithInterval(30*time.Second))),
sdkmetric.WithView(sdkmetric.NewView(
sdkmetric.Instrument{Name: "http.server.request.body.size"},
sdkmetric.Stream{Aggregation: sdkmetric.AggregationDrop{}},
)),
)
defer func() {
shutdownCtx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
err = errors.Join(err, mp.Shutdown(shutdownCtx))
}()
if err := otelruntime.Start(otelruntime.WithMeterProvider(mp)); err != nil {
return err
}
const route = "/orders"
handler, err := orderHandler(mp.Meter("example.com/order-service"))
if err != nil {
return err
}
mux := http.NewServeMux()
mux.Handle("POST "+route, otelhttp.NewHandler(
handler, route, otelhttp.WithMeterProvider(mp),
))
server := httptest.NewServer(mux)
defer server.Close()
for _, suffix := range []string{"", "?fail=1"} {
req, err := http.NewRequestWithContext(ctx, http.MethodPost,
server.URL+route+suffix, strings.NewReader("demo"))
if err != nil {
return err
}
resp, err := server.Client().Do(req)
if err != nil {
return err
}
resp.Body.Close()
fmt.Println(resp.StatusCode)
}
return nil
}
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
WithInsecure() 會關閉傳輸層保護,這裡的目的地是本機測試接收端。遠端接收應依實際部署設定接收位址、TLS 和所需憑證。
分開看 HTTP 指標和業務指標
程式會印出 201 和 503。在 Collector 找到 service.name=order-service 以及 http.server.request.duration。此版本的 otelhttp 為每筆完成且有埋點的請求記錄一次耗時;直方圖的 Count 也能統計同一維度的請求數。這兩筆回應的狀態碼屬性不同,各有一次觀測。業務計數器 orders.created 只記成功成立的訂單,channel=app 的值應為一。
HTTP 中介層也會記錄內容大小。SDK 的 View 會在匯出前捨棄 http.server.request.body.size,保留回應內容大小和請求耗時。若想減少保留指標的維度,可用 View 過濾屬性,並確認剩下的標籤仍能回答原本的查詢。刪除整條指標流與刪掉其中幾個屬性,影響的資料不同。
按要量測的問題選擇指標儀器
| 想知道什麼 | 儀器 | 量測方式 |
|---|---|---|
| 成立了幾筆訂單? | Counter | 以非負值累加。跨程序查詢需辨識時間性與重設。 |
| 有幾個請求還在處理? | UpDownCounter | 進入時加一,結束時以相同屬性減一。兩筆請求結束後讀到零。 |
| 佇列現在有多深? | Gauge | 記下實際量到的值。範例使用固定值二,也可用 ObservableGauge 在收集時讀取。 |
| 處理時間如何分布? | Histogram | 以秒記錄到直方圖。範例在 250 ms 設有桶邊界。 |
直方圖應在告警門檻附近有合適的桶邊界。P95 是根據桶計數估算的,精細度會影響結果。跨副本合併時,確認桶配置相容,再由後端先合併分布、後估算分位數。
使用穩定的指標名稱,並宣告單位,例如 s、By。屬性只保留會拿來查詢的維度,例如渠道或地區。請求 ID 和完整 URL 可能讓每個請求都產生一條時間序列,可改用 /orders/{id} 這類路由樣板。 高基數如何形成
將相同指標送到觀測雲
本機 Collector 顯示的是後端轉換前的 OTLP 資料。若改用 DataKit,先啟用 OpenTelemetry 收集器並確認網路路徑,再把 gRPC 匯出器指向接收端的 gRPC 監聽位址。若使用 OTLP/HTTP,請改用 HTTP/Protobuf 匯出器並設定實際的指標路徑。DataKit 文件預設的 HTTP 指標路徑是 /otel/v1/metrics,HTTP 監聽埠預設為 9529。 DataKit OpenTelemetry 收集器(簡體中文)
送出固定筆數的請求,先核對收到的名稱、單位、屬性與直方圖格式,再建立監控器。若調查時要一起看追蹤,先對齊服務與環境欄位,並確認 span 已被收集。聚合後的指標點涵蓋多次觀測,通常無法直接對應單一追蹤。 設定觀測雲監控器(簡體中文)
部署時的常見問題
服務重啟後,計數器會怎樣?
累積型 OTLP 資料點可帶有起始時間。程序重啟後,新資料流會重新累積,應驗證後端查詢如何計算跨重設的速率。若配置為 Delta,資料點表達每個區間的增量,後端要依相同口徑解讀。
能合併多個副本的 Summary 嗎?
各用戶端算出的分位數通常無法合成整體分位數。Go Metrics API 用 Histogram 記錄分布,後端可先合併相容的直方圖,再從合併後的分布估算分位數。
SDK 多久匯出一次?
範例是 30 秒。部署時可依告警視窗、接收端容量和需要的資料時效挑選間隔。間隔縮短會增加批次數,應用實際流量量測開銷。
怎麼收集 Go 執行環境的指標?
範例對同一個 provider 呼叫 runtime.Start。指定的 contrib 版本會註冊 go.goroutine.count、go.memory.gc.goal 等指標。若需要排程延遲直方圖 go.schedule.duration,依文件將 runtime.NewProducer() 加到讀取器。名稱與可用性要看實際版本。 Go 執行環境埋點文件(英文)
