插桩示例概览

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

本文档介绍了为 Go、Java、Node.js 和 Python 语言提供的插桩示例的结构。这些示例提供了有关如何对应用进行插桩处理的指南。

您可能会对说明不同配置的其他示例感兴趣：

• 使用范例将指标和跟踪记录相关联介绍了如何配置 Go 应用以生成范例。范例是附加到指标数据点的示例数据点。您可以使用范例将跟踪记录与指标数据相关联。

• 使用 Ops Agent 和 OpenTelemetry 协议 (OTLP) 介绍了如何配置 Ops Agent 和 OTLP 接收器以从应用收集指标和跟踪记录。

示例的运作方式

Go、Java、Node.js 和 Python 示例使用 OpenTelemetry 协议收集跟踪记录和指标数据。这些示例会配置日志记录框架以写入结构化日志，并将 OpenTelemetry 收集器配置为从应用的 stdout 流中进行读取。如需了解框架建议，请参阅选择插桩方法。

应用是使用 Docker 构建和部署的。使用 OpenTelemetry 对应用进行插桩处理时，您无需使用 Docker。

您可以在 Cloud Shell、 Google Cloud资源或本地开发环境中运行这些示例。

深入探究

这些示例使用 OpenTelemetry 收集器作为边车来接收和丰富应用的遥测数据，收集器随后使用Google Cloud 导出器将其发送到您的 Google Cloud 项目。该导出器会将遥测数据转换为与 Cloud Trace API、Cloud Monitoring API 或 Cloud Logging API 兼容的格式。接下来，它们会通过发出 API 命令将转换后的数据发送到您的 Google Cloud 项目。

这些示例展示了如何执行以下操作：

1. 配置 OpenTelemetry 以使用 OpenTelemetry 收集器收集指标和跟踪记录。

   如果您查看示例，就会发现此步骤的复杂程度取决于语言。例如，对于 Go，此步骤会将 main 函数配置为调用一个函数来配置指标和跟踪记录的收集。对于 Go，HTTP 服务器和客户端也会更新。

2. 配置日志记录框架以写入结构化日志。

   我们建议您的应用写入结构化日志，这会导致日志载荷格式化为 JSON 对象。对于这些日志，您可以构造查询来搜索特定 JSON 路径，并且可以为日志载荷中的特定字段编制索引。

   某些服务（例如 Google Kubernetes Engine）具有内置代理，可爬取结构化日志并将这些日志发送到您的 Google Cloud 项目。其他服务（例如 Compute Engine）需要您安装代理，以便爬取和发送日志。如果您想了解所安装的代理，请参阅 Ops Agent 概览。

   您无需安装任何代理即可使用这些示例。

3. 配置 Docker 文件。所有示例都包含以下 yaml 文件：

   • docker-compose.yaml：为应用、OpenTelemetry 收集器和负载生成器配置服务。例如，OpenTelemetry 收集器的服务 otelcol 会指定映像、卷和环境变量。OpenTelemetry 收集器的端点由 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量设置，该变量在 app 服务中指定。

   • otel-collector-config.yaml：配置接收器、导出器、处理器和流水线。

     telemetry 服务可为跟踪记录、指标和日志数据定义流水线。每个流水线条目都会指定一个接收器、一个处理器和一个导出器。指标和跟踪记录使用的是同一个接收器 otlp。

     exporters 部分介绍了如何将收集的数据导出到 Google Cloud 项目。对于所有遥测数据，系统都会使用 Google Cloud 导出器。该导出器会将遥测数据转换为与 Cloud Trace API、Cloud Monitoring API 或 Cloud Logging API 兼容的格式。接下来，它会通过发出 API 命令将转换后的数据发送到您的 Google Cloud 项目。

   • docker-compose.creds.yaml：此文件可选择性地将Google Cloud 凭据文件装载到 otelcol 容器中。在本地机器上运行示例时需要此文件，因为在这种情况下，应用默认凭据 (ADC) 只能以文件的形式提供。

所需权限

如果您在 Cloud Shell、 Google Cloud资源或本地开发环境中运行示例，则只需具备本部分中列出的权限即可。对于生产应用，通常由服务账号提供用于写入日志、指标和跟踪记录数据的凭据。

• 如需获得让示例应用写入日志、指标和跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：

  • Logs Writer (roles/logging.logWriter)
  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  • Cloud Trace Agent (roles/cloudtrace.agent)

• 如需获得查看日志、指标和跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：

  • Logs Viewer (roles/logging.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
  • Cloud Trace User (roles/cloudtrace.user)

  如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

  您也可以通过自定义角色或其他预定义角色来获取所需的权限。

必需的 API

以下信息介绍了向 Google Cloud 项目发送遥测数据所需的 API：

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

后续步骤

• Go 示例。
• Java 示例。
• Node.js 示例。
• Python 示例。