简要介绍如何对 Cloud Trace 进行插桩

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本文档概述了如何对 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。

  • 配置 Zipkin 服务器以从 Zipkin 客户端接收跟踪记录,然后将这些跟踪记录转发到 Cloud Trace 进行分析。如需了解此方法,请参阅将 Cloud Trace 与 Zipkin 搭配使用

  • 配置 Spring Boot 应用以将其收集的跟踪记录数据转发到 Cloud Trace。如需了解此过程,请参阅 Spring Cloud for Google Cloud: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 位的数字。它在您的各个请求之间应该是唯一的,除非您有意将请求捆绑在一起。

  • 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 示例。示例是可以附加到分布测量结果的示例点。例如,您可能希望延迟时间指标包含网址的标签。您无法向指标添加网址标签,因为指标的基数较高,这会导致性能问题。不过,您可以创建一个记录网址的示例。如需了解详情,请参阅 Exemplar

如需查看示例,请执行以下操作:

  1. 绘制分布值指标的图表,并将图表类型设置为热图图表。您可以在信息中心创建图表或使用 Metrics Explorer
  2. 在图表的工具栏中,选择图表工具栏中的 Trace exeversal 图标 。有关示例,请参阅图表工具栏

如需创建范例,您可以编写自己的自定义指标,也可以使用 OpenCensus 等库。如需了解自定义指标的一般信息,请参阅以下内容:

以下代码示例展示了如何编写示例:

  1. 创建额外信息以添加到存储桶计数中:

    • SpanContext 对象存储项目 ID、跟踪记录 ID 和 Span ID。确保这些字段与发送到 Cloud Trace 的跟踪记录的值一致。Cloud Monitoring 使用这些字段确定要显示的跟踪记录。

    • DroppedLabels 对象用于定义其他标签。以下代码示例添加了一个标签,键为“Label”,值为“Dropped”。在前面介绍的延迟时间指标示例中,可能会添加一个键为“网址”的标签。

  2. Point 写入时序:

    • TimeInterval 字段定义了相应点的开始时间和结束时间。
    • DistributionValue 字段用于指定数据。数据包括 Distribution 存储桶的定义和存储桶值。此字段还包含要使用数据写入的任何示例。该示例编写了两个示例,其中一个示例包含 span 上下文,后者包含丢弃的标签对象。
import (
	"fmt"
	"time"

	"cloud.google.com/go/monitoring/apiv3/v2/monitoringpb"
	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	"google.golang.org/protobuf/types/known/anypb"
)

// Generates metric TimeSeries points containing Exemplars with attached tracing span.
func createDataPointWithExemplar(projectID string) (*monitoringpb.Point, error) {
	// projectID := "my-cloud-project-id"
	end := time.Now().Unix()
	traceId := "0000000000000001"
	spanId := "00000001"
	spanCtx, err := anypb.New(&monitoringpb.SpanContext{
		SpanName: fmt.Sprintf("projects/%s/traces/%s/spans/%s", projectID, traceId, spanId),
	})
	if err != nil {
		return nil, err
	}
	droppedLabels, err := anypb.New(&monitoringpb.DroppedLabels{
		Label: map[string]string{"Label": "Dropped"},
	})
	if err != nil {
		return nil, err
	}
	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}, Attachments: []*anypb.Any{spanCtx, droppedLabels}},
					{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint, nil
}

配置 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 和其他开源代码库的链接,请转到您所用语言的设置页面: