针对 GKE 上的 Java 工作负载使用 OpenTelemetry 零代码插桩

借助 OpenTelemetry 零代码插桩，您可以自动从 Google Kubernetes Engine (GKE) 上运行的 Java 应用收集指标和 跟踪记录，而无需 修改应用代码。在本演练中，您将向 GKE 部署示例 Java 应用，配置 OpenTelemetry 自动插桩，并在 Google Cloud Observability 中查看生成的遥测数据。虽然这些步骤侧重于 Java 工作负载，但您可以将此方法扩展到 其他受支持的语言。

为何使用零代码插桩？

零代码插桩（也称为自动插桩） 在 OpenTelemetry 中是一种强大的工具，可让应用开发者向其代码添加可配置的 可观测性，而无需编写任何其他代码 或修改任何现有代码。零代码插桩的工作原理是自动 向主动部署的应用库添加插桩，通过发出 黄金信号来提供有关应用性能的 可靠洞见。 这使得零代码插桩成为应用可观测性之旅的绝佳起点。

Java 中的零代码插桩通过对该语言生态系统中广泛使用的常用库进行插桩来发出指标和跟踪 span。对于 Java，指标包括：

• JVM 运行时指标由 Java 平台发出
• 从 Java HTTP 客户端库和 Google HTTP 客户端库等库发出的 HttpClient 指标和 HttpClient span。
• 数据库客户端指标和 数据库客户端 span，由 JDBC和Lettuce等库发出。

发出的指标集取决于要进行插桩的应用以及应用使用的库。如需查看 Java 零代码插桩 代理可以插桩的库 和框架的完整列表，请参阅受支持的库和框架。

借助自动插桩，您可以执行以下操作：

• 获取黄金信号监控，而无需进行任何代码更改。
• 将高 p99.9 延迟时间与涵盖每个 RPC 调用的各个用户跟踪记录相关联。
• 从各种常用库和框架中获取一致的遥测数据（包括指标、日志和跟踪记录）。

如需详细了解零代码插桩， 请参阅 OpenTelemetry 零代码。

概览

如需向 GKE 上运行的 Java 工作负载添加可观测性，您需要部署以下组件：

• OpenTelemetry 零代码插桩，用于从应用生成遥测数据。
• OpenTelemetry 收集器，用于收集 应用生成的遥测数据，使用关键元数据和上下文对其进行扩充，并将其 路由到 Google Cloud 以供使用。

在本演练中，您将在 GKE 上部署一个经过插桩的 Java 应用，该应用会向 Google Cloud发出指标和跟踪记录。然后，您可以 使用的 Google Cloud可观测性产品（例如 Metrics Explorer、Logs Explorer 和 Trace 探索器）查看这些遥测信号。如需了解如何查看和使用生成的遥测数据，请参阅 查看遥测数据。

本演练使用以下收费服务来写入信号：

• Cloud Monitoring 的 Managed Service for Prometheus
• Cloud Logging
• Cloud Trace
• Google Kubernetes Engine
• Cloud Build
• Artifact Registry

如需根据您的预计使用量来估算费用，请使用价格计算器。

准备工作

本部分介绍了如何设置环境以部署应用并对其进行插桩，然后运行该应用。

选择或创建 Google Cloud 项目

为此演练选择一个 Google Cloud 项目。如果您还没有 项目 Google Cloud ，请进行创建：

1. 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

2. Verify that billing is enabled for your Google Cloud project.

安装命令行工具

本文档使用以下命令行工具：

• gcloud
• kubectl

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

gcloud components list

设置环境变量

为了减少常用值的输入量、防止输入错误，并使本文档中的命令可运行，请设置以下环境变量：

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export CLUSTER_NAME=CLUSTER_NAME
export CLUSTER_REGION=us-east1
export ARTIFACT_REGISTRY=opentelemetry-autoinstrument-registry
export REGISTRY_LOCATION=us-east4

在运行这些命令之前，请替换以下变量或使用默认值：

• PROJECT_ID：项目的标识符。
• CLUSTER_NAME：您的集群的名称。这可以指新集群或现有集群。
• us-east1：集群所在的区域。如果您使用的是现有集群，请使用该集群的区域。
• opentelemetry-autoinstrument-registry：您的 Artifact Registry 仓库的名称。 这可以指新仓库或现有仓库。
• us-east4：Artifact Registry 仓库所在的区域。 如果您使用的是现有仓库，请使用该仓库的区域。

如果您在运行本文档中的命令时遇到错误，请检查这些变量是否在终端环境中正确设置。

启用 API

如需使用本文档中的服务，您必须在项目中启用以下 API： 在您的 Google Cloud 项目中：

• Artifact Registry API：artifactregistry.googleapis.com
• Cloud Build API：cloudbuild.googleapis.com
• Google Kubernetes Engine：container.googleapis.com
• Identity and Access Management API：iam.googleapis.com
• Cloud Logging API：logging.googleapis.com
• Cloud Monitoring API：monitoring.googleapis.com
• Telemetry API：telemetry.googleapis.com

这些 API（Telemetry API 除外）可能已在您的 项目中启用。 Google Cloud 运行以下命令以列出已启用的 API：

gcloud services list

启用尚未启用的任何 API。 请特别注意 Telemetry API，telemetry.googleapis.com；此文档 可能是您第一次遇到此 API。

如需启用尚未启用的 API，请运行相应 API 的命令：

gcloud services enable artifactregistry.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable iam.googleapis.com
gcloud services enable logging.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable telemetry.googleapis.com

获取权限

1. 如需获得运行应用并让其写入日志、指标和跟踪记录数据所需的权限，请让管理员为您授予以下 IAM 角色：

   • Logs Writer (roles/logging.logWriter) 项目的
   • 项目的 Monitoring Metric Writer (roles/monitoring.metricWriter)
   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter) 项目的
   • 项目的 Developer (roles/container.developer)
   • Cloud Build Editor (roles/cloudbuild.builds.editor) 项目
   • Artifact Registry Writer (roles/artifactregistry.writer) 项目的
   • 项目的 Service Account User (roles/iam.serviceAccountUser)
   • 配额项目的 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

   如果您在 Cloud Shell、 Google Cloud 资源或本地 开发环境中运行示例，则只需具备这些权限即可。如需了解如何配置配额项目，请参阅 设置配额项目。

   重要提示：生产环境应用通常依赖于服务帐号来提供写入日志、指标和跟踪记录数据所需的凭据。在这些情况下，请向服务 账号授予之前的角色。

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

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

设置集群

为示例应用和收集器设置 GKE 集群：

1. 运行以下命令以登录： Google Cloud

   gcloud auth login
   gcloud config set project PROJECT_ID
   

2. 如果您还没有 GKE 集群，请运行以下命令来创建 Autopilot 集群：

   gcloud container clusters create-auto --region us-east1 CLUSTER_NAME --project PROJECT_ID
   

3. 如需与集群互动，请运行以下命令来连接本地 kubectl 实用程序：

   gcloud container clusters get-credentials CLUSTER_NAME --region us-east1 --project PROJECT_ID
   

部署 Java 应用

本部分中的步骤将在您的集群上部署一个未经插桩的示例 Java 应用 （OpenTelemetry Spring Boot 插桩示例） 。本部分使用 Cloud Build 和 Artifact Registry 来创建和存储应用映像。

1. 如果您还没有 Artifact Registry 仓库，请运行以下命令来创建仓库：

   gcloud artifacts repositories create opentelemetry-autoinstrument-registry --repository-format=docker --location=us-east4 --description="GKE Autoinstrumentation sample app"
   

2. 运行以下命令以克隆示例应用：

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git
   

3. 设置以下环境变量：

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export ARTIFACT_REGISTRY=opentelemetry-autoinstrument-registry
   export REGISTRY_LOCATION=us-east4
   

4. 运行以下命令来构建应用映像并将其推送到 Artifact Registry 仓库：

   pushd opentelemetry-samples/java/instrumentation-quickstart && \
   gcloud builds submit --config <(envsubst < cloudbuild-uninstrumented-app.yaml) . && \
   popd
   

   注意 ：如果您使用的是 Mac，则运行之前的命令可能 需要您先从 Homebrew 安装 gettext 软件包。如需了解更多 信息，请参阅这篇 Stack Overflow 文章。 安装软件包后，您可能需要再次设置环境变量。

5. 为应用创建 Kubernetes 部署配置文件。 复制以下配置并将其保存到名为 deployment.yaml 的文件中：

   apiVersion: v1
   kind: Service
   metadata:
     name: quickstart-app
     labels:
       app: quickstart-app
       app.kubernetes.io/part-of: gke-autoinstrument-guide
   spec:
     ports:
       - port: 8080
         targetPort: 8080
         name: quickstart-app
     selector:
       app: quickstart-app
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: quickstart-app
     labels:
       app: quickstart-app
       app.kubernetes.io/part-of: gke-autoinstrument-guide
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: quickstart-app
     template:
       metadata:
         labels:
           app: quickstart-app
       spec:
         containers:
           - name: quickstart-app
             image: us-east4-docker.pkg.dev/PROJECT_ID/opentelemetry-autoinstrument-registry/java-quickstart:latest
             ports:
               - containerPort: 8080
                 name: quickstart-app
   

6. 运行以下命令来为应用创建命名空间：

   kubectl create namespace APPLICATION_NAMESPACE
   

7. 运行以下命令，将部署配置应用于您的集群：

   kubectl apply -f deployment.yaml -n APPLICATION_NAMESPACE
   

8. 创建部署后，可能需要一段时间才能创建 Pod 并开始运行。如需检查 Pod 的状态，请运行以下命令：

   kubectl get po -n APPLICATION_NAMESPACE -w
   

   如需停止查看 Pod 状态，请输入 Ctrl-C 以停止该命令。

设置 OpenTelemetry 收集器实例

在本部分中，您将创建另一个部署，该部署将在 GKE 集群中运行 Google 构建的 OpenTelemetry 收集器实例。收集器配置为使用以下导出器导出数据：

• 使用 OTLP HTTP 导出器 的指标
• 使用 OTLP HTTP 导出器 的跟踪记录
• 使用 Google Cloud 导出器 的日志

您可以按照 Managed OpenTelemetry for GKE中的说明，在受管环境中使用 Google 构建的 OpenTelemetry 收集器，而不是按照本文档中的手动步骤部署 OpenTelemetry Collector。

注意 ：本文档使用 Google 推荐的 配置来设置收集器，该配置足以满足大多数用户和使用场景的需求。虽然您 可以部署自定义收集器来支持高级使用场景，但您需要 保留某些配置选项以保持与 Google Cloud的兼容性。 如需详细了解如何配置自定义收集器，请参阅 在 Google Kubernetes Engine 上部署 Google 构建的 OpenTelemetry 收集器。

1. 运行以下命令，为 OpenTelemetry 收集器的部署授权 Kubernetes 服务帐号：

   export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   
   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./subject/ns/opentelemetry/sa/opentelemetry-collector \
     --condition=None
   
   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./subject/ns/opentelemetry/sa/opentelemetry-collector \
     --condition=None
   
   gcloud projects add-iam-policy-binding projects/PROJECT_ID \
     --role=roles/telemetry.tracesWriter \
     --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID./subject/ns/opentelemetry/sa/opentelemetry-collector \
     --condition=None
   

2. 运行以下命令，使用推荐的默认配置在 GKE 集群上部署 Google 构建的 OpenTelemetry 收集器实例：

   kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest//k8s/base?ref=otlpmetric | envsubst | kubectl apply -f -
   

   此配置会将收集器部署到 opentelemetry 命名空间。

3. 创建部署后，可能需要一段时间才能创建 Pod 并开始运行。如需检查 Pod 的状态，请运行以下命令：

   kubectl get po -n opentelemetry -w
   

   如需停止查看 Pod 状态，请输入 Ctrl-C 以停止该命令。

配置 OpenTelemetry 零代码插桩

如需为部署在 GKE 上的应用配置 OpenTelemetry 零代码插桩，请在 GKE 集群上安装 OpenTelemetry 运算符。OpenTelemetry 运算符提供对 Kubernetes 自定义资源定义 (CRD)（即插桩资源）的访问权限，该资源用于将自动插桩注入到集群内运行的 Kubernetes 资源中。

插桩资源通过使用特殊注解“注入”或“应用”到特定工作负载。OpenTelemetry 运算符会观察集群内运行的资源上的这些注解，并在这些资源管理的应用中注入适当的插桩。

1. 如果您还没有安装 Helm CLI， 请运行以下命令来安装 Helm：

   curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
   
   chmod 700 get_helm.sh
   
   ./get_helm.sh                         
   

2. 如果您还没有在集群上安装 cert-manager，请运行以下命令来安装它：

   helm repo add jetstack https://charts.jetstack.io
   
   helm repo update
   
   helm install \
   --create-namespace \
   --namespace cert-manager \
   --set installCRDs=true \
   --set global.leaderElection.namespace=cert-manager \
   --set extraArgs={--issuer-ambient-credentials=true} \
   cert-manager jetstack/cert-manager
   

3. 运行以下命令并使用 0.140.0 或更高版本来安装 OpenTelemetry 运算符：

   kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.140.0/opentelemetry-operator.yaml
   

4. 通过创建名为 instrumentation.yaml 且包含以下内容的文件，为 插桩自定义资源 创建配置文件：

   apiVersion: opentelemetry.io/v1alpha1
   kind: Instrumentation
   metadata:
     name: sample-java-auto-instrumentation
   spec:
     exporter:
       endpoint: http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317
     sampler:
       type: parentbased_traceidratio
       # Adjust the sampling rate to control cost
       argument: "0.01"
   
     java:
       env:
         - name: OTEL_EXPORTER_OTLP_PROTOCOL
           value: grpc
         - name: OTEL_LOGS_EXPORTER
           value: none
   

5. 为运算符创建命名空间。您可以使用与应用命名空间 APPLICATION_NAMESPACE 相同的值。

   kubectl create namespace INSTRUMENTATION_NAMESPACE
   

6. 运行以下命令，在集群中创建插桩自定义资源并应用 instrumentation.yaml 文件：

   kubectl apply -f instrumentation.yaml -n INSTRUMENTATION_NAMESPACE
   

7. 将自动插桩注解应用于之前部署的示例 Java 应用 。运行以下命令，使用注解修补原始部署：

   kubectl patch deployment.apps/quickstart-app -n APPLICATION_NAMESPACE -p '{"spec":{"template":{"metadata":{"annotations":{"instrumentation.opentelemetry.io/inject-java": "'"INSTRUMENTATION_NAMESPACE"'/sample-java-auto-instrumentation"}}}}}'
   

8. 修补部署（这会导致应用部署重启）后，您可以运行以下命令来检查应用中 Pod 的状态：

   kubectl get po -n APPLICATION_NAMESPACE -w
   

   如需停止查看 Pod 状态，请输入 Ctrl-C 以停止该命令。

部署在 GKE 集群中的 Java 应用现在已自动插桩。

从已部署的应用生成遥测数据

如需从自动插桩的应用生成遥测数据，您需要向应用发送请求以模拟用户活动。您可以通过运行流量模拟器来生成稳定的流量流。本部分介绍了如何下载模拟器、使用 Cloud Build 构建模拟器、将映像存储在 Artifact Registry 中，以及部署模拟器：

1. 运行以下命令来下载流量模拟器应用：

   mkdir traffic-simulator && pushd traffic-simulator && \
   curl -O https://raw.githubusercontent.com/GoogleCloudPlatform/opentelemetry-operator-sample/refs/heads/main/recipes/self-managed-otlp-ingest/traffic/hey.Dockerfile  && \
   curl -O https://raw.githubusercontent.com/GoogleCloudPlatform/opentelemetry-operator-sample/refs/heads/main/recipes/self-managed-otlp-ingest/traffic/cloudbuild-hey.yaml && \
   popd
   

   上述命令会执行以下操作：

   1. 为构建流量模拟器应用创建一个单独的目录。
   2. 下载应用的 Dockerfile。
   3. 下载 Cloud Build 配置以构建应用映像。

2. 运行以下命令，使用 Cloud Build 创建应用映像并将其推送到 Artifact Registry：

   pushd traffic-simulator && \
   gcloud builds submit --config <(envsubst < cloudbuild-hey.yaml) . && \
   popd
   

3. 通过将以下内容复制到 traffic-simulator 目录中名为 quickstart-traffic.yaml 的文件中，为模拟器创建部署配置文件：

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: traffic-simulator
     labels:
       app.kubernetes.io/part-of: gke-autoinstrument-guide
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: traffic-simulator
     template:
       metadata:
         labels:
           app: traffic-simulator
       spec:
         containers:
           - name: traffic-simulator
             image: us-east4-docker.pkg.dev/PROJECT_ID/opentelemetry-autoinstrument-registry/hey:latest
             args:
             - -c=2
             - -q=1
             - -z=1h
             - http://quickstart-app:8080/multi
   

4. 运行以下命令来部署流量模拟器：

   pushd traffic-simulator && \
   kubectl apply -f quickstart-traffic.yaml -n APPLICATION_NAMESPACE && \
   popd
   

5. 创建部署后，可能需要一段时间才能创建 Pod 并开始运行。如需检查 Pod 的状态，请运行以下命令：

   kubectl get po -n APPLICATION_NAMESPACE -w
   

   如需停止查看 Pod 状态，请输入 Ctrl-C 以停止该命令。

查看遥测数据

流量模拟器开始向应用发送请求后，已部署的 Java 应用会生成遥测数据。指标和跟踪记录可能需要几 分钟时间才能开始显示在 Google Cloud。

• OpenTelemetry 运算符注入的插桩依赖于 OpenTelemetry Java 代理。OpenTelemetry Java 代理包含 许多常用 Java 库和框架的内置插桩，这些库和框架会发出指标。

• 注入的插桩还会自动捕获对示例应用公开的任何端点进行的任何调用的跟踪记录。 流量模拟器会以固定的速率不断向 Java 应用公开的 /multi 端点发送请求。/multi 端点会依次向 /single 端点发送请求以生成最终响应。这些互动最终会成为可以使用 Trace 探索器查看的跟踪记录。

查看指标

您可以在 Cloud Monitoring 的 Metrics Explorer 中查看自动插桩的指标。本部分包含使用 PromQL 编写的示例查询。

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

进入 Metrics Explorer

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

您可以为示例应用查看的一些指标包括：

• JVM 运行时指标：OpenTelemetry Java 代理会发出有关底层 JVM 的指标。这些指标会公开有关 JVM 内存、垃圾回收、类、线程和其他相关概念的信息。如需查看受支持的 JVM 指标的 完整列表，请参阅 JVM 运行时指标 语义约定页面。

  • JVM 内存用量：将以下 PromQL 查询粘贴到 Metrics Explorer 中：

    sum(avg_over_time({"process.runtime.jvm.memory.usage"}[${__interval}]))
    

  • JVM CPU 利用率：将以下 PromQL 查询粘贴到 Metrics Explorer 中：

    sum(avg_over_time({"process.runtime.jvm.cpu.utilization"}[${__interval}]))
    

    下图显示了 JVM CPU 利用率指标：

    

• Spring Boot 指标：示例应用 使用 Spring Boot 框架，该框架也受 OpenTelemetry 零代码插桩（适用于 Java）的支持。

  • HTTP 客户端平均时长：将以下 PromQL 查询粘贴到 Metrics Explorer 中：

    sum(rate({"http.client.duration_sum"}[${__interval}])) by (cluster, job) / sum(rate({"http.client.duration_count"}[${__interval}])) by (cluster, job)
    

  • HTTP 服务器平均时长：将以下 PromQL 查询粘贴到 Metrics Explorer 中：

    sum(rate({"http.server.duration_sum"}[${__interval}])) by (cluster, job) / sum(rate({"http.server.duration_count"}[${__interval}])) by (cluster, job)
    

    下图显示了 Spring Boot HTTP 服务器平均时长指标：

    

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

查看跟踪记录

您可以在 Cloud Trace 的 Trace 探索器中查看自动插桩的跟踪记录。您可以在 Trace 探索器中按“服务名称”过滤这些跟踪记录，并将服务名称设置为 quickstart-app。

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

转到 Trace 探索器

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

以下屏幕截图显示了 OpenTelemetry quickstart-app 部署生成的跟踪记录：

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

清理

如果您创建了一个新 Google Cloud 项目，但不再需要该项目，则 可以运行以下命令将其删除：

gcloud projects delete PROJECT_ID

如果您使用的是现有项目，则可以删除您在本演练中创建的资源以节省费用：

• 运行以下命令来删除 GKE 集群：

  gcloud container clusters delete CLUSTER_NAME --location=us-east1
  

• 运行以下命令来删除 Artifact Registry 仓库：

  gcloud artifacts repositories delete opentelemetry-autoinstrument-registry --location=us-east4