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

本文說明如何使用 OpenTelemetry，在應用程式中加入可觀測性程式碼。OpenTelemetry 提供檢測程式庫，可為熱門架構產生遙測資料。您可以新增自訂檢測，測量應用程式的特定行為，藉此擴增程式庫產生的遙測資料。

本文所述原則和概念適用於以 OpenTelemetry 支援的所有語言編寫的應用程式。如要進一步瞭解插樁，請參閱下列文件：

您可以在 GitHub 找到範例程式碼，也就是 Go 檢測範例中說明的 Go 應用程式。如要查看完整範例，請按一下「更多」，然後選取「在 GitHub 上查看」。

事前準備

啟用 Cloud Logging、Cloud Monitoring 和 Cloud Trace API。

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

建立自訂追蹤記錄

如要從應用程式產生自訂追蹤記錄，請加入可建立 OpenTelemetry 時距的檢測程式碼。在 OpenTelemetry 中，時距是追蹤記錄的建構基礎。

如要建立時距，請執行下列操作：

  1. 修改應用程式，取得 OpenTelemetry Tracer。在 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. 使用 tracer 例項建立範圍。在下列程式碼範例中，每當呼叫 computeSubrequests 函式時，系統就會產生範圍：

    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 函式產生的範圍代表整個函式完成的工作。這是因為函式的第一個步驟是使用 tracer.Start 和 defer 關鍵字啟動新的範圍，而 span.End() 則可確保範圍在函式結束前結束。

建立自訂指標

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

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

  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 匯出工具設定，從應用程式匯出這些工具記錄的指標。

後續步驟