為什麼 LogTape 應該成為您的 JavaScript/TypeScript 首選日誌記錄庫

洪 民憙 (Hong Minhee) @hongminhee@hackers.pub

在多樣化且不斷發展的 JavaScript 生態系統中，日誌記錄仍然是開發、除錯和監控應用程式的關鍵組件。雖然存在許多日誌記錄庫，但 LogTape 憑藉其簡單性、靈活性和跨執行環境兼容性的獨特組合脫穎而出。讓我們探討為什麼 LogTape 值得您在下一個 JavaScript 或 TypeScript 專案中考慮—無論您是在構建應用程式還是庫。

零依賴：輕量級佔用

LogTape 最吸引人的特點之一是它完全沒有依賴項。在「依賴地獄」困擾許多 JavaScript 專案的時代，LogTape 提供了一個令人耳目一新的替代方案：

// 除了 LogTape 本身之外，不需要安裝其他套件
import { configure, getConsoleSink, getLogger } from "@logtape/logtape";

這種零依賴方法提供了幾個優勢：

減少打包大小
沒有傳遞依賴意味著更小的套件
增強穩定性
沒有上游依賴帶來的破壞性變更風險
簡化安全性
減少第三方程式碼的潛在漏洞
降低整合開銷
對於不想讓使用者承擔額外依賴的庫作者來說特別有價值

執行環境多樣性：一次編寫，隨處記錄

雖然許多流行的日誌記錄庫主要專注於 Node.js，但 LogTape 提供了跨多種 JavaScript 執行環境的無縫支援：

這種執行環境靈活性意味著無論您的部署環境如何，都可以使用一致的日誌記錄模式：

// 相同的 API 在所有 JavaScript 執行環境中無縫運作
import { getLogger } from "@logtape/logtape";

const logger = getLogger(["my-service", "user-management"]);

// 在 Node.js、Deno、Bun、瀏覽器或 edge 函數中都能運作
logger.info`User ${userId} logged in successfully`;

對於跨多個平台工作的團隊或在執行環境之間轉換的專案，這種一致性是無價的。不需要學習不同的日誌記錄庫或方法—LogTape 在任何地方都以相同的方式工作。

階層式分類：精細控制

LogTape 的階層式分類系統是 JavaScript 日誌記錄庫中罕見的突出特點。分類允許您以樹狀結構組織日誌：

// 父分類
const appLogger = getLogger(["my-app"]);

// 子分類繼承父分類的設定
const dbLogger = getLogger(["my-app", "database"]);

// 孫分類
const queryLogger = getLogger(["my-app", "database", "queries"]);

// 使用 getChild() 的替代方法
const userLogger = appLogger.getChild("users");
const authLogger = userLogger.getChild("auth");

這種階層式方法提供了強大的優勢：

目標過濾
為應用程式的不同部分配置不同的日誌級別
繼承
子記錄器繼承父記錄器的設定，減少配置開銷
組織清晰度
日誌自然遵循應用程式的模組結構

以下是如何為不同分類配置日誌級別的方法：

await configure({
  sinks: {
    console: getConsoleSink(),
    file: getFileSink("app.log"),
  },
  loggers: [
    // 所有應用程式日誌的基本配置
    { 
      category: ["my-app"], 
      lowestLevel: "info", 
      sinks: ["console", "file"] 
    },
    // 僅為資料庫組件提供更詳細的日誌記錄
    { 
      category: ["my-app", "database"], 
      lowestLevel: "debug", 
      sinks: ["file"] 
    }
  ]
});

使用此配置，所有「info」級別及以上的應用程式日誌都會同時輸出到控制台和檔案，而資料庫特定的日誌則包含更詳細的「debug」級別資訊，但僅在日誌檔案中。

結構化日誌：超越簡單文字

現代日誌記錄超越了簡單的文字字串。LogTape 採用結構化日誌，將日誌條目視為資料物件而非純文字：

logger.info("User logged in", {
  userId: 123456,
  username: "johndoe",
  loginTime: new Date(),
  ipAddress: "192.168.1.1"
});

LogTape 還支援訊息中的佔位符，將結構化資料與人類可讀文字連接起來：

logger.info("User {username} (ID: {userId}) logged in from {ipAddress}", {
  userId: 123456,
  username: "johndoe",
  ipAddress: "192.168.1.1"
});

結構化日誌提供了實質性的好處：

改善搜尋能力
搜尋特定欄位值而非解析文字
更好的分析
對結構化欄位進行資料分析
一致格式
強制標準化日誌格式
機器可讀
更容易被日誌管理系統處理

對於注重效能的應用程式，LogTape 提供結構化資料的延遲評估：

logger.debug("Performance metrics", () => ({
  memoryUsage: process.memoryUsage(),
  cpuUsage: process.cpuUsage(),
  timestamp: performance.now()
}));

該函數僅在啟用 debug 級別時才會被評估，避免對被抑制的日誌級別進行不必要的計算。

極簡的接收器和過濾器：最少的樣板代碼

LogTape 的擴展性方法非常直接。創建自定義接收器（輸出目的地）和過濾器只需最少的樣板代碼。

超簡單的接收器

LogTape 中的接收器只是一個接收日誌記錄的函數：

// 創建自定義接收器就像定義一個函數一樣簡單
const mySink = (record) => {
  const timestamp = new Date(record.timestamp).toISOString();
  const level = record.level.toUpperCase();
  const category = record.category.join('.');
  
  // 發送到您的自定義目的地
  myCustomLogService.send({
    time: timestamp,
    priority: level,
    component: category,
    message: record.message,
    ...record.properties
  });
};

// 在配置中使用您的自定義接收器
await configure({
  sinks: {
    console: getConsoleSink(),
    custom: mySink
  },
  loggers: [
    { category: ["my-app"], sinks: ["console", "custom"] }
  ]
});

與需要擴展類別、實現多個方法或遵循特定模式的其他庫相比，LogTape 的方法令人耳目一新地直接。

簡單的過濾器

同樣，LogTape 中的過濾器只是返回布林值的函數：

// 只傳遞高優先級或特定組件日誌的過濾器
const importantLogsFilter = (record) => {
  // 始終包含錯誤
  if (record.level === "error" || record.level === "fatal") {
    return true;
  }
  
  // 始終包含與支付相關的日誌
  if (record.category.includes("payments")) {
    return true;
  }
  
  // 過濾掉其他日誌
  return false;
};

await configure({
  // ...接收器配置
  filters: {
    important: importantLogsFilter
  },
  loggers: [
    { 
      category: ["my-app"], 
      sinks: ["alertSystem"], 
      filters: ["important"] 
    }
  ]
});

LogTape 還提供了基於級別過濾的便捷簡寫：

await configure({
  // ...接收器配置
  filters: {
    // 這創建了一個「warning」級別及以上的過濾器
    warningAndAbove: "warning"
  },
  loggers: [
    { 
      category: ["my-app"], 
      sinks: ["console"], 
      filters: ["warningAndAbove"] 
    }
  ]
});

非常適合庫作者

LogTape 特別適合想要整合日誌記錄而不給使用者增加負擔的庫作者。核心理念很簡單：

  1. 庫提供日誌輸出點
  2. 應用程式配置如何處理這些日誌

以下是庫如何實現 LogTape 的方式：

// my-awesome-lib/database.js
import { getLogger } from "@logtape/logtape";

export class Database {
  private logger = getLogger(["my-awesome-lib", "database"]);

  constructor(host, port, user) {
    this.host = host;
    this.port = port;
    this.user = user;
  }

  connect() {
    this.logger.info("Connecting to database", {
      host: this.host,
      port: this.port,
      user: this.user
    });
    
    // 連接邏輯...
    
    this.logger.debug("Connection established");
  }
  
  query(sql) {
    this.logger.debug("Executing query", { sql });
    // 查詢邏輯...
  }
}

關鍵點是庫從不調用 configure()。相反，它提供有用的日誌輸出點，具有適當的級別和上下文數據。

使用該庫的應用程式可以精確決定如何處理這些日誌：

// 應用程式代碼
import { configure, getConsoleSink } from "@logtape/logtape";
import { Database } from "my-awesome-lib";

// 配置如何處理日誌
await configure({
  sinks: {
    console: getConsoleSink(),
    file: getFileSink("app.log")
  },
  loggers: [
    // 處理所有庫日誌
    { 
      category: ["my-awesome-lib"], 
      lowestLevel: "info", 
      sinks: ["file"] 
    },
    // 在開發期間為資料庫組件提供更詳細的日誌
    { 
      category: ["my-awesome-lib", "database"], 
      lowestLevel: "debug", 
      sinks: ["console", "file"] 
    }
  ]
});

// 使用庫
const db = new Database("localhost", 5432, "user");
db.connect();

這種關注點分離提供了幾個好處：

  1. 庫使用者對日誌處理有完全控制權
  2. 庫可以提供豐富的日誌記錄，而不強加實現細節
  3. 不會與應用程式日誌配置衝突
  4. 庫可以在內部「嘈雜」，同時允許應用程式根據需要進行過濾

上下文豐富日誌記錄

LogTape 提供上下文機制，用於在多個日誌訊息中添加一致的屬性。這對於追蹤系統中的請求特別有價值：

顯式上下文 

const logger = getLogger(["my-app", "api"]);

// 創建帶有上下文的記錄器
const requestLogger = logger.with({
  requestId: "abc-123",
  userId: 42,
  endpoint: "/users"
});

// 來自此記錄器的所有日誌都包含上下文屬性
requestLogger.info("Processing request");
requestLogger.debug("Validating input");
requestLogger.info("Request completed", { durationMs: 120 });

隱式上下文（v0.7.0+）

對於希望上下文在函數調用之間應用而無需顯式傳遞的情況：

import { getLogger, withContext } from "@logtape/logtape";

function handleRequest(req, res) {
  withContext({ 
    requestId: req.id, 
    userId: req.user?.id 
  }, () => {
    // 此函數及其調用的任何函數中的所有日誌
    // 將自動包含上下文屬性
    processRequest(req, res);
  });
}

function processRequest(req, res) {
  // 無需傳遞上下文 - 它自動可用
  getLogger(["my-app", "processor"]).info("Processing data");
  
  // 調用也將繼承上下文的其他函數
  validateInput(req.body);
}

function validateInput(data) {
  // 此日誌也獲取 requestId 和 userId
  getLogger(["my-app", "validator"]).debug("Validating input", { data });
}

這種隱式上下文功能對於在多層代碼中追蹤請求非常寶貴，無需通過每個函數調用手動傳遞上下文。

何時 LogTape 可能不是您的最佳選擇

雖然 LogTape 為許多使用場景提供了令人信服的優勢，但它並非普遍是最佳選擇：

極端效能需求
如果您的應用程式每秒記錄數萬個條目，且原始效能是最優先考慮的因素，專注於優化日誌輸出的專業高效能庫（如 Pino）可能更適合。
廣泛的預建整合
如果您需要立即與眾多特定系統（Elasticsearch、Graylog 等）整合，而無需編寫任何自定義代碼，Winston 豐富的傳輸生態系統可能提供更快的起點。
具有特定日誌需求的遺留系統
如果您正在維護圍繞 Java 或其他環境特定日誌模式構建的系統，專門構建的庫（如 Log4js）可能提供更熟悉的 API。
僅限網頁瀏覽器且日誌需求最小的應用程式
對於極其簡單的僅限網頁瀏覽器的日誌需求，您只需要帶有級別的基本控制台輸出，更簡單的庫（如 loglevel）可能就足夠了。

結論

LogTape 在擁擠的 JavaScript 日誌記錄領域中脫穎而出，提供了一個獨特的功能組合，解決了實際開發挑戰：

  • 零依賴，提供輕量級、安全的基礎
  • 執行環境多樣性，支援 Node.js、Deno、Bun、瀏覽器和 edge 函數
  • 階層式分類，實現更好的日誌組織和過濾
  • 結構化日誌，改善分析和搜尋能力
  • 簡單的擴展機制，最少的樣板代碼
  • 對庫友好的設計，尊重關注點分離

無論您是構建應用程式還是庫，跨多個 JavaScript 執行環境工作，或者只是尋求一個乾淨、設計良好的日誌解決方案，LogTape 都值得認真考慮。其周到的設計在簡單性和強大功能之間取得平衡，避免了 JavaScript 日誌記錄庫的常見陷阱。

有關更多信息和詳細文檔，請訪問 LogTape 的官方網站。

6
1
0

1 comment

If you have a fediverse account, you can comment on this article from your own instance. Search https://hackers.pub/ap/articles/0196e16d-24a5-719f-bdfe-091a2162cbd2 on your instance and reply to it.

1
1
0