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

本文將說明如何使用 OpenTelemetry 在應用程式中新增可觀察性程式碼。OpenTelemetry 提供檢測程式庫，可為熱門架構產生遙測資料。您可以新增用於評估應用程式特定行為的自訂檢測工具，擴充程式庫產生的遙測資料。

本文件所述的原則和概念可套用至使用 OpenTelemetry 支援的所有語言編寫的應用程式。如要進一步瞭解檢測功能，請參閱下列文件：

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

事前準備

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

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 函式每次呼叫時都會產生 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 函式產生的間隔代表整個函式所執行的工作。這是因為函式的首要步驟是使用 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 匯出器設定，從應用程式匯出。

後續步驟