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

本文档介绍了如何在 Google Kubernetes 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 Telemetry, 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 Telemetry, 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. Kubernetes 集群。如果您没有 Kubernetes 集群，请按照 GKE 快速入门中的说明进行操作。

2. 以下命令行工具：

   • gcloud
   • kubectl

   gcloud 和 kubectl 工具是 Google Cloud CLI 的一部分。如需了解如何安装这些工具，请参阅管理 Google Cloud CLI 组件。如需查看已安装的 gcloud CLI 组件，请运行以下命令：

           gcloud components list
           

为收集器配置权限

如果您已停用 GKE Workload Identity，则可以跳过本部分。

如需确保 OpenTelemetry 收集器的 Kubernetes 服务账号拥有导出遥测数据所需的权限，请让您的管理员为 OpenTelemetry 收集器的 Kubernetes 服务账号授予项目的以下 IAM 角色：

重要提示：您必须向 OpenTelemetry 收集器的 Kubernetes 服务账号（而不是您的用户账号）授予这些角色。如果未能向正确的主账号授予这些角色，可能会导致权限错误。

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

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

您的管理员也可以通过自定义角色或其他预定义角色向 OpenTelemetry 收集器的 Kubernetes 服务账号授予所需的权限。

如需配置权限，请使用以下 add-iam-policy-binding 命令：

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/logging.logWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/monitoring.metricWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudtrace.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector

在运行这些命令之前，请替换以下变量：

• PROJECT_ID：项目的标识符。
• PROJECT_NUMBER： Google Cloud 项目编号。

部署收集器

可以直接从自行管理的 OTLP Kubernetes 注入代码库提供的经过审查的示例部署收集器流水线。在将 PROJECT_ID 替换为您的 Google Cloud 项目的 ID 后，您可以使用以下命令直接从 GitHub 部署：

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export PROJECT_NUMBER=PROJECT_NUMBER
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest.git/k8s/base | envsubst | kubectl apply -f -

在运行这些命令之前，请替换以下变量：

• PROJECT_ID：项目的标识符。
• PROJECT_NUMBER：项目的数字标识符。

配置收集器

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

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

提供的收集器配置

您可以在 otlp-k8s-ingest 代码库中找到适用于 Kubernetes 环境的收集器配置：

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace using OTLP http/proto
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  googleclientauth:


processors:
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection

  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)

  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")

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - metricstarttime
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    traces:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: http://${env:MY_POD_IP}:14317
              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 和 cluster_name。

• k8sattributes：自动将 Kubernetes 资源属性映射到遥测标签。

• transform：重命名与 Google Cloud受监控的资源上的标签发生冲突的指标标签。

接收器

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

可用组件

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

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

生成遥测数据

本部分介绍如何部署一个示例应用并将该应用指向收集器的 OTLP 端点，以及在Google Cloud中查看遥测数据。示例应用是一个小型生成器，用于将跟踪记录、日志和指标导出到收集器。

如果您已有使用 OpenTelemetry SDK 进行插桩处理的应用，则可以改为将相应应用指向收集器的端点。

如需部署示例应用，请运行以下命令：

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml

如需将使用 OpenTelemetry SDK 的现有应用指向收集器的端点，请将 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量设置为 http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317。

几分钟后，应用生成的遥测数据会开始通过收集器流向 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. 点击 将信息中心添加到您的列表，然后完成对话框。

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

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