使用范例将指标和跟踪记录相关联

本文档介绍了范例，即附加到指标数据点的示例数据点。范例的一个用途是存储跟踪记录的链接，以便您可以将指标与跟踪记录数据相关联。本文档还介绍了如何使用 OpenTelemetry 生成范例。

范例简介

范例是一种将任意数据与指标数据相关联的方法。您可以使用它们将非指标数据附加到测量值。范例的一个用途是将跟踪记录数据与指标数据相关联。在 Cloud Monitoring 中，范例可以附加到具有 Distribution 值类型的指标数据。分布值指标会收集许多测量值，并将其分组到存储桶中。每个“点”都是一个直方图，即列出存储桶计数的数组。系统不会保留实际测量值，只保留存储桶计数。如需了解详情，请参阅分布值指标简介。

写入指标数据点时，可以将 Exemplar 对象数组附加到该数据。在进行使用时，范例可将有用的信息附加到指标数据。例如，当 OpenTelemetry 写入范例时，它会将链接附加到跟踪记录的当前 span。

直方图数据通常使用热图显示。当“点”包含范例时，Cloud Monitoring 会使用点为热图添加注解：

• 如需查看指标点的摘要信息，请激活注解的提示。
• 如需访问跟踪记录，请选择注解。

例如，使用 Go 生成跟踪记录和指标中所述的示例应用使用 OpenTelemetry 写入指标数据、跟踪记录数据和范例。以下屏幕截图显示了多次执行应用后的 prometheus/http_server_duration_milliseconds/histogram 指标值：

上一个屏幕截图展示了多个范例。一个范例的提示已展开，它显示日期、跟踪记录名称、百分位和延迟时间值。

选择注解后，将显示范例中链接的跟踪记录：

如果显示的信息不够详细，您可以选择在 Trace 中查看，这会打开 Trace 探索器页面。在该页面上，您可以查看跟踪记录属性并访问指向日志条目的链接。

如何启用 OpenTelemetry 范例

如前面的示例所示，您可以配置 OpenTelemetry 来写入将跟踪记录的当前 span 与指标测量值相关联的范例。但是，如需写入范例，您必须执行以下操作：

1. 配置 OpenTelemetry 指标和跟踪记录 SDK。

2. 如需在自定义插桩中添加范例，您需要确保在 span 中记录指标，并通过指标测量值从 span 传递上下文。

   例如，computeSubrequests 函数遵循上述指南。函数 subRequestsHistogram.Record 在 tracer.Start 之后以及 span.End（会延迟）之前进行调用。另请注意，上下文 ctx 会从 tracer.Start 传递到 Record 函数：

   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
   }
   

   如需详细了解此示例，请参阅向应用添加自定义跟踪记录和指标。

后续步骤

• OpenTelemetry
• OpenTelemetry 范例
• OpenTelemetry 指标数据模型
• OpenTelemetry 直方图