概览

本文档概述了如何对 Cloud Trace 应用进行插桩处理。如需详细了解如何设置 Cloud Trace,请参阅特定语言的设置页面。

Cloud Trace 会为您的应用提供分布式跟踪数据。对应用进行插桩处理后,您可以检查单个请求的延迟时间数据,并在 Cloud Trace 控制台中查看整个应用的总体延迟时间。

Cloud Trace 建议您使用 OpenTelemetry。OpenTelemetry 是由 OpenCensus 和 OpenTracing 合并而成的开源产品。

何时对应用进行插桩处理

要让您的应用向 Cloud Trace 提交跟踪记录,必须对其进行插桩处理。您可以使用 Google 客户端库对代码进行插桩处理。不过,建议您使用 OpenTelemetryOpenCensus 对应用进行插桩处理。这些是开源跟踪软件包。OpenTelemetry 正在积极开发中,并且是首选软件包。

对应用进行插桩处理以实现跟踪

您可以通过以下三种方式为应用实现跟踪:

  • 使用 OpenTelemetry 和关联的 Cloud Trace 客户端库。这是对应用进行插桩处理的推荐方法。

  • 如果 OpenTelemetry 客户端库不适用于您所用语言,请使用 OpenCensus。

  • 使用 Cloud Trace API 并编写自定义方法以将跟踪数据发送到 Cloud Trace。

下表列出了每种编程语言的推荐的插桩:

语言 推荐的插桩
C# .NET Cloud Trace API
Go OpenTelemetry
Java OpenTelemetry
Node.js OpenTelemetry
PHP OpenCensus
Python OpenTelemetry
Ruby Cloud Trace API

何时创建 Span

Cloud Trace 客户端库通常会维护一个全局跟踪上下文,其中包含有关当前 span 的信息(包括其跟踪记录 ID 以及是否对跟踪记录进行采样)。这些库通常在 RPC 边界上创建 span。但是,如果默认创建算法不足以满足您的需求,您可能需要创建 span。

当前活跃 span 可由全局跟踪上下文访问,后者有时封装在跟踪器对象中。您可以通过对现有 span 使用自定义注释和标记来添加与应用相关的信息,也可以创建具有各自注释和标记的新子 span,从而更精细地跟踪应用的行为。由于上下文是全局性的,因此更新上下文的多线程应用必须使用适当的隔离。

何时提供身份验证凭据

在 Google Cloud 上运行应用时,您无需为应用提供身份验证凭据,也无需在应用中指定 Google Cloud 项目 ID。对于某些语言,即使您在 Google Cloud 上运行,也需要指定 Google Cloud 项目 ID。

如果您在 Google Cloud 之外运行,则需要向应用提供身份验证凭据。您还需要在应用中指定 Google Cloud 项目 ID。

有关详情,请转到特定语言的设置页面。

如何强制跟踪请求

Cloud Trace 不会对每个请求进行采样。例如,如果您使用 Java 和 OpenCensus,则每 10000 个请求中只有 1 个请求会被跟踪。如果您使用的是 App Engine,则对于每个 App Engine 实例,请求会按每秒 0.1 个请求的速率进行采样。如果您使用 Cloud Trace API,则可以配置自定义速率。某些软件包(例如 Java OpenCensus 软件包)支持配置采样率。

如果您配置具有采样率的微服务,则该采样率仅适用于从该微服务开始的请求。如果您没有为微服务配置采样率,则父上下文的采样率将确定微服务的采样率。

如需强制跟踪特定请求,请在请求中添加 X-Cloud-Trace-Context 标头。标头规范为:

"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"

其中:

  • TRACE_ID 是一个 32 个字符的十六进制值,表示一个 128 位的数字。它在您的请求中应该是唯一的,除非您有意将各请求绑定在一起。您可以使用 UUID。

  • SPAN_ID 是(无符号)span ID 的十进制表示法。它应该在您的跟踪记录中随机生成且具有唯一性。对于后续请求,请将 SPAN_ID 设置为父级请求的 span ID。如需详细了解嵌套跟踪记录,请参阅 TraceSpanRESTRPC)的说明。

  • 要跟踪此请求,TRACE_TRUE 的值必须为 1。不跟踪请求请指定为 0

例如,要使用 cURL 强制跟踪,请运行以下命令:

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b12000100000/1;o=1"

如何创建 Cloud Trace 范例

OpenCensus 会在为 gRPC 服务编写时间序列数据时创建 Cloud Trace 范例。如需查看这些范例,您可以创建一个图表并使用图表的工具栏启用其显示功能。如需了解详情,请参阅使用图表工具栏

如果您有兴趣编写自己的自定义指标,请参阅以下资源:

如果您要编写自定义指标,则可以创建范例。以下 Go 代码段展示了如何在时间序列中创建单个 Point。第一个元素是标记为 Interval 的时间间隔,第二个元素是值。该值是 TypedValue 对象的实例,且必须解析为 distributionValue

import (
	"time"

	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
)

func createDataPointWithExemplar() *monitoringpb.Point {
	end := time.Now().Unix()
	dataPoint := &monitoringpb.Point{
		Interval: &monitoringpb.TimeInterval{
			StartTime: &googlepb.Timestamp{Seconds: end - 60},
			EndTime:   &googlepb.Timestamp{Seconds: end},
		},
		Value: &monitoringpb.TypedValue{Value: &monitoringpb.TypedValue_DistributionValue{
			DistributionValue: &distributionpb.Distribution{
				Count: 14,
				BucketOptions: &distributionpb.Distribution_BucketOptions{Options: &distributionpb.Distribution_BucketOptions_LinearBuckets{
					LinearBuckets: &distributionpb.Distribution_BucketOptions_Linear{NumFiniteBuckets: 2, Width: 3, Offset: 0},
				}},
				BucketCounts: []int64{5, 6, 3},
				Exemplars: []*distributionpb.Distribution_Exemplar{
					{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
					{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint
}

配置 Google Cloud 项目

要使用 Cloud Trace,您的 Google Cloud 项目必须启用 Cloud Trace API。此设置可让您的 Google Cloud 项目接收已经过身份验证的来源的跟踪记录数据。

默认情况下,Google Cloud 项目已启用 Cloud Trace API,因此您无需执行任何操作。如果您已修改 Google Cloud 项目的访问权限范围并希望验证设置,请执行以下操作:

  1. 在 Google Cloud Console 中,转到 API 和服务

    转到“API 和服务”

  2. 点击启用 API 和服务

  3. 在搜索栏中输入 Trace API

  4. 如果系统显示 API 已启用,则表示此 API 已启用,您无需执行任何操作。否则,请点击启用

后续步骤

如需详细的配置信息、示例以及指向 GitHub 和其他开源代码库的链接,请转到您所用语言的设置页面: