使用 Lambda 的 Powertools 緩衝日誌並在發生錯誤時自動刷新

最新版本的 AWS Powertools for Lambda 讓使用自訂功能擴充 Logger 變得更輕鬆：

Logger 類別現在更具可擴充性
現在您可以覆寫 Logger 方法 createAndPopulateLogItem、printLog 和 processLogItem，這些方法以前是私有的。這允許您擴展記錄器並添加新功能，例如實現您自己的訊息緩衝區。
發布 v2.12.0

我正在使用這個新的擴充性來實現一個有用的功能：日誌緩衝和刷新。這個想法很簡單：在生產環境中，我們通常只記錄重要訊息，例如警告和錯誤，因為日誌空間可能會變得昂貴並且會產生噪音。但是，當發生錯誤時，我們希望獲得所有可能的資訊：分散在函數中的所有偵錯和資訊日誌都應該可用。但它們並不是因為我們將日誌等級設定得太低。

緩衝和沖洗

如果我們在內部收集所有這些偵錯和資訊日誌，如果發生錯誤等重要事件，我們將它們列印到控制台怎麼辦？我把日誌分為兩類：低階日誌和進階日誌。如果我們配置的日誌等級是 WARN，則 DEBUG 或 INFO 日誌將是低階日誌，而 ERROR 將是進階日誌。

現在，當我們列印低階日誌時，我們不會像現在這樣丟棄它，而是將日誌緩衝在內部列表中。一旦我們有了高級日誌，我們就會將所有緩衝的日誌刷新到控制台。

執行

為了新增此功能，我們建立一個新類，該類別從 Powertools 擴展 Logger 類別並重寫 processLogItem()。這是由不同的日誌方法（如 logger.debug()）呼叫的中心方法。如果日誌項目處於正確的級別，原始實作會將日誌項目列印到控制台。透過重寫此方法，我們可以根據日誌等級新增緩衝和刷新日誌的特殊邏輯。

import { LogItem, Logger as PowertoolsLogger } from '@aws-lambda-powertools/logger';
import type { LogItemExtraInput, LogItemMessage } from '@aws-lambda-powertools/logger/types';

export class Logger extends PowertoolsLogger {
  #buffer: Record<string, Array<[number, string]>> = {};

  get buffer(): Record<string, Array<[number, string]>> {
    return this.#buffer;
  }

  protected override processLogItem(logLevel: number, input: LogItemMessage, extraInput: LogItemExtraInput): void {
    const xRayTraceId = this['envVarsService'].getXrayTraceId() as string;

    // Flush buffer when log level is higher than the configured log level
    if (logLevel > this.level && xRayTraceId) {
      const buffer = this.#buffer[xRayTraceId] ?? [];

      // Print all log items in the buffer
      if (buffer.length) this.info(`Flushing buffer with ${buffer.length} log items`);

      for (const [bufferLogLevel, bufferLogItem] of buffer) {
        // Create a new LogItem from the stringified log item
        this.printLog(bufferLogLevel, new LogItem(JSON.parse(bufferLogItem)));
      }

      // Clear the buffer after flushing
      // This also removes entries from other X-Ray trace IDs
      this.#buffer = {};
    }

    // Buffer the log item when log level is lower than the configured log level
    if (logLevel < this.level && xRayTraceId) {
      const buffer = this.#buffer[xRayTraceId] ?? [];
      // Add the stringified log item to the buffer
      // Serializing the log item ensures it is not mutated after being added to the buffer
      buffer.push([logLevel, JSON.stringify(this.createAndPopulateLogItem(logLevel, input, extraInput))]);

      // Update the buffer with the new log item
      // This also removes other X-Ray trace IDs from the buffer
      this.#buffer = {
        [xRayTraceId]: buffer,
      };
    }

    // Call the parent method to ensure the log item is processed
    super.processLogItem(logLevel, input, extraInput);
  }
}

您可能會問為什麼我們在這裡使用 X 光追蹤 ID。在處理程序函數之外實例化 Logger 是很常見的。但是，由於 Lambda 執行環境可能會重複用於多次調用，因此緩衝區可能包含先前調用的日誌項目。這就是緩衝區被實現為物件而不是簡單數組的原因。我們使用 X-Ray Trace ID 作為標識符，僅緩衝來自相同呼叫的日誌項。
緩衝區被實作為一個物件而不是一個簡單的陣列。當緩衝區被刷新時，我們可以簡單地重置對象，從而從其他呼叫中清除項目。

本地測試

讓我們快速在本地驗證一下實作：

// set X-Ray Trace ID manually if running locally
process.env._X_AMZN_TRACE_ID = '1-abcdef12-3456abcdef123456abcdef12';

// log level = WARN
const logger = new Logger({ logLevel: 'WARN' });

logger.debug('debug'); // < log level
logger.info('info');   // < log level
logger.warn('warn');   // = log level
logger.error('error'); // > log level

這是我們得到的輸出：

import { LogItem, Logger as PowertoolsLogger } from '@aws-lambda-powertools/logger';
import type { LogItemExtraInput, LogItemMessage } from '@aws-lambda-powertools/logger/types';

export class Logger extends PowertoolsLogger {
  #buffer: Record<string, Array<[number, string]>> = {};

  get buffer(): Record<string, Array<[number, string]>> {
    return this.#buffer;
  }

  protected override processLogItem(logLevel: number, input: LogItemMessage, extraInput: LogItemExtraInput): void {
    const xRayTraceId = this['envVarsService'].getXrayTraceId() as string;

    // Flush buffer when log level is higher than the configured log level
    if (logLevel > this.level && xRayTraceId) {
      const buffer = this.#buffer[xRayTraceId] ?? [];

      // Print all log items in the buffer
      if (buffer.length) this.info(`Flushing buffer with ${buffer.length} log items`);

      for (const [bufferLogLevel, bufferLogItem] of buffer) {
        // Create a new LogItem from the stringified log item
        this.printLog(bufferLogLevel, new LogItem(JSON.parse(bufferLogItem)));
      }

      // Clear the buffer after flushing
      // This also removes entries from other X-Ray trace IDs
      this.#buffer = {};
    }

    // Buffer the log item when log level is lower than the configured log level
    if (logLevel < this.level && xRayTraceId) {
      const buffer = this.#buffer[xRayTraceId] ?? [];
      // Add the stringified log item to the buffer
      // Serializing the log item ensures it is not mutated after being added to the buffer
      buffer.push([logLevel, JSON.stringify(this.createAndPopulateLogItem(logLevel, input, extraInput))]);

      // Update the buffer with the new log item
      // This also removes other X-Ray trace IDs from the buffer
      this.#buffer = {
        [xRayTraceId]: buffer,
      };
    }

    // Call the parent method to ensure the log item is processed
    super.processLogItem(logLevel, input, extraInput);
  }
}

警告是第一個訊息，因為偵錯和資訊日誌已被緩衝。當錯誤被記錄時，我們在實際列印錯誤之前刷新了緩衝的日誌（並列印了資訊）。

徵求意見

我的幼稚實現有一些警告。最重要的是，緩衝區大小不受限制，這意味著如果緩衝區增長太大，可能會導致記憶體問題。有幾種方法可以緩解此問題，例如，將緩衝區實作為滑動窗口，僅保留最新日誌或限制總緩衝區大小。

此外，緩衝日誌僅在受控情況下刷新，例如在 logger.error() 上，但在未處理的錯誤上不會刷新。如果我們將緩衝區公開並使用像 Middy.js 這樣的中間件，則可以輕鬆實現此行為。 Middy 公開了一個 onError 事件，我們可以利用該事件來刷新緩衝區。

我在官方 AWS Powertools for Lambda 儲存庫的評論請求中更詳細地介紹了這一點。

如果您希望看到此功能成為 Powertools for Lambda 的一部分，請在那裡分享您的想法和回饋？

以上是使用 Lambda 的 Powertools 緩衝日誌並在發生錯誤時自動刷新的詳細內容。更多資訊請關注PHP中文網其他相關文章！