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

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

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

您可以在 GitHub 找到範例程式碼 (與「Go 檢測範例」一文所述的 Go 應用程式相同)。如要查看完整範例，請按一下「更多」圖示 ，然後選取「在 GitHub 上查看」。

事前準備

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

建立自訂追蹤記錄

如要從應用程式產生自訂追蹤記錄，請加入可建立 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 匯出工具設定，從應用程式匯出這些工具記錄的指標。

後續步驟