本頁面由 Cloud Translation API 翻譯而成。

Java 檢測範例
透過集合功能整理內容你可以依據偏好儲存及分類內容。

本文說明如何修改 Java 應用程式，以便使用開放原始碼 OpenTelemetry 架構收集追蹤記錄和指標資料，以及如何將結構化 JSON 記錄寫入標準輸出。本文件也提供可安裝及執行的 Java Spring Boot 應用程式範例相關資訊。應用程式已設定為產生指標、追蹤記錄和記錄。無論您是否使用 Spring Boot Framework，步驟都相同。

如要進一步瞭解檢測功能，請參閱下列文件：

檢測和觀測能力。
選擇檢測方法。

關於手動和零程式碼檢測

本文所述的檢測功能會使用 OpenTelemetry 零程式檢測功能，將遙測資料傳送至 Google Cloud 專案。就 Java 而言，零程式碼檢測是指動態將位元碼插入程式庫和架構，以便擷取遙測資料的做法。零程式檢測功能可收集傳入和傳出 HTTP 呼叫等遙測資料。詳情請參閱「Java 代理程式」。

OpenTelemetry 也提供 API，可在您自己的程式碼中新增自訂檢測功能。OpenTelemetry 稱之為「手動檢測」。本文件不會說明手動檢測。如需相關範例和資訊，請參閱「手動檢測」。

事前準備

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

檢測應用程式以收集追蹤記錄、指標和記錄

如要檢測應用程式以收集追蹤記錄和指標資料，並將結構化 JSON 寫入標準輸出，請按照本文件後續章節所述的步驟操作：

設定應用程式以使用 OpenTelemetry Java Agent
設定 OpenTelemetry
設定結構化記錄
寫入結構化記錄檔

將應用程式設定為使用 OpenTelemetry Java Agent

如要設定應用程式以使用 OpenTelemetry 寫入結構化記錄檔，並收集指標和追蹤記錄資料，請更新應用程式的叫用作業，以便使用 OpenTelemetry Java 代理程式。這種檢測應用程式的方法稱為「自動檢測」，因為您不必修改應用程式程式碼。

下列程式碼範例說明 Dockerfile，該檔案會下載 OpenTelemetry Java Agent JAR 檔案，並更新指令列叫用作業，以便傳遞 -javaagent 標記。

如要查看完整範例，請按一下「更多」，然後選取「前往 GitHub 查看」。

RUN wget -O /opentelemetry-javaagent.jar https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.31.0/opentelemetry-javaagent.jar
CMD sh -c "java -javaagent:/opentelemetry-javaagent.jar -cp app:app/lib/* com.example.demo.DemoApplication \
	2>&1 | tee /var/log/app.log"

或者，您也可以在 JAVA_TOOL_OPTIONS 環境變數中設定 -javaagent 標記：

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"

設定 OpenTelemetry

OpenTelemetry Java 代理程式的預設設定會使用 OTLP 通訊協定匯出追蹤記錄和指標。它還會將 OpenTelemetry 設為使用 W3C 追蹤記錄內容格式，用於傳播追蹤記錄內容。這項設定可確保跨度在追蹤記錄中具有正確的父項與子項關係。

如需更多資訊和設定選項，請參閱「OpenTelemetry Java 自動檢測」。

設定結構化記錄

如要將追蹤資訊納入以 JSON 格式寫入標準輸出的記錄，請將應用程式設為以 JSON 格式輸出結構化記錄。建議您使用 Log4j2 實作記錄功能。下列程式碼範例說明 log4j2.xml 檔案已設定為使用 JSON 範本版面配置輸出 JSON 結構化記錄：

<!-- Format JSON logs for the Cloud Logging agent
https://cloud.google.com/logging/docs/structured-logging#special-payload-fields -->

<!-- Log4j2's JsonTemplateLayout includes a template for Cloud Logging's special JSON fields
https://logging.apache.org/log4j/2.x/manual/json-template-layout.html#event-templates -->
<JsonTemplateLayout eventTemplateUri="classpath:GcpLayout.json">
  <!-- Extend the included GcpLayout to include the trace and span IDs from Mapped
  Diagnostic Context (MDC) so that Cloud Logging can correlate Logs and Spans

  Since log4j2 2.24.0, GcpLayout.json already includes trace context logging from MDC and
  the below additional fields are no longer needed -->
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace"
    format="JSON"
    value='{"$resolver": "mdc", "key": "trace_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/spanId"
    format="JSON"
    value='{"$resolver": "mdc", "key": "span_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace_sampled"
    format="JSON"
    value="true"
  />
</JsonTemplateLayout>

先前的設定會從 SLF4J 的對應的診斷情境中擷取關於有效時間範圍的資訊，並將該資訊做為屬性新增至記錄檔。這些屬性可用於將記錄與追蹤連結：

logging.googleapis.com/trace：與記錄項目相關聯的追蹤記錄資源名稱。
logging.googleapis.com/spanId：與記錄項目相關聯的追蹤記錄中的時距 ID。
logging.googleapis.com/trace_sampled：這個欄位的值必須是 true 或 false。

如要進一步瞭解這些欄位，請參閱 LogEntry 結構。

寫入結構化記錄檔

如要撰寫連結至追蹤記錄的結構化記錄檔，請使用 SLF4J 記錄 API。例如，下列陳述式說明如何呼叫 Logger.info() 方法：

logger.info("handle /multi request with subRequests={}", subRequests);

OpenTelemetry Java 代理程式會自動在 OpenTelemetry 背景資訊中，將目前有效時距的時距背景資訊填入 SLF4J 的對應診斷背景資訊。接著，系統會將對應的診斷內容納入 JSON 記錄中，如「設定結構化記錄」一文所述。

執行已設定為收集遙測資料的範例應用程式

範例應用程式使用供應商中立格式，包括用於記錄的 JSON，以及用於指標和追蹤的 OTLP，以及 Spring Boot Framework。為了將遙測資料路由至 Google Cloud，這個範例會使用已設定 Google 匯出工具的 OpenTelemetry Collector。這個應用程式有兩個端點：

/multi 端點由 handleMulti 函式處理。應用程式中的負載產生器會向 /multi 端點提出要求。當這個端點收到要求時，會向本機伺服器上的 /single 端點傳送三到七個要求。

/**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/multi")
public Mono<String> handleMulti() throws Exception {
  int subRequests = ThreadLocalRandom.current().nextInt(3, 8);

  // Write a structured log with the request context, which allows the log to
  // be linked with the trace for this request.
  logger.info("handle /multi request with subRequests={}", subRequests);

  // Make 3-7 http requests to the /single endpoint.
  return Flux.range(0, subRequests)
      .concatMap(
          i -> client.get().uri("http://localhost:8080/single").retrieve().bodyToMono(Void.class))
      .then(Mono.just("ok"));
}

/single 端點由 handleSingle 函式處理。這個端點收到要求時，會先短暫休眠，然後以字串回應。

/**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/single")
public String handleSingle() throws InterruptedException {
  int sleepMillis = ThreadLocalRandom.current().nextInt(100, 200);
  logger.info("Going to sleep for {}", sleepMillis);
  Thread.sleep(sleepMillis);
  logger.info("Finishing the request");
  return String.format("slept %s\n", sleepMillis);
}

下載及部署應用程式

如要執行範例，請按照下列步驟操作：

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

複製存放區：

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java

前往範例目錄：

cd opentelemetry-operations-java/examples/instrumentation-quickstart

建構並執行範例：

docker compose up --abort-on-container-exit

如果您不是在 Cloud Shell 上執行，請將 GOOGLE_APPLICATION_CREDENTIALS 環境變數指向憑證檔案，然後執行應用程式。應用程式預設憑證會在 $HOME/.config/gcloud/application_default_credentials.json 提供憑證檔案。

# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

查看指標

範例應用程式中的 OpenTelemetry 檢測工具會產生 Prometheus 指標，您可以使用 Metrics Explorer 查看這些指標：

Prometheus/http_server_duration_milliseconds/histogram 會記錄伺服器要求的時間長度，並將結果儲存在直方圖中。
Prometheus/http_client_duration_milliseconds/histogram 會記錄用戶端要求的時間長度，並將結果儲存在直方圖中。

如要查看範例應用程式產生的指標，請按照下列步驟操作：

前往 Google Cloud 控制台的「Metrics Explorer」頁面：
前往 Metrics Explorer

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要設定 App Hub，請選取 App Hub 主機專案或已啟用應用程式的資料夾管理專案。
在「指標」元素中，展開「選取指標」選單，在篩選列中輸入 http_server，然後使用子選單選取特定資源類型和指標：
1. 在「Active resources」選單中，選取「Prometheus Target」。
2. 在「Active metric categories」(使用中的指標類別) 選單中，選取「Http」。
3. 在「Active metrics」選單中，選取指標。
4. 按一下 [套用]。
設定資料檢視方式。
當指標的測量值為累積值時，「Metrics Explorer」會自動根據對齊期間將測量資料標準化，因此圖表會顯示速率。詳情請參閱「類型、類型和轉換」。

當系統測量整數或雙精度值時 (例如兩個 counter 指標)，Metrics Explorer 會自動加總所有時間序列。如要查看 /multi 和 /single HTTP 路徑的資料，請將「Aggregation」項目的第一個選單設為「None」。

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

查看追蹤記錄

追蹤資料可能需要幾分鐘的時間才會顯示。舉例來說，當專案收到追蹤記錄資料時，Google Cloud Observability 可能需要建立資料庫來儲存該資料。建立資料庫可能需要幾分鐘的時間，在此期間，您無法查看追蹤記錄資料。

如要查看追蹤記錄資料，請按照下列步驟操作：

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

您也可以透過搜尋列找到這個頁面。
在頁面的表格部分，選取標頭名稱為 /multi 的資料列。
在「Trace details」面板的甘特圖中，選取標示為 /multi 的時距。

畫面上會開啟一個面板，顯示 HTTP 要求的相關資訊。這些詳細資料包括方法、狀態碼、位元組數量，以及呼叫端的使用者代理程式。
如要查看與此追蹤記錄相關聯的記錄，請選取「Logs & Events」分頁標籤。

這個分頁會顯示個別記錄。如要查看記錄項目的詳細資料，請展開記錄項目。您也可以按一下「View Logs」，然後使用 Logs Explorer 查看記錄檔。

如要進一步瞭解如何使用 Cloud Trace 探索工具，請參閱「尋找及探索追蹤記錄」一文。

查看記錄檔

您可以透過「記錄檔探索器」檢查記錄，並查看相關的追蹤記錄 (如有)。

前往 Google Cloud 控制台的「Logs Explorer」頁面：
前往「Logs Explorer」(記錄檔探索工具)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
找出說明為 handle /multi request 的記錄。

如要查看記錄的詳細資料，請展開記錄項目。
在含有「handle /multi request」訊息的記錄項目上，按一下「Traces」，然後選取「View trace details」。

「Trace details」面板會隨即開啟，並顯示所選的追蹤記錄。

記錄資料可能會比追蹤資料早幾分鐘出現。如果您在查看追蹤記錄資料時遇到錯誤，無論是透過搜尋 ID 或按照本任務中的步驟操作，請稍候一兩分鐘，然後再重試該動作。

如要進一步瞭解如何使用記錄檔探索工具，請參閱「使用記錄檔探索工具查看記錄檔」。