借助 OpenTelemetry 零代码插桩，您可以自动从 Google Kubernetes Engine (GKE) 上运行的 Java 应用收集指标和跟踪记录，而无需修改应用代码。在本演示中，您会将一个 Java 示例应用部署到 GKE，配置 OpenTelemetry 自动插桩，并在 Google Cloud Observability 中查看生成的遥测数据。虽然这些步骤侧重于 Java 工作负载，但您可以将此方法扩展到其他受支持的语言。
为何使用零代码插桩？
OpenTelemetry 中的零代码插桩（也称为自动插桩）是一种强大的工具，可让应用开发者向其代码添加可配置的可观测性，而无需编写任何其他代码或修改任何现有代码。零代码插桩的工作原理是自动向主动部署的应用库添加插桩，通过发出黄金信号，提供有关应用性能的可靠数据洞见。这使得零代码插桩成为应用可观测性之旅的绝佳起点。
Java 中的零代码插桩通过对该语言生态系统中广泛使用的热门库进行插桩，来发出指标和跟踪 span。对于 Java，指标包括：
- Java 平台发出的 JVM 运行时指标
- 从 Java Http 客户端库和 Google Http 客户端库等库发出的 HttpClient 指标和 HttpClient span。
- 从 JDBC 和 Lettuce 等库发出的数据库客户端指标和数据库客户端 span。
发出的指标集取决于要插桩的应用以及应用使用的库。如需查看可由 Java 零代码插桩代理进行插桩的库和框架的完整列表，请参阅支持的库和框架。
借助自动插桩，您可以执行以下操作：
- 无需进行任何代码更改即可获得黄金信号监控。
- 将较高的 p99.9 延迟时间与跨越每个 RPC 调用的各个用户跟踪记录相关联。
- 从各种常用库和框架中获取一致的遥测数据，包括指标、日志和跟踪记录。
如需详细了解零代码插桩，请参阅 OpenTelemetry 零代码。
概览
如需为在 GKE 上运行的 Java 工作负载添加可观测性，需要部署以下组件：
- OpenTelemetry 零代码插桩，用于从应用生成遥测数据。
- OpenTelemetry 收集器，用于收集应用生成的遥测数据，并使用关键元数据和上下文丰富这些数据，然后将其路由到 Google Cloud 以供使用。
在本演示中，您将在 GKE 上部署一个插桩 Java 应用，该应用会向 Google Cloud发出指标和跟踪记录。然后，您可以使用 Google Cloud的可观测性产品（例如 Metrics Explorer、Logs Explorer 和 Trace Explorer）查看这些遥测信号。如需了解如何查看和使用生成的遥测数据，请参阅查看遥测数据。
本演示使用以下收费服务来写入信号：
- Cloud Monitoring 的 Managed Service for Prometheus
- Cloud Logging
- Cloud Trace
- Google Kubernetes Engine
- Cloud Build
- Artifact Registry
如需根据您的预计使用量来估算费用，请使用价格计算器。
准备工作
本部分介绍了如何设置环境，以便部署和插桩应用，然后运行应用。
选择或创建 Google Cloud 项目
为此演示选择一个 Google Cloud 项目。如果您还没有 Google Cloud 项目，请进行创建：
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
安装命令行工具
本文档使用以下命令行工具：
gcloudkubectl
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
如需使用本文档中的服务，您必须在 Google Cloud 项目中启用以下 API：
- 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
获取权限
-
如需获得运行应用并让其写入日志、指标和跟踪记录数据所需的权限，请让管理员为您授予以下 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 资源或本地开发环境中运行示例，则只需具备这些权限即可。如需了解如何配置配额项目，请参阅设置配额项目。
- 项目的 Logs Writer (
-
如需获得查看日志、指标和跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：
- Logs Viewer (
roles/logging.viewer) - Monitoring Viewer (
roles/monitoring.viewer) - Cloud Trace User (
roles/cloudtrace.user)
- Logs Viewer (
设置集群
为示例应用和收集器设置 GKE 集群：
运行以下命令，登录 Google Cloud ：
gcloud auth login gcloud config set project PROJECT_ID如果您还没有 GKE 集群，请运行以下命令创建 Autopilot 集群：
gcloud container clusters create-auto --region us-east1 CLUSTER_NAME --project PROJECT_ID如需与集群交互，请运行以下命令连接本地
kubectl实用程序：gcloud container clusters get-credentials CLUSTER_NAME --region us-east1 --project PROJECT_ID
部署 Java 应用
本部分中的步骤会在您的集群上部署一个未插桩的示例 Java 应用，即 OpenTelemetry Spring Boot 插桩示例。本部分使用 Cloud Build 和 Artifact Registry 创建和存储应用映像。
如果您还没有 Artifact Registry 代码库，请运行以下命令创建一个代码库：
gcloud artifacts repositories create opentelemetry-autoinstrument-registry --repository-format=docker --location=us-east4 --description="GKE Autoinstrumentation sample app"运行以下命令，克隆示例应用：
git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git设置以下环境变量：
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export ARTIFACT_REGISTRY=opentelemetry-autoinstrument-registry export REGISTRY_LOCATION=us-east4运行以下命令，构建应用映像并将其推送到 Artifact Registry 代码库：
pushd opentelemetry-samples/java/instrumentation-quickstart && \ gcloud builds submit --config <(envsubst < cloudbuild-uninstrumented-app.yaml) . && \ popd为应用创建 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运行以下命令，为您的应用创建命名空间：
kubectl create namespace APPLICATION_NAMESPACE运行以下命令，将部署配置应用于您的集群：
kubectl apply -f deployment.yaml -n APPLICATION_NAMESPACE创建 Deployment 后，Pod 可能需要一段时间才能创建并开始运行。如需检查 Pod 的状态，请运行以下命令：
kubectl get po -n APPLICATION_NAMESPACE -w如需停止监控 Pod 状态，请输入 Ctrl-C 以停止该命令。
设置 OpenTelemetry 收集器实例
在本部分中，您将创建另一个部署，用于在 GKE 集群中运行 Google 构建的 OpenTelemetry 收集器实例。收集器配置为使用以下导出器导出数据：
- 使用 OTLP HTTP 导出器的指标
- 使用 OTLP HTTP 导出器导出跟踪记录
- 使用 Google Cloud Exporter 导出日志
您可以按照适用于 GKE 的代管式 OpenTelemetry（在代管式环境中使用 Google 构建的 OpenTelemetry 收集器），而不是按照本文档中的手动步骤部署 OpenTelemetry 收集器。
运行以下命令，为 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
运行以下命令，使用推荐的默认配置在 GKE 集群上部署 Google 构建的 OpenTelemetry 收集器实例：
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest//k8s/base?ref=otlpmetric | envsubst | kubectl apply -f -此配置会将收集器部署到
opentelemetry命名空间。创建 Deployment 后，Pod 可能需要一段时间才能创建并开始运行。如需检查 Pod 的状态，请运行以下命令：
kubectl get po -n opentelemetry -w如需停止监控 Pod 状态，请输入 Ctrl-C 以停止该命令。
配置 OpenTelemetry 零代码插桩
如需为部署在 GKE 上的应用配置 OpenTelemetry 零代码插桩，请在 GKE 集群上安装 OpenTelemetry Operator。OpenTelemetry Operator 提供对 Kubernetes 自定义资源定义 (CRD)（即插桩资源）的访问权限，该资源用于将自动插桩注入到集群中运行的 Kubernetes 资源中。
通过使用特殊注解，插桩资源会被“注入”或“应用”到特定工作负载。OpenTelemetry Operator 会观察集群内运行的资源上的这些注解，并在这些资源管理的应用中注入适当的插桩。
如果您尚未安装 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如果集群上尚未安装
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运行以下命令并使用 0.140.0 或更高版本来安装 OpenTelemetry Operator：
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.140.0/opentelemetry-operator.yaml通过创建名为
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为 Operator 创建命名空间。您可以使用与应用命名空间 APPLICATION_NAMESPACE 相同的值。
kubectl create namespace INSTRUMENTATION_NAMESPACE在集群中创建插桩自定义资源，并通过运行以下命令应用
instrumentation.yaml文件：kubectl apply -f instrumentation.yaml -n INSTRUMENTATION_NAMESPACE将自动插桩注解应用于之前部署的示例 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"}}}}}'修补部署（这会导致应用部署重启）后，您可以通过运行以下命令来检查应用中 Pod 的状态：
kubectl get po -n APPLICATION_NAMESPACE -w如需停止监控 Pod 状态，请输入 Ctrl-C 以停止该命令。
现在，在 GKE 集群中部署的 Java 应用已自动插桩。
从已部署的应用生成遥测数据
如需从自动插桩的应用生成遥测数据，您需要向应用发送请求以模拟用户活动。您可以通过在集群中部署流量模拟器来生成稳定的流量：
通过将以下内容复制到名为
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: golang:1.24 command: - go - run - github.com/rakyll/hey@latest - -c=2 - -q=1 - -z=1h - http://quickstart-app:8080/multi运行以下命令来部署流量模拟器：
kubectl apply -f quickstart-traffic.yaml -n APPLICATION_NAMESPACE创建 Deployment 后，Pod 可能需要一段时间才能创建并开始运行。如需检查 Pod 的状态，请运行以下命令：
kubectl get po -n APPLICATION_NAMESPACE -w如需停止监控 Pod 状态，请输入 Ctrl-C 以停止该命令。
查看遥测数据
流量模拟器开始向应用发送请求后，部署的 Java 应用会生成遥测数据。指标和跟踪记录可能需要几分钟时间才会开始显示在 Google Cloud中。
OpenTelemetry Operator 注入的插桩依赖于 OpenTelemetry Java 代理。OpenTelemetry Java 代理包含针对许多发出指标的常用 Java 库和框架的内置插桩。
注入的插桩还会自动捕获对示例应用公开的任何端点发出的任何调用的跟踪记录。流量模拟器会以固定速率不断向 Java 应用公开的
/multi端点发送请求。/multi端点会反过来向/single端点发送请求，以生成最终响应。这些互动最终会作为跟踪记录，可以使用 Trace 探索器进行查看。
查看指标
您可以在 Cloud Monitoring 的 Metrics Explorer 中查看自动插桩指标。本部分包含用 PromQL 编写的示例查询。
在 Google Cloud 控制台中，前往 leaderboard 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 框架，适用于 Java 的 OpenTelemetry 零代码插桩也支持该框架。
平均 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 Explorer 中过滤这些跟踪记录，方法是过滤“服务名称”并将服务名称设置为 quickstart-app。
在 Google Cloud 控制台中，前往 
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