在 Compute Engine 上部署 Google 构建的 OpenTelemetry 收集器

本文档介绍了如何在 Compute Engine 上运行 Google 构建的 OpenTelemetry 收集器，以从插桩的应用中收集 OTLP 日志、指标和跟踪记录，然后将这些数据导出到 Google Cloud。

准备工作

运行 Google 构建的 OpenTelemetry 收集器需要以下资源：

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Compute Engine 实例。如果您没有 Compute Engine 实例，请按照创建并启动 Compute Engine 实例中的说明进行操作。
2. gcloud 的安装。如需了解如何安装 gcloud，请参阅安装 gcloud CLI。

为收集器配置权限

默认情况下，Compute Engine 实例使用 Compute Engine 默认服务账号 [e-mail]。此服务账号通常具有写入本文档中所述的指标和日志所需的 Identity and Access Management (IAM) 角色：

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

如果您选择使用用户代管式服务账号而不是默认服务账号，则必须为该账号分配这些相同的角色。如需了解详情，请参阅服务账号。

安装收集器

如需将 Google 构建的 OpenTelemetry 收集器作为软件包安装到 Compute Engine 实例中，请完成以下步骤。

Debian 和 Ubuntu

1. 使用 SSH 或类似工具建立与虚拟机实例的终端连接，并确保您拥有 sudo 访问权限。

2. 运行以下命令以设置软件包代码库：

   sudo mkdir -p /etc/apt/keyrings
   sudo curl -o /etc/apt/keyrings/otelcol-google.asc https://packages.cloud.google.com/apt/doc/apt-key.gpg
   cat <<EOF | sudo tee /etc/apt/sources.list.d/otelcol-google.list
   deb [signed-by=/etc/apt/keyrings/otelcol-google.asc] https://us-apt.pkg.dev/projects/cloud-ops-agents-artifacts google-cloud-opentelemetry-collector-apt main
   EOF
   

3. 刷新软件包管理器并安装软件包：

   sudo apt update
   sudo apt install otelcol-google
   

   安装完成后，由 Google 构建的 OpenTelemetry 收集器会自动启动。

CentOS、RHEL 和 Rocky Linux

1. 使用 SSH 或类似工具建立与虚拟机实例的终端连接，并确保您拥有 sudo 访问权限。

2. 运行以下命令以设置软件包代码库：

   cat <<EOF | sudo tee /etc/yum.repos.d/otelcol-google.repo
   [otelcol-google]
   name=Google Built OpenTelemetry Collector
   baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
   autorefresh=0
   enabled=1
   type=rpm-md
   gpgcheck=1
   repo_gpgcheck=0
   gpgkey=http://dl.google.com/linux/linux_signing_key.pub
   EOF
   

3. 安装软件包：

   sudo yum install otelcol-google
   

   安装完成后，由 Google 构建的 OpenTelemetry 收集器会自动启动。

SLES

1. 使用 SSH 或类似工具建立与虚拟机实例的终端连接，并确保您拥有 sudo 访问权限。

2. 运行以下命令以设置软件包代码库：

   cat <<EOF | sudo tee /etc/zypp/repos.d/otelcol-google.repo
   [otelcol-google]
   name=Google Built OpenTelemetry Collector
   baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
   autorefresh=0
   enabled=1
   type=rpm-md
   gpgkey=http://dl.google.com/linux/linux_signing_key.pub
   EOF
   

3. 安装软件包：

   sudo zypper install otelcol-google
   

   安装完成后，由 Google 构建的 OpenTelemetry 收集器会自动启动。

Windows

1. 使用 RDP 或类似工具连接到您的实例，然后登录到 Windows。

2. 右键点击 PowerShell 图标并选择以管理员身份运行，以管理员权限打开 PowerShell 终端。

3. 运行以下 PowerShell 命令以设置软件包代码库：

   googet addrepo otelcol-google `
       https://us-googet.pkg.dev/projects/cloud-ops-agents-artifacts/repos/google-cloud-opentelemetry-collector-googet
   

4. 安装软件包：

   googet install otelcol-google
   

   安装完成后，由 Google 构建的 OpenTelemetry 收集器会自动启动。

部署收集器

Google 构建的 OpenTelemetry 收集器默认包含不导出遥测数据的最低配置。如需导出遥测数据，请在安装收集器后，通过替换默认配置来配置收集器。将收集器的配置放在以下文件中：

• 对于 Linux：/etc/otelcol-google/config.yaml
• 对于 Windows：C:\Program Files\Google\OpenTelemetry Collector\config.yaml

配置收集器

我们提供了 OpenTelemetry 收集器配置，供您与 Google 构建的收集器搭配使用。此配置旨在传递大量 OTLP 指标、日志和跟踪记录。此配置还可用于防止常见的注入问题。您可以向配置添加元素，但我们强烈建议您不要移除元素。

本部分介绍了所提供的配置、关键组件（例如导出器、处理器、接收器）和其他可用组件。

提供的收集器配置

您可以在 opentelemetry-operations-collector 代码库的 google-built-opentelemetry-collector 目录中找到收集器配置：

receivers:
  # Open two OTLP servers:
  # - On port 4317, open an OTLP GRPC server
  # - On port 4318, open an OTLP HTTP server
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        cors:
          # This effectively allows any origin
          # to make requests to the HTTP server.
          allowed_origins:
          - http://*
          - https://*
        endpoint: localhost:4318

processors:
  # The batch processor is in place to regulate both the number of requests
  # being made and the size of those requests.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The memorylimiter will check the memory usage of the collector process.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # The resourcedetection processor is configured to detect GCP resources.
  # Resource attributes that represent the GCP resource the collector is
  # running on will be attached to all telemetry that goes through this
  # processor.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform/collision:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  # Traces -> Cloud Trace
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
  googlecloud:
    log:
      default_log_name: opentelemetry-collector

  # The googlemanagedprometheus exporter will send metrics to
  # Google Managed Service for Prometheus.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
  googlemanagedprometheus:

extensions:
  # Opens an endpoint on 13133 that can be used to check the
  # status of the collector. Since this does not configure the
  # `path` config value, the endpoint will default to `/`.
  #
  # When running on Cloud Run, this extension is required and not optional.
  # In other environments it is recommended but may not be required for operation
  # (i.e. in Container-Optimized OS or other GCE environments).
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions:
  - health_check
  pipelines:
    logs:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
    metrics/otlp:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - transform/collision
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    traces:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
  # Internal telemetry for the collector supports both push and pull-based telemetry data transmission.
  # Leveraging the pre-configured OTLP receiver eliminates the need for an additional port.
  #
  # Docs:
  # https://opentelemetry.io/docs/collector/internal-telemetry/
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: grpc
                endpoint: http://localhost:4317
                insecure: true

导出器

收集器配置包含以下导出器：

• googlecloud 导出器，用于日志和跟踪记录。此导出器配置了默认日志名称。

• googlemanagedprometheus 导出器，用于指标。此导出器不需要任何配置，但具有配置选项。如需了解 googlemanagedprometheus 导出器的配置选项，请参阅 Google Cloud Managed Service for Prometheus 文档中的 OpenTelemetry 收集器使用入门。

处理器

收集器配置包括以下处理器：

• batch：配置为在达到每个请求的 Google Cloud 条目数量上限时，或按照每 5 秒的 Google Cloud 最小时间间隔（以先发生者为准）来批处理遥测请求。

• memory_limiter：限制收集器的内存用量，当超过限制时，通过丢弃数据点来防止内存不足崩溃。

• resourcedetection：自动检测 Google Cloud 资源标签，例如 project_id。

接收器

收集器配置仅包含 otlp 接收器。 如需了解如何对应用进行插桩以将 OTLP 跟踪记录和指标发送到收集器的 OTLP 端点，请参阅选择插桩方法。

可用组件

Google 构建的 OpenTelemetry 收集器包含大多数用户在 Google Cloud Observability 中实现丰富体验所需的组件。如需查看可用组件的完整列表，请参阅 opentelemetry-operations-collector 代码库中的组件。

如需请求更改或添加可用组件，请在 opentelemetry-operations-collector 代码库中打开功能请求。

生成遥测数据

您可以使用开源 telemetrygen 工具来测试配置。该链接中包含有关下载和运行该工具的说明。如需运行该工具，您必须安装 Go 或 Docker。

几分钟后，应用生成的遥测数据会开始通过收集器流向 Google Cloud 控制台以用于每个信号。

查看遥测数据

Google 构建的 OpenTelemetry 收集器会将插桩应用中的指标、日志和跟踪记录发送到 Google Cloud Observability。Collector 还会发送自我可观测性指标。以下部分介绍了如何查看此遥测数据。

查看指标

Google 构建的 OpenTelemetry 收集器会收集 Prometheus 指标，您可以使用 Metrics Explorer 查看这些指标。收集的指标取决于应用的插桩，但 Google 构建的收集器也会写入一些自身指标。

如需查看 Google 构建的 OpenTelemetry 收集器收集的指标，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 Metrics Explorer 页面：

   进入 Metrics Explorer

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
3. 在指标元素中，展开选择指标菜单，在过滤条件栏中输入 Prometheus Target，然后使用子菜单选择一个特定资源类型和指标：
   1. 在活跃资源菜单中，选择 Prometheus 目标。
   2. 如需选择指标，请使用活跃指标类别和活跃指标菜单。 Google 构建的 OpenTelemetry 收集器收集的指标具有前缀 prometheus.googleapis.com。
   3. 点击应用。

4. 如需添加用于从查询结果中移除时序的过滤条件，请使用过滤条件元素。

5. 配置数据的查看方式。
   

   如果指标的测量结果是累积的，则 Metrics Explorer 会自动按校准时间段对测量数据进行归一化，从而使图表显示速率。如需了解详情，请参阅种类、类型和转换。

   测量整数或双精度值时（例如使用 counter 指标），Metrics Explorer 会自动对所有时序求和。如需更改此行为，请将汇总条目的第一个菜单设置为无。

   如需详细了解如何配置图表，请参阅使用 Metrics Explorer 时选择指标。

查看跟踪记录

如需查看跟踪记录数据，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 Trace 探索器页面：

   转到 Trace 探索器

   您也可以使用搜索栏查找此页面。

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
3. 在页面的表格部分，选择一行。

4. 在跟踪记录详细信息面板的甘特图中，选择一个 span。

   此时会打开一个面板，其中显示跟踪请求的相关信息。这些详细信息包括方法、状态代码、字节数以及调用方的用户代理。

5. 如需查看与此跟踪记录关联的日志，请选择日志和事件标签页。

   该标签页会显示各个日志。如需查看日志条目的详细信息，请展开日志条目。您还可以点击查看日志，并使用 Logs Explorer 查看日志。

如需详细了解如何使用 Cloud Trace 探索器，请参阅查找和探索跟踪记录。

查看日志

在 Logs Explorer 中，您可以检查日志，还可以查看关联的跟踪记录（如果存在）。

1. 在 Google Cloud 控制台中，前往 segment Logs Explorer 页面：

   前往 Logs Explorer

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

2. 在插桩应用中找到日志条目。如需查看详细信息，请展开日志条目。

3. 点击包含跟踪记录消息的日志条目中的 跟踪记录，然后选择查看跟踪记录详细信息。

   跟踪记录详情面板随即会打开并显示所选跟踪记录。

如需详细了解如何使用 Logs Explorer，请参阅使用 Logs Explorer 查看日志。

观察和调试收集器

Google 构建的 OpenTelemetry 收集器会自动提供自我可观测性指标，可帮助您监控性能并确保 OTLP 注入流水线的持续正常运行时间。

如需监控收集器，请安装收集器的示例信息中心。此信息中心可让您一目了然地了解来自收集器的多个指标，包括正常运行时间、内存用量以及对 Google Cloud Observability 的 API 调用。

如需安装信息中心，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 信息中心页面：

   前往信息中心

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 点击信息中心模板。
3. 搜索 OpenTelemetry 收集器信息中心。
4. 可选：如需预览信息中心，请选择相应信息中心。

5. 点击 将信息中心添加到您的列表，然后完成对话框。

   您可以通过该对话框选择信息中心的名称，并向信息中心添加标签。

如需详细了解如何安装信息中心，请参阅安装信息中心模板。