v0.21

ログとエラー

はじめに

dframeworkはコンソールと永続ログファイルの両方に書き込むデュアルチャネルロギングシステムを提供します。エラーページのレンダリング、コンポーネントタイプ別のスタックトレースの分類、コンパイル済みビューエラーの元のテンプレート行へのマッピング、および一般的なミスに対する診断ヒントを提供するエラーハンドラーが含まれています。

ロガー

ログレベル

ロガーは6つのログレベルをサポートしそれぞれ独自のカラーコーディングと動作を持ちます。

レベル 色 用途
debug シアン 開発専用メッセージ(デバッグモードが有効でない限り抑制)
info 青 一般的な情報メッセージ
hot オレンジ ローカル開発時のホットリロードイベント
warn 黄 重大でない警告
error 赤 エラーおよび例外
table マゼンタ 構造化された表形式データの出力

最小ログレベルはデバッグモードが有効かどうかによって決定されます。app.debugがtrueの場合debugを含むすべてのレベルが出力されます。デバッグが無効な場合debugメッセージは抑制されます。

ログメッセージの書き込み

各ログレベルにはグローバルなLogファサードまたは名前付きインポート(import { Log } from 'dframework')を介してアクセス可能な対応メソッドがあります。すべてのメソッドは自動的にフォーマットされる可変長引数を受け付けます。

1import { Log } from 'dframework';
2
3Log.debug('cache miss for key:', cacheKey);
4Log.info('user registered:', user.email);
5Log.warn('rate limit approaching for ip:', clientIp);
6Log.error('payment failed:', error);

ロガーはさまざまな引数タイプをフォーマットします。文字列はそのまま出力され、Errorオブジェクトは完全なスタックトレースを表示し、PromiseはPromise { <pending> }として表示され、オブジェクトはlocal環境において深さ3およびカラーサポート付きで整形出力されます。

テーブル形式のログ

Log.table()メソッドはオブジェクトの配列を罫線文字を使用したフォーマット済みasciiテーブルとしてレンダリングします。

1app.logger.table([
2 { name: 'users', rows: 1250, size: '2.4 MB' },
3 { name: 'posts', rows: 8340, size: '15.1 MB' },
4 { name: 'sessions', rows: 89, size: '0.1 MB' }
5], 'database overview');
1database overview
2┌─────────┬──────┬─────────┐
3│ name │ rows │ size │
4├─────────┼──────┼─────────┤
5│ users │ 1250 │ 2.4 MB │
6│ posts │ 8340 │ 15.1 MB │
7│ sessions│ 89 │ 0.1 MB │
8└─────────┴──────┴─────────┘

ログ出力

コンソール出力

local環境ではすべてのログメッセージがansiカラーコード付きでコンソールに出力されます。エラーおよび警告メッセージは標準出力と区別するためにconsole.errorを使用します。

production環境では色は削除されwarnおよびerrorメッセージのみがconsole.errorに出力されます。その他のすべてのレベルではconsole.logが使用されます。

ファイル出力

すべてのログメッセージは永続ログファイルにも同時に書き込まれます。ログファイルは環境ごとに分割されプロジェクトルートのlogsディレクトリに保存されます。

1logs/
2├── dev/
3│ ├── dframework_2026-06-04.log
4│ └── dframework_2026-06-05.log
5└── prod/
6 ├── dframework_2026-06-04.log
7 └── dframework_2026-06-05.log

local環境はlogs/dev/に書き込み、本番環境はlogs/prod/に書き込みます。ファイル出力からはansiカラーコードが自動的に削除されます。

ログファイルのローテーションと保持

ファイルロギングはロックフリーなアトミックリングバッファを介して通信する専用のバックグラウンドワーカースレッドを使用します。ログのフォーマットとエンコードはメインイベントループをブロックすることなく実行されすべてのディスクioを分離しながら厳密な順序を維持します。

ログファイルは毎日午前0時にローテーションされます。各ファイルには日付(dframework_YYYY-MM-DD.log)が付与されます。日付が変わるとバックグラウンドワーカーは自動的に以前のファイル記述子を閉じ新しい日次ファイル記述子を開きます。

フレームワークは古いログファイルを自動的には削除しません。保持クリーンアップはスケジュールされたコマンドまたはcronジョブを介してアプリケーションレベルに意図的に委任されており各チームが独自の保持およびコンプライアンスポリシーを決定できます。

cliを使用するかタスクにスケジュールして古いログファイルをクリアまたはプルーニングできます:

1dstrn logs:clear
2dstrn logs:clear --env=prod
3dstrn logs:clear --before=2026-01-01
4dstrn logs:clear --after=2026-05-01 --archive
5dstrn logs:clear --preview

デバッグバーとの統合

デバッグモードが有効なlocal環境ではログメッセージとパフォーマンステレメトリがリクエストコンテキストによって自動的にキャプチャされデバッグバーのレスポンスに含まれます。各ログエントリはそのレベル、メッセージ(色を除去したもの)、およびタイムスタンプを記録します。

クエリプロファイリングとN+1検出

デバッグバーはリクエストライフサイクル中に実行されたすべてのデータベースクエリを追跡し実行レイテンシを測定して反復クエリをハイライトします。

同一の正規化された形状を持つクエリが単一のリクエストで3回以上実行された場合デバッグバーにはインジケーターバッジが表示されます。バッジをクリックすると以下を表示する診断モーダルが開きます:

設定

ロガーはアプリケーション設定から設定を読み取ります。

設定キー 効果
app.env ログファイルのディレクトリ(devまたはprod)とコンソールカラーモードを決定
app.debug trueの場合debugログレベルを有効化しデバッグエラーページをアクティブ化
1// config/app.js
2export default {
3 env: 'local',
4 debug: true
5};

エラーハンドラー

ErrorHandlerクラスはアプリケーション全体のエラーレンダリングとロギングを管理します。アプリ起動時にインスタンス化され即座のレンダリングのためにすべてのエラーページテンプレートをキャッシュします。

エラーページ

dframeworkには404および500用の組み込みエラーページテンプレートが含まれています(ローカル開発時のdebugも含む)。各ページはフレームワークのビューテンプレート構文を使用しスタイル設定されたエラースクリーンをユーザーに表示します。

エラーが発生するとエラーハンドラーはステータスコードに基づいて適切なテンプレートを選択します。特定のコードに対応するビューテンプレートが存在しない場合エラーハンドラーはプレーンテキストの${status} Errorレスポンスを送信します。

カスタムエラーページ

views/errorsディレクトリに同じ名前のファイルを配置することで任意の組み込みエラーページをオーバーライドできます。ユーザー定義のエラーページはフレームワークのデフォルトよりも優先されます。

1views/errors/
2├── 404.d
3├── 500.d
4└── 503.d

カスタムエラーページでは数値のステータスコードに置き換えられる{{ status }}プレースホルダーにアクセスできます。

デバッグエラーページ

app.debugがtrueでありエラーが404でない場合フレームワークは本番エラーページの代わりに詳細なデバッグエラーページをレンダリングします。デバッグページには以下が表示されます:

このページは開発専用に設計されており本番環境では決して表示されません。

エラーヒント

エラーハンドラーには一般的なエラーメッセージを認識して診断ヒントを提供するパターンマッチングシステムが含まれています。エラーがログに記録されるとハンドラーは既知のパターンのリストと照らし合わせてメッセージをチェックします。

エラーパターン ヒント
Unexpected reserved word メソッド定義の前にasyncキーワードが抜けていないか確認してください
Cannot read properties of undefined プロパティにアクセスする前にオブジェクトが存在することを確認してください
is not a function メソッドが存在し適切にインポートされているか確認してください
Cannot find module インポートパスを確認しファイルが存在することを確認してください
await is only valid in async 関数宣言にasyncキーワードを追加してください
EADDRINUSE ポートが既に使用されています。他のプロセスを停止するか別のポートを使用してください
ER_NO_SUCH_TABLE データベーステーブルを作成するためにマイグレーションを実行してください
ER_BAD_FIELD_ERROR テーブルにカラムが存在しません。スキーマまたはマイグレーションを確認してください
ER_DUP_ENTRY ユニーク制約の重複値です。データまたはスキーマを確認してください

ヒントはコンソール出力のエラーメッセージの下にシアンで表示されます。

1[Socket] Template rendering failed: Cannot read properties of undefined (reading 'name')
2tip: verify object exists before accessing properties
3 ▸ [controller] UserController controllers/UserController.js:42
4 ▸ [view] home views/home.d:15

スタックトレースの分類

エラーハンドラーは生のスタックトレースを分類され色分けされたフレームに変換しトレースの最も関連性の高い部分を強調表示します。

フレームカテゴリ

各スタックフレームはファイルパスに基づいてカテゴリに分類されます。

カテゴリ 色 一致するパス
controller 黄 /controllers/
middleware 青 /middlewares/
model 緑 /models/
view マゼンタ view:///
route アクセント /routes/
job シアン /jobs/
command シアン /console/
config オレンジ /config/
migration 白 /migrations/
seeder 白 /seeders/
app 白 プロジェクトルート内のその他すべて

node_modulesおよびフレームワークのコアディレクトリからのフレームは自動的に除外されます。トレースにはアプリケーションコードのみが表示されます。

1 ▸ [controller] register controllers/AuthController.js:28
2 ▸ [model] create models/User.js:15
3 ▸ [view] auth.register views/auth/register.d:42

ビュー行マッピング

エラーがコンパイル済みビューテンプレートに起因する場合エラーハンドラーはコンパイルされたjavascriptの行番号を.dテンプレートファイル内の元の行にマッピングします。これはビューコンパイル中に生成された行マップを使用して行われスタックトレースが生成されたコードではなくエラーを引き起こしたテンプレート内の正確な行を指すようにします。

ホットリロードパスの解決

local環境ではフレームワークはホットリロードのためにキャッシュ無効化パス(.hot-*)を使用します。エラーハンドラーはこれらをスタックトレース内の元のファイルパスに解決するため常にクリーンで認識しやすいパスが表示されます。