Node.js 檢測範例

本文說明如何修改 Node.js JavaScript 應用程式，使用開放原始碼 OpenTelemetry 架構收集追蹤記錄和指標資料，以及如何將結構化 JSON 記錄寫入標準輸出。本文也提供可安裝及執行的 Node.js 應用程式範例相關資訊。這個應用程式使用 Fastify 網路架構，並設定為產生指標、追蹤和記錄。

如要進一步瞭解插樁，請參閱下列文件：

• 儀表化和可觀測性。
• 選擇插碼方式。

注意： 本文僅顯示工作應用程式的選定部分。 舉例來說，範例不會顯示匯入的套件清單。不過，您可以在 GitHub 上找到完整應用程式。如要查看完整範例，請按一下「更多」，然後選取「在 GitHub 上查看」。

手動和零程式碼檢測簡介

對於這個語言，OpenTelemetry 將零程式碼檢測定義為從程式庫和架構收集遙測資料的做法，且無須變更程式碼。不過，您必須安裝模組並設定環境變數。

本文不會說明零程式碼的插碼作業。如要瞭解該主題，請參閱「JavaScript 零程式碼檢測」。

如需一般資訊，請參閱「OpenTelemetry Instrumentation for Node」。

事前準備

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

Enable the APIs

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

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

1. 設定 OpenTelemetry
2. 設定應用程式，預先載入 OpenTelemetry 設定
3. 設定結構化記錄
4. 寫入結構化記錄檔

設定 OpenTelemetry

OpenTelemetry Node.js SDK 的預設設定會使用 OTLP 通訊協定匯出追蹤記錄。此外，這項設定也會將 OpenTelemetry 設為使用 W3C 追蹤內容格式傳播追蹤內容。這項設定可確保追蹤記錄中的範圍具有正確的父項與子項關係。

以下程式碼範例說明如何使用 JavaScript 模組設定 OpenTelemetry。

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

diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.getEnv().OTEL_LOG_LEVEL
);

const sdk = new opentelemetry.NodeSDK({
  instrumentations: getNodeAutoInstrumentations({
    // Disable noisy instrumentations
    '@opentelemetry/instrumentation-fs': {enabled: false},
  }),
  resourceDetectors: getResourceDetectorsFromEnv(),
  metricReader: getMetricReader(),
});

try {
  sdk.start();
  diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
  diag.error(
    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
    error
  );
}

// Gracefully shut down the SDK to flush telemetry when the program exits
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => diag.debug('OpenTelemetry SDK terminated'))
    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});

先前的程式碼範例會設定 OpenTelemetry，使用 OTLP 通訊協定匯出指標，並使用 @opentelemetry/auto-instrumentations-node 套件設定所有可用的 Node.js 檢測。

為確保所有待處理的遙測資料都已排清，且連線在應用程式關閉前已正常關閉，SIGTERM 處理常式會呼叫 shutdown。

如要瞭解詳情和設定選項，請參閱「零程式碼插碼設定」。

設定應用程式，預先載入 OpenTelemetry 設定

如要設定應用程式寫入結構化記錄，並使用 OpenTelemetry 收集指標和追蹤資料，請更新應用程式的叫用，以使用 Node.js --require 旗標預先載入檢測模組。使用 --require 標記可確保 OpenTelemetry 在應用程式啟動前完成初始化。詳情請參閱 OpenTelemetry Node.js 入門。

以下程式碼範例說明 Dockerfile 如何傳遞 --require 標記：

CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log

設定結構化記錄

如要將追蹤資訊納入以 JSON 格式寫入標準輸出的記錄中，請將應用程式設定為以 JSON 格式輸出結構化記錄。Fastify 使用 Pino 記錄架構，並在每個要求處理常式中提供記錄器。下列程式碼範例說明 Pino LoggerOptions 物件，該物件會將應用程式設定為輸出 JSON 結構化記錄：

// Expected attributes that OpenTelemetry adds to correlate logs with spans
interface LogRecord {
  trace_id?: string;
  span_id?: string;
  trace_flags?: string;
  [key: string]: unknown;
}

// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
const PinoLevelToSeverityLookup: Record<string, string | undefined> = {
  trace: 'DEBUG',
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARNING',
  error: 'ERROR',
  fatal: 'CRITICAL',
};

export const loggerConfig = {
  messageKey: 'message',
  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
  timestamp(): string {
    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
  },
  formatters: {
    log(object: LogRecord): Record<string, unknown> {
      // Add trace context attributes following Cloud Logging structured log format described
      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
      const {trace_id, span_id, trace_flags, ...rest} = object;

      return {
        'logging.googleapis.com/trace': trace_id,
        'logging.googleapis.com/spanId': span_id,
        'logging.googleapis.com/trace_sampled': trace_flags
          ? trace_flags === '01'
          : undefined,
        ...rest,
      };
    },
    // See
    // https://getpino.io/#/docs/help?id=mapping-pino-log-levels-to-google-cloud-logging-stackdriver-severity-levels
    level(label: string) {
      return {
        severity:
          PinoLevelToSeverityLookup[label] ?? PinoLevelToSeverityLookup['info'],
      };
    },
  },
} satisfies LoggerOptions;

先前的設定會從記錄訊息中擷取有效跨度相關資訊，然後將該資訊做為屬性新增至 JSON 結構化記錄。這些屬性可用於將記錄與追蹤記錄建立關聯：

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

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

如要搭配 Fastify 使用 Pino 設定，請在建立 Fastify 應用程式時傳遞記錄器設定物件：

// Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});

寫入結構化記錄檔

如要寫入連結至追蹤記錄的結構化記錄，請使用 Fastify 提供的 Pino 記錄器。舉例來說，下列陳述式說明如何呼叫 Logger.info() 方法：

request.log.info({subRequests}, 'handle /multi request');

OpenTelemetry 會在 OpenTelemetry Context 中，使用目前有效範圍的範圍內容，自動填入 Pino 記錄項目。然後，這個範圍內容會納入 JSON 記錄，如「設定結構化記錄」一文所述。

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

範例應用程式使用與供應商無關的格式，包括記錄的 JSON，以及指標和追蹤記錄的 OTLP，以及 Fastify 架構。如要將遙測資料傳送至 Google Cloud，這個範例會使用已設定 Google 匯出工具的 OpenTelemetry Collector。這個應用程式有兩個端點：

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

  /**
   * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
   *
   * OpenTelemetry instrumentation requires no changes here. It will automatically generate a
   * span for the handler body.
   */
  fastify.get('/multi', async request => {
    const subRequests = randInt(3, 8);
    request.log.info({subRequests}, 'handle /multi request');
  
    for (let i = 0; i < subRequests; i++) {
      await axios.get(`http://localhost:${port}/single`);
    }
    return 'ok';
  });

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

  /**
   * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
   * milliseconds slept as its response.
   */
  fastify.get('/single', async request => {
    // Sleep between 100-200 milliseconds
    const sleepMillis = randInt(100, 200);
    request.log.info({sleepMillis}, 'Going to sleep');
    await sleep(sleepMillis);
    return `slept ${sleepMillis}\n`;
  });

下載及部署應用程式

注意： 建議使用 Cloud Shell 執行範例應用程式。不過，如要在 Linux 或 Mac 上在本機執行範例應用程式，請略過下列操作說明的第一個步驟。

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

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

2. 複製存放區：

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

3. 前往範例目錄：

   cd opentelemetry-operations-js/samples/instrumentation-quickstart
   

4. 建構並執行範例：

   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 記錄用戶端要求的時間長度，並將結果儲存在直方圖中。

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

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

   前往 Metrics Explorer

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

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。 如要進行 App Hub 設定，請選取 App Hub 主專案或已啟用應用程式的資料夾的管理專案。
3. 在「指標」元素中，展開「選取指標」選單， 在篩選列中輸入 http_server， 然後使用子選單選取特定資源類型和指標：
   1. 在「Active resources」(有效資源) 選單中，選取「Prometheus Target」(Prometheus 目標)。
   2. 在「Active metric categories」(使用中的指標類別) 選單中，選取「Http」。
   3. 在「Active metrics」(使用中的指標) 選單中，選取指標。
   4. 按一下 [套用]。
4. 設定資料的顯示方式。
   

   如果指標的測量值是累計值，指標探索工具會自動以對齊週期將測量資料正規化，因此圖表會顯示比率。詳情請參閱「種類、型別和轉換」。

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

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

查看追蹤記錄

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

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

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

   前往「Trace Explorer」頁面

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

2. 在頁面的表格部分，選取跨度名稱為 /multi 的資料列。

3. 在「Trace details」(追蹤記錄詳細資料) 面板的甘特圖中，選取標示為 /multi 的時距。

   畫面上會開啟一個面板，顯示 HTTP 要求相關資訊。這些詳細資料包括方法、狀態碼、位元組數，以及呼叫者的使用者代理程式。

4. 如要查看與這項追蹤記錄相關聯的記錄檔，請選取「記錄檔和事件」分頁標籤。

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

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

查看記錄檔

您可以在記錄檔探索器中檢查記錄，也可以查看相關聯的追蹤記錄 (如有)。

1. 前往 Google Cloud 控制台的「Logs Explorer」頁面：

   前往「Logs Explorer」(記錄檔探索工具)

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

2. 找出說明為 handle /multi request 的記錄。

   如要查看記錄詳細資料，請展開記錄項目。

3. 在含有「handle /multi request」訊息的記錄項目上，按一下 「追蹤記錄」，然後選取「查看追蹤記錄詳細資料」。

   「Trace details」(追蹤記錄詳細資料) 面板隨即開啟，並顯示所選追蹤記錄。

   記錄資料可能比追蹤資料早幾分鐘提供。如果透過 ID 搜尋追蹤記錄或按照這項工作中的步驟查看追蹤記錄資料時發生錯誤，請稍候一到兩分鐘，然後重試。

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

後續步驟

• OpenTelemetry
• OTLP 規格
• 結構化記錄
• 排解 Managed Service for Prometheus 的問題
• 排解 Cloud Trace 問題