I couldn't find a logging library that worked for my library, so I made one

Fedifyでログを取り込むときに直面した課題

Fedify（ActivityPubサーバーフレームワーク）を作り始めたとき、驚くほどやっかいな問題に直面しました。
それは「どうすればロギングを追加できるのか」という点です。
ロギング自体が難しいわけではありません――JavaScriptには何十もの成熟したライブラリがあります。ただ、これらは主にアプリケーション向けで、ライブラリとしては目立たないように設計されていないことが問題です。

数か月前にこの件について書いたところ、反応は控えめでした。興味を示す声もあれば懐疑的な意見や「この記事はAI生成？」という議論までありました。正直言って、英語は第一言語ではないので、LLMで文章を磨いています。アイデアと技術内容は私のものです。

いくつかの読者からは理論だけでなく実際に使える例を求められました。

問題点

既存のロガーは「アプリケーションを作っている前提」で設計されています。Fedify は ActivityPub プロトコル を用いて分散型ソーシャルアプリを構築するためのライブラリです。
フェデレーションに慣れていれば、デバッグは非常に手間がかかります。たとえばアクティビティが届かなかった場合、次のような質問に答えたいでしょう。

これらの質問は HTTP ハンドリング、暗号署名、JSON‑LD 処理、キュー管理など複数サブシステムにまたがります。ロギングが適切でなければ、デバッグは推測ゲームになります。

しかしライブラリ作者として直面したジレンマは次のとおりです。

• 冗長なログを出力すると、コンソールが混乱しユーザーに迷惑になる
• 何も出力しないと、問題発生時に原因究明が困難になる

既存の選択肢を検討

Winston や Pino を使えば：

1. Fedify 内でロガーを設定する（ユーザーに自分の好みを押し付ける）
2. ユーザーにロガーインスタンスを渡してもらう（ボイラープレート増加）

また

debug

どれも私の求めていたものとは違いました。そこで LogTape を自作しました―ライブラリ作者向けにゼロから設計されたロギングライブラリです。Fedify が最初の実運用ユーザーになりました。

解決策：階層化カテゴリとデフォルトで出力しない

重要な発見はシンプルでした：「ライブラリはログを出力しても、開発者が明示的に有効にするまで何もしない」ということ。Fedify は LogTape の 階層化カテゴリ を使い、ユーザーが必要な情報だけを細かく制御できるようにしました。

["fedify"]

["fedify", "federation", "inbox"]

["fedify", "federation", "outbox"]

["fedify", "federation", "http"]

["fedify", "sig", "http"]

["fedify", "sig", "ld"]

["fedify", "sig", "key"]

["fedify", "runtime", "docloader"]

["fedify", "webfinger", "lookup"]

（その他約十項目が存在します）
各カテゴリは独立したサブシステムに対応しています。

これにより、ユーザーは次のようにロギングを設定できます：

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    // Fedify 全体のエラーだけ表示
    { category: "fedify", sinks: ["console"], lowestLevel: "error" },

    // inbox 処理に関しては debug レベルで出力
    { category: ["fedify", "federation", "inbox"],
      sinks: ["console"],
      lowestLevel: "debug"
    },
  ],
});

受信アクティビティに問題が発生したとき、該当サブシステムの詳細ログだけが出力されます。コードを書き換える必要はなく、設定だけで完結です。

非同期境界を跨ぐリクエストトレース

階層化カテゴリでフィルタリングできるようになったものの、非同期処理間でログを関連付ける課題が残っていました。フェデレーションでは1つのユーザー操作が数多くの非同期呼び出しに波及します：リモートアクターの取得 → 署名確認 → アクティビティ処理 → フォロワーへの配信…

LogTape の 暗黙的コンテキスト 機能を使えば、すべてのログエントリに

requestId

await configure({
  sinks: {
    file: getFileSink("fedify.jsonl", { formatter: jsonLinesFormatter })
  },
  loggers: [
    { category: "fedify", sinks: ["file"], lowestLevel: "info" },
  ],
  contextLocalStorage: new AsyncLocalStorage(), // 暗黙的コンテキストを有効化
});

この設定では、すべてのログエントリに

requestId

jq 'select(.properties.requestId == "abc-123")' fedify.jsonl

これで手動で関連付ける必要がありません。

requestId

実際にユーザーが見るもの

Fedify を使う人は次のような状況を体験します：

同じライブラリコードが Node.js・Deno・Bun・エッジ関数 のいずれでも動き、追加のポリフィルやシムは不要です。必要なのはユーザー自身の判断です。

学んだこと

requestId

activityId

actorId

ぜひ自分で試してみてください

ライブラリを作っていて「ロギングはどうやる？」と悩んでいるなら、Fedify の実装例を参考にしてください。Fedify のログドキュメントには詳細が記載されていますし、LogTape の設計思想も併せて紹介しています。

LogTape は Winston や Pino を置き換えるものではなく、「ライブラリはユーザーの手元で必要なときだけ動作するようにしたい」――という別のニーズを満たすツールです。
もしそのようなロギングが必要なら、従来のアプリ中心のロガーよりも LogTape が適しているかもしれません。