使用 OpenTelemetry 在應用程式中新增自訂追蹤記錄和指標

在應用程式程式碼中加入自訂 OpenTelemetry 檢測，即可記錄自訂追蹤記錄 span 和指標，評估應用程式特定行為，不限於標準架構程式庫收集的資料。您可以將本文中的概念套用至以 OpenTelemetry 支援的任何語言編寫的應用程式；如需背景資訊，請參閱「應用程式開發人員的可觀測性」和「選擇檢測方法」。

本文件中的範例使用 Go 檢測範例中說明的 Go 範例應用程式，該應用程式可在 GitHub 中取得。

事前準備

啟用 Cloud Logging、Cloud Monitoring 和 Cloud Trace API (如果尚未啟用)。

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

建立自訂追蹤記錄

如要從應用程式產生自訂追蹤記錄，請新增檢測程式碼，建立 OpenTelemetry 跨度。在 OpenTelemetry 中，span 是追蹤記錄的構成元素。

如要建立 Span，請按照下列步驟操作：

  1. 修改應用程式，取得 OpenTelemetry Tracer。在 OpenTelemetry 中，追蹤器是 Span 的建立者。您可以按照下列程式碼所示取得追蹤器。如要查看完整範例，請在範例的工具列中選取 GitHub 標誌。

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    追蹤程式名稱 (以 scopeName 表示) 會識別所產生追蹤記錄的檢測範圍。

  2. 使用 tracer 例項建立 Span。在下列程式碼範例中，computeSubrequests 函式會在每次呼叫時產生 Span：

    func computeSubrequests(r *http.Request, subRequests int) error {
	// Add custom span representing the work done for the subrequests
	ctx, span := tracer.Start(r.Context(), "subrequests")
	defer span.End()

	// Make specified number of http requests to the /single endpoint.
	for i := 0; i < subRequests; i++ {
		if err := callSingle(ctx); err != nil {
			return err
		}
	}
	// record number of sub-requests made
	subRequestsHistogram.Record(ctx, int64(subRequests))
	return nil
}

    在上述程式碼範例中，從 computeSubrequests 函式產生的 Span 代表整個函式完成的工作。這是因為函式的第一個步驟是使用 tracer.Start 和 defer 關鍵字啟動新的 Span，然後 span.End() 確保 Span 在函式結束前結束。

建立自訂指標

如要從應用程式產生指標，請新增檢測程式碼，記錄應用程式執行期間的測量結果。

如要建立指標，請按照下列步驟操作：

  1. 修改應用程式，取得 OpenTelemetry Meter。在 OpenTelemetry 中，計量器可讓您存取指標檢測，以便記錄指標。您可以按照下列程式碼取得計量器：

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    計量器名稱 (以 scopeName 表示) 會識別所產生指標的檢測範圍。

  2. 使用 meter 例項建立可記錄指標的檢測。舉例來說，下列程式碼會使用 meter 建立 OpenTelemetry 直方圖：

    sleepHistogram, err = meter.Float64Histogram("example.sleep.duration",
	metric.WithDescription("Sample histogram to measure time spent in sleeping"),
	metric.WithExplicitBucketBoundaries(0.05, 0.075, 0.1, 0.125, 0.150, 0.2),
	metric.WithUnit("s"))
if err != nil {
	panic(err)
}

    上述程式碼會產生名為 sleepHistogram 的直方圖。

  3. 使用 sleepHistogram 執行個體記錄睡眠時間，這是在叫用 randomSleep 函式時決定：

    func randomSleep(r *http.Request) time.Duration {
	// simulate the work by sleeping 100 to 200 ms
	sleepTime := time.Duration(100+rand.Intn(100)) * time.Millisecond
	time.Sleep(sleepTime)

	hostValue := attribute.String("host.value", r.Host)
	// custom histogram metric to record time slept in seconds
	sleepHistogram.Record(r.Context(), sleepTime.Seconds(), metric.WithAttributes(hostValue))
	return sleepTime
}

    系統會根據 OpenTelemetry 匯出工具設定，從應用程式匯出這些檢測工具記錄的指標。

後續步驟