在 GKE 上使用 OpenTelemetry 零程式碼檢測功能,檢測 Java 工作負載

OpenTelemetry 無程式碼檢測功能可讓您自動收集在 Google Kubernetes Engine (GKE) 上執行的 Java 應用程式指標和追蹤記錄,無須修改應用程式程式碼。在本逐步操作說明中,您會將 Java 範例應用程式部署至 GKE、設定 OpenTelemetry 自動檢測,並在 Google Cloud Observability 查看產生的遙測資料。雖然這些步驟著重於 Java 工作負載,但您也可以將這個方法延伸至其他支援的語言。

為什麼要使用零程式碼插碼?

OpenTelemetry 中的零程式碼檢測 (也稱為自動檢測) 是一項強大工具,可讓應用程式開發人員在程式碼中新增可設定的觀測能力,不必編寫任何額外程式碼或修改現有程式碼。無程式碼檢測會自動將檢測新增至已部署的應用程式程式庫,並發出黃金信號,提供可靠的應用程式效能洞察資料。因此,無程式碼檢測是應用程式觀測能力之旅的絕佳起點。

Java 的免程式碼檢測功能會檢測該語言生態系統中廣泛使用的熱門程式庫,藉此發出指標和追蹤記錄 span。Java 的指標包括:

發出的指標組合取決於檢測的應用程式,以及應用程式使用的程式庫。如需 Java 無程式碼檢測代理程式可檢測的程式庫和架構完整清單,請參閱「支援的程式庫和架構」。

自動檢測功能可讓您執行下列操作:

  • 不必變更任何程式碼,即可監控黃金信號。
  • 將高 p99.9 延遲時間與個別使用者追蹤記錄建立關聯,涵蓋每個 RPC 呼叫。
  • 從各種熱門程式庫和架構,取得一致的指標、記錄和追蹤記錄遙測資料。

如要進一步瞭解零程式碼檢測,請參閱 OpenTelemetry 的零程式碼。

總覽

如要為 GKE 上執行的 Java 工作負載新增觀測能力,必須部署下列元件:

  • OpenTelemetry 零程式碼檢測功能,可從應用程式產生遙測資料。
  • OpenTelemetry Collector 會收集應用程式產生的遙測資料,並加入重要的中繼資料和背景資訊,然後轉送至 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

您可以使用 Pricing Calculator 根據預測用量估算費用。

事前準備

本節說明如何設定環境,以便部署及檢測應用程式,然後執行應用程式。

選取或建立 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:專案 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

除了 Telemetry API 以外,這些 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 角色:

    如果您在 Cloud Shell、 Google Cloud 資源或本機開發環境中執行範例,這些權限就已足夠。如要瞭解如何設定配額專案,請參閱「設定配額專案」。

  2. 如要取得查看記錄、指標和追蹤資料所需的權限,請要求管理員授予您專案的下列 IAM 角色:

設定叢集

為範例應用程式和收集器設定 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
    
  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. 執行下列指令,將 Deployment 設定套用至叢集:

    kubectl apply -f deployment.yaml -n APPLICATION_NAMESPACE
    
  8. 建立 Deployment 後,Pod 可能需要一段時間才會建立並開始運作。如要檢查 Pod 的狀態,請執行下列指令:

    kubectl get po -n APPLICATION_NAMESPACE -w
    

    如要停止監控 Pod 狀態,請輸入 Ctrl-C 停止指令。

設定 OpenTelemetry Collector 執行個體

在本節中,您將建立另一個 Deployment,在 GKE 叢集中執行 Google 建構的 OpenTelemetry Collector 執行個體。收集器已設為使用下列匯出工具匯出資料:

您可以按照「GKE 適用的代管 OpenTelemetry」一文中的步驟操作,在代管環境中使用 Google 建構的 OpenTelemetry Collector,而不必按照本文中的手動步驟部署 OpenTelemetry Collector。

  1. 執行下列指令,授權 Kubernetes 服務帳戶部署 OpenTelemetry Collector:

    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 Collector 執行個體,並執行下列指令,採用建議的預設設定:

    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),也就是檢測資源,用於將自動檢測插入叢集內執行的 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 的檔案,並加入以下內容,為 Instrumentation Custom Resource 建立設定檔:

    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 自訂資源,然後執行下列指令套用 instrumentation.yaml 檔案:

    kubectl apply -f instrumentation.yaml -n INSTRUMENTATION_NAMESPACE
    
  7. 將自動檢測註解套用至先前部署的 Java 應用程式範例。執行下列指令,使用註解修補原始 Deployment:

    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. 修補 Deployment 後,應用程式 Deployment 會重新啟動,您可以執行下列指令,查看應用程式中的 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. 建立 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 控制台的「Metrics Explorer」頁面:

前往「Metrics Explorer」

如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果。

您可以查看範例應用程式的部分指標,包括:

  • 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 使用率指標:

      圖表顯示 JVM CPU 使用率,由 OpenTelemetry 零程式碼檢測功能擷取。

  • 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 伺服器時間長度指標:

      圖表:顯示 OpenTelemetry 零程式碼檢測功能擷取的平均 HTTP 伺服器時間。

如要進一步瞭解如何使用 Metrics Explorer,請參閱「在使用 Metrics Explorer 時選取指標」。

查看追蹤記錄

您可以在 Cloud Trace 的 Trace Explorer 中,查看自動檢測的追蹤記錄。您可以在 Trace Explorer 中篩選這些追蹤記錄,方法是篩選「Service Name」(服務名稱),並將服務名稱設為 quickstart-app。

前往 Google Cloud 控制台的 「Trace Explorer」頁面:

前往「Trace explorer」(Trace 探索工具)

您也可以透過搜尋列找到這個頁面。

下列螢幕截圖顯示 OpenTelemetry quickstart-app 部署作業產生的追蹤記錄:

Trace Explorer 會顯示 OpenTelemetry 零程式碼檢測功能擷取的追蹤記錄。

如要進一步瞭解如何使用 Trace Explorer,請參閱「尋找及探索追蹤記錄」。

清除所用資源

如果您建立了新的 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