bitrix-logger

ロギング（PSR-3）

ベースライン：main 23.0+ · 検証済み：main 26.800.0

コードは Psr\Log\LoggerInterface に依存し、実装は .settings.php の loggers で選択します。AddMessage2Log() は互換性のためだけに使用します。

実装（Bitrix\Main\Diag\）

クラス	説明
FileLogger(string $fileName, ?int $maxSize = null)	デフォルトの最大サイズは 1 MB で、超過すると <file>.old に名前が変更されます。0 はローテーションなしです
SysLogger(string $prefix = '', int $flags = LOG_ODELAY, int $facility = LOG_USER)	システムの syslog
EventLogger(?string $module, ?string $auditType, ?callable $callback)	b_event_log（管理画面の イベントログ）— 低頻度のログにのみ使用してください
LogFormatter($showArguments = false, $argMaxChars = 30)	デフォルトです。プレースホルダー {date} {host} {level} {delimiter} {exception} {trace} とコンテキストキーを使用します
JsonLinesFormatter（main 25.300 以降。それ以前：LogFormatter）	$context のみを 1 行の JSON として書き込みます。メッセージテキストは出力されないため、コンテキストに含めてください

level と formatter の設定は Bitrix\Main\Diag\Logger のサブクラスにのみ適用され、Monolog には適用されません。

ロガーの取得

main 26.250 以降* — LoggerFactory + LoggerRegistry：

use Bitrix\Main\Diag\LoggerFactory;
use Bitrix\Main\Diag\LoggerRegistry;

$logger = (new LoggerFactory())->createById('vendor.module.sync'); // NullLogger unless the id is enabled
(new LoggerRegistry())->enable('vendor.module.sync');               // option loggers:logger_is_enabled_<id> = Y
$logger = (new LoggerFactory())->createById('vendor.module.sync', [], false); // skip the registry check

• 有効化された ID に loggers エントリーがない場合、デフォルトロガー（LOG_FILENAME 定数）または NullLogger が使用されます。
• この方法で作成されたカーネル ID は、有効化されるまでログを出力しません：main.Messenger.Receiver、main.Messenger.Requeue、main.config.feature、bizproc.imbot、…
• Logger::create($id, $params) — main 26.300 以降は非推奨で、26.250 より前に使用できる唯一の API です。$id が設定されていない場合は null を返します：$logger = Logger::create('id') ?? new NullLogger();

サービスへの注入（モジュールの .settings.php）：

\Vendor\Module\Public\Service\SyncService::class => [
    'className' => \Vendor\Module\Public\Service\SyncService::class,
    'constructorParams' => static fn () => [(new \Bitrix\Main\Diag\LoggerFactory())->createById('vendor.module.sync')],
],

loggers セクション

/local/.settings_extra.php に記述してください。クロージャは、カーネルがメインファイルを書き換えると保持されません（bitrix-settings）。

'services' => [
    'value' => [
        'vendor.formatter.json' => ['className' => \Bitrix\Main\Diag\JsonLinesFormatter::class],
    ],
],
'loggers' => [
    'value' => [
        'vendor.module.sync' => [
            'constructor' => static fn () => new \Bitrix\Main\Diag\FileLogger('/var/log/site/sync.log', 10 * 1024 * 1024),
            'level' => \Psr\Log\LogLevel::INFO,     // threshold
            'formatter' => 'vendor.formatter.json', // service id
        ],
        'main.HttpClient' => [
            'constructor' => static function (\Bitrix\Main\Web\Http\DebugInterface $debug, \Psr\Http\Message\RequestInterface $request) {
                $debug->setDebugLevel(\Bitrix\Main\Web\HttpDebug::ALL);
                return new \Bitrix\Main\Diag\FileLogger('/var/log/site/http.log');
            },
        ],
    ],
    'readonly' => true,
],

エントリーの形式：constructor クロージャ（ファクトリーの $params を受け取ります）、または className + constructorParams（配列、または配列を返すクロージャ）。

カーネルのロガー ID

ID	使用箇所	クロージャのパラメーター
main.Default	AddMessage2Log()、デフォルトロガー	$logFileName、$showArgs
main.HttpClient	HttpClient / PSR-18 ハンドラー	DebugInterface $debug、RequestInterface $request
main.GeoIpManager	GeoIP マネージャー	—
main.EventLog.SysLogger、main.EventLog.FileLogger	CEventLog バックエンド	—、$path, $maxSize

main.Mail または main.Engine の ID はありません。

書き込み

$this->logger->error('Sync of order {orderId} failed: {exception}', ['orderId' => $id, 'exception' => $e]);

• コンテキストの {key} がプレースホルダーとして使われます。exception はクラス、メッセージ、トレースを出力します。
• 例外なしでスタックトレースを記録する場合：'trace' => \Bitrix\Main\Diag\Helper::getBackTrace(6, DEBUG_BACKTRACE_IGNORE_ARGS)。
• Monolog（composer require monolog/monolog）：constructor クロージャから Monolog\Logger を返し、レベルやフォーマッターは Monolog で設定します。

チェックリスト

• サービスには LoggerInterface を渡します（デフォルトは NullLogger）。業務コード内で new FileLogger() を使用しません。
• ロガー ID にはモジュール ID をプレフィックスとして付けます。LoggerFactory を使用する箇所では LoggerRegistry で有効化します。
• ログファイルは DOCUMENT_ROOT の外部に置き、ローテーションサイズを設定します。
• メッセージやコンテキストにパスワード、トークン、個人データを含めません。
• JsonLinesFormatter の呼び出し元では、メッセージをコンテキストに含めます。