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

本文档演示了如何使用 OpenTelemetry 零代码插桩自动插桩在 Google Kubernetes Engine (GKE) 上运行的 Java 应用。借助零代码插桩，您只需极少的人工操作，即可全面了解 Java 工作负载的可观测性。

本演示详细介绍了如何将示例 Java 应用部署到 GKE、使用 OpenTelemetry 自动检测应用，以及使用 Google Cloud Observability 可视化生成的遥测信号。

该演练介绍了如何自动检测在 GKE 上运行的 Java 工作负载，但您可以将这些说明扩展到其他受支持的语言。

为何使用零代码插桩？

OpenTelemetry 中的零代码插桩（也称为自动插桩）是一种强大的工具，可让应用开发者向其代码添加可配置的可观测性，而无需编写任何额外的代码或修改任何现有代码。零代码插桩通过自动向有效部署的应用库添加插桩来工作，通过发出黄金信号，提供有关应用性能的可靠分析洞见。因此，零代码插桩是应用可观测性历程的绝佳起点。

Java 中的零代码插桩通过对该语言生态系统中广泛使用的热门库进行插桩来发出指标和轨迹跨度。对于 Java，指标包括：

所发出的指标集取决于被检测的应用程序 以及该应用程序使用的库。如需查看可由 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 项目，请进行创建：

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

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

    Go to project selector

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

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

    Go to project selector

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

如需使用本文档中的服务，您必须在 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

设置集群

为示例应用和收集器设置 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-operations-java.git

  3. 设置以下环境变量： 

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

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

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

  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 收集器实例。收集器配置为使用以下导出器导出数据：

您可以按照适用于 GKE 的受管 OpenTelemetry 中的步骤，在受管环境中使用 Google 构建的 OpenTelemetry 收集器，而无需按照本文档中的手动步骤来部署 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.svc.id.goog/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.svc.id.goog/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.svc.id.goog/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 Operator。OpenTelemetry Operator 提供对 Kubernetes 自定义资源定义 (CRD)（即插桩资源）的访问权限，该 CRD 用于将自动插桩注入到集群内运行的 Kubernetes 资源中。

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

  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 Operator：

    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. 为 Operator 创建命名空间。您可以使用与应用命名空间 APPLICATION_NAMESPACE 相同的值。

    kubectl create namespace INSTRUMENTATION_NAMESPACE

  6. 在集群中创建 Instrumentation 自定义资源，并通过运行以下命令应用 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 Operator 注入的插桩依赖于 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 利用率指标：

      图表显示了由 OpenTelemetry 零代码插桩捕获的 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 服务器时长指标：

      图表显示了由 OpenTelemetry 零代码插桩捕获的平均 HTTP 服务器时长。

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

查看跟踪记录

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

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

转到 Trace 探索器

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

以下屏幕截图显示了由 OpenTelemetry quickstart-app 部署生成的轨迹：

跟踪记录探索器会显示由 OpenTelemetry 零代码插桩捕获的跟踪记录。

如需详细了解如何使用 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