适用于 GKE 的托管式 OpenTelemetry

本文档介绍了适用于 Google Kubernetes Engine (GKE) 的 Managed OpenTelemetry， 可让您将 OpenTelemetry 协议 (OTLP) 跟踪记录、指标和日志从 GKE 上运行的应用发送到 Google Cloud Observability。Managed OpenTelemetry 提供 Google Cloud 提供的唯一托管式解决方案，用于收集 GKE 上的跟踪记录数据。

如需使用适用于 Google Kubernetes Engine (GKE) 的 Managed OpenTelemetry，应用需要已进行插桩，以便使用 OpenTelemetry 协议生成信号。 如需了解详情，请参阅 支持的工作负载。

适用于 GKE 的 Managed OpenTelemetry 有两个组件：

  • 代管式收集：代管式收集器提供集群内 OpenTelemetry 协议端点，作为工作负载以 OTLP 格式发送 跟踪记录、指标和日志的目标， 而无需管理收集器。

  • 自动配置：名为 Instrumentation 的自定义资源可为您的 GKE 工作负载启用自动配置，以生成和注入相关的 OpenTelemetry 跟踪记录、指标和日志。此方法支持 智能体开发套件 (ADK) 以及多模态提示和回答数据。

    您可以将 Instrumentation 自定义资源用于使用 OpenTelemetry SDK 且配置了标准 OpenTelemetry 环境变量的工作负载。此 Instrumentation 自定义资源 instrumentations.telemetry.googleapis.com 与 OpenTelemetry 运算符的 Instrumentation 资源不同。

如需了解使用适用于 GKE 的 Managed OpenTelemetry 的步骤，请参阅 部署适用于 GKE 的 Managed OpenTelemetry。

借助适用于 GKE 的 Managed OpenTelemetry，您可以收集 OTLP 遥测数据，而无需管理和运行 OpenTelemetry 收集器。运行自己的收集器可能会产生开销，包括身份验证、配置、升级和监控。 但是，如果您需要收集器级过滤和控制，则可以使用 Google 构建的 OpenTelemetry 收集器 ，而不是此代管式服务。

OpenTelemetry 提供 API、库和 SDK，用于生成分布式跟踪记录、指标和日志，以便进行应用监控。如需详细了解 OpenTelemetry，请参阅有关OpenTelemetry和OpenTelemetry 协议 (OTLP)的文档。如需详细了解如何生成和收集应用的 运行时行为数据，请参阅 插桩和可观测性。

适用于 GKE 的 Managed OpenTelemetry 的工作原理

适用于 GKE 的 Managed OpenTelemetry 有两个组件：代管式收集和自动配置。

代管式收集

代管式收集通过将代管式 OpenTelemetry 收集器部署到集群中来提供集群内 OTLP 端点。此集群内 OTLP 端点接收 OTLP 格式的跟踪记录、指标和日志。如需接收来自工作负载的数据，必须将工作负载配置为将数据发送到收集器。

代管式收集器的端点为：http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318。

代管式收集会将收集的数据发送到 Google Cloud Observability。然后，这些数据可在以下服务中使用：

您可以使用控制台或 gcloud CLI 为 GKE 集群启用代管式收集。如需查看相关说明，请参阅 在集群中启用适用于 GKE 的 Managed OpenTelemetry。

自动配置

借助自动配置，GKE 可以将 GKE 上运行的工作负载配置为将信号发送到代管式收集器的端点。

您可以使用不同的方法来配置工作负载。 自动配置使用注入到工作负载容器中的环境变量，让工作负载将信号发送到代管式收集器。 如果您要手动配置工作负载，可以使用其他方法。如需了解 详情，请参阅 手动配置。

使用自动配置时，您可以使用 Instrumentation 自定义资源定义配置。然后，GKE 会将环境变量（例如 OTLP 导出器端点）注入到工作负载的容器中。当工作负载的容器具有这些环境变量时，工作负载运行时，OpenTelemetry 数据会发送到代管式收集器。

自动配置适用于原生支持 OpenTelemetry 的工作负载，这意味着它们使用 OpenTelemetry SDK 并使用标准 OpenTelemetry 环境变量进行配置。 如需了解详情，请参阅 支持的工作负载。

如需了解如何使用自动 配置来配置应用，请参阅 将应用配置为使用 Managed OpenTelemetry 收集器。

Instrumentation 自定义资源

您可以使用 Instrumentation 自定义资源执行以下操作：

  • 指定是将环境变量注入到所选 Pod 的容器中，还是注入到命名空间中的所有 Pod 的容器中。
  • 控制收集的数据类型（日志、指标和跟踪记录）。
  • 控制指标数据发送到代管式收集器的频率。
  • 控制跟踪记录数据的采样率。

如需详细了解如何使用 Instrumentation 自定义资源，请参阅 修改配置。

自动注入环境变量

如需将 OpenTelemetry 环境变量自动注入到 GKE 工作负载中，您需要在集群中配置 Instrumentation 对象。 然后，当您在具有 Instrumentation 对象的集群中部署应用时，GKE 会注入这些变量。

部署应用并创建 Pod 时，Instrumentation 对象需要在集群中。如果您在创建 Instrumentation 对象之前部署了应用，则需要 重启应用的 Pod，以触发环境变量的自动注入。

环境变量

当工作负载部署到启用了自动配置的命名空间时，GKE 会将环境变量注入到工作负载的容器中。这些环境 变量是 OpenTelemetry SDK 配置中的 OpenTelemetry 变量。

以下列表包含适用于 GKE 的 Managed OpenTelemetry 可以注入的所有环境变量。注入到容器中的特定环境变量取决于 Instrumentation 自定义资源中的配置。

可以自动注入到容器中的环境变量如下所示：

  • OpenTelemetry 导出器端点。
    • OTEL_EXPORTER_OTLP_ENDPOINT：任何信号类型的基本端点网址。此端点始终指向集群内 Managed OpenTelemetry 收集器 HTTP 端点，用于日志、指标和跟踪记录。 端点为：http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318。
  • 跟踪记录采样率配置。
    • OTEL_TRACES_SAMPLER：将 SDK 用于对跟踪记录进行采样的采样器 设置为以下其中一项：
      • 在自定义资源中配置跟踪记录采样时，为 parentbased_traceidratio。
      • parentbased_always_on 是此环境变量的默认值。 如果未配置此环境变量或在自定义资源中为 null，则使用此值。
    • OTEL_TRACES_SAMPLER_ARG：指定跟踪记录采样率（介于 0.0 和 1.0 之间）。如果未在自定义资源中配置，则使用 1.0。
  • 两次连续指标导出开始之间的延迟间隔。
    • OTEL_METRIC_EXPORT_INTERVAL：两次导出尝试开始之间的时间间隔（以毫秒为单位）（最小值：5000，最大值：300000，默认值：30000）。
  • 按信号类型停用 OTLP 遥测数据导出。当 tracer_provider、meter_provider 或 logger_provider 在 Instrumentation 文件中设置为 null 时，信号导出器会被停用。
    • OTEL_TRACES_EXPORTER：设置为 none 时，停用跟踪记录导出。默认值：otlp。
    • OTEL_METRICS_EXPORTER：设置为 none 时，停用指标导出。默认值：otlp。
    • OTEL_LOGS_EXPORTER：设置为 none 时，停用日志导出。默认值：otlp。
  • 标识 hostNetwork Pod，以便通过 OpenTelemetry 收集器的 Kubernetes 属性处理器 关联元数据。
    • K8S_POD_UID：hostNetwork Pod 的 Pod UID，用于填充 OTEL_RESOURCE_ATTRIBUTES 环境变量中的 k8s.pod.uid 设置。
    • OTEL_RESOURCE_ATTRIBUTES：该值包含 k8s.pod.uid=$(K8S_POD_UID)，以允许 Kubernetes 属性处理器将元数据（例如 k8s.namespace.name、k8s.deployment.name 和 k8s.node.name）与 hostNetwork Pod 相关联。 将元数据与 hostNetwork Pod 相关联后，可以将提取的元数据作为资源属性添加到 span、指标和日志中。
  • 提示和回答。
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'：指示 OpenTelemetry 将 Cloud Storage 对象格式化为 JSON Lines。此环境变量具有固定值：jsonl。
    • OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'：指示 OpenTelemetry 上传提示和回答数据，而不是将这些内容嵌入到跟踪记录 span 中。所上传对象的引用包含在日志条目中。此环境变量具有固定值：upload。
    • OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'：指示 OpenTelemetry 使用最新的 生成式 AI 语义惯例。此环境变量具有固定值：gen_ai_latest_experimental。
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH：指定对象的路径。例如，gs://STORAGE_BUCKET_NAME/PATH

手动配置

您可以使用不同的方法来配置工作负载，以将信号发送到代管式收集器的 端点。 如果您要手动配置工作负载，则可以手动添加和修改环境变量，也可以使用其他方法，例如命令行标志。

我们不建议对同一工作负载同时使用手动配置和自动配置，因为自动配置可能会覆盖手动更改。这种组合可能会使跟踪配置更改变得更加困难。

如需详细了解自动配置，请参阅 自动配置

支持的工作负载

支持的工作负载是指使用 OpenTelemetry 收集应用运行时行为相关数据的工作负载。如果工作负载使用 OpenTelemetry SDK 并使用标准 OpenTelemetry 环境变量进行配置，则原生支持 OpenTelemetry。例如， 智能体开发套件 (ADK) 原生支持 OpenTelemetry。

如需详细了解如何生成和收集应用的运行时行为数据，请参阅 插桩和可观测性。

如果工作负载支持某些类型的 OTLP 数据，而不支持其他类型的数据，则适用于 GKE 的 Managed OpenTelemetry 会收集 OTLP 数据。例如，如果工作负载使用 OpenTelemetry SDK 来实现跟踪记录，但不使用它来实现日志或指标，则适用于 GKE 的 Managed OpenTelemetry 不会收集日志和指标数据。如需详细了解如何 控制要收集的数据类型，请参阅 选择要收集的信号类型。

适用于 GKE Autopilot 合作伙伴的 特权工作负载不支持 OpenTelemetry 配置注入。

结算

向 Google Cloud发送遥测数据时，您需要按提取量 付费。指标按 Google Cloud Managed Service for Prometheus 价格结算，日志按 Cloud Logging 价格结算，跟踪记录按 Cloud Trace 价格结算。

如需了解与跟踪记录、日志和 Google Cloud Managed Service for Prometheus 指标提取关联的费用，请参阅 Google Cloud Observability 价格。

配额

使用适用于 GKE 的 Managed OpenTelemetry 时，Google Cloud Observability 服务的配额适用。有关详情，请参阅：

后续步骤