Bitrix follows the PSR-3 standard. In code, inject \\Psr\\Log\\LoggerInterface, and in .settings.php, configure the specific implementation. Direct calls to AddMessage2Log are legacy; in new code, write via DI logger.
All are in the \\Bitrix\\Main\\Diag\\ namespace:
| Class | \nPurpose | \n
|---|---|
Logger | \nAbstract base class; Logger::create('id', $params) creates a logger via factory | \n
FileLogger | \nInto a file, with auto-rotation when $maxLogSize is exceeded (default 1 MB) | \n
SysLogger | \nInto system syslog via openlog/syslog | \n
EventLogger | \nInto b_event_log table (Admin Panel → Event Log) | \n
LogFormatter | \nDefault formatter: interpolates {placeholder}, renders exceptions and stacks | \n
JsonLinesFormatter | \nFrom 25.300.0; one JSON line per entry, convenient for ELK/Loki | \n
Levels are constants of \\Psr\\Log\\LogLevel::* (emergency, alert, critical, error, warning, notice, info, debug).
<?php declare(strict_types=1);\n\nnamespace Vendor\\Module\\Application\\Service;\n\nuse Psr\\Log\\LoggerInterface;\nuse Psr\\Log\\NullLogger;\n\nfinal class PostService\n{\n public function __construct(\n private readonly LoggerInterface $logger = new NullLogger(),\n ) {}\n\n public function publish(int $postId): void\n {\n try\n {\n // ...\n $this->logger->info('Post {id} published', ['id' => $postId]);\n }\n catch (\\Throwable $e)\n {\n $this->logger->error('Publish failed for post {id}: {exception}', [\n 'id' => $postId,\n 'exception' => $e,\n ]);\n throw $e;\n }\n }\n}\nRegistration in /local/modules/vendor.module/.settings.php:
'services' => [\n 'value' => [\n \\Vendor\\Module\\Application\\Service\\PostService::class => [\n 'constructor' => static fn (): \\Vendor\\Module\\Application\\Service\\PostService =>\n new \\Vendor\\Module\\Application\\Service\\PostService(\n new \\Bitrix\\Main\\Diag\\FileLogger('/var/log/bitrix/post-service.log'),\n ),\n ],\n ],\n 'readonly' => true,\n],\nMessage is a template with {key}, values are taken from $context:
$logger->warning('User {userId} tried {action} on post {postId}', [\n 'userId' => $uid, 'action' => 'delete', 'postId' => $pid,\n]);\nSpecial keys understood by LogFormatter:
{date} — current time (interpolated automatically).{host} — HTTP_HOST (automatic).{delimiter} — entry separator (automatic).{exception} — \\Throwable object → formats class, message, stack trace.{trace} — manual stack trace: Diag\\Helper::getBackTrace(6, DEBUG_BACKTRACE_IGNORE_ARGS, 3).Enable arguments in stack trace:
\n$logger->setFormatter(new \\Bitrix\\Main\\Diag\\LogFormatter(showArguments: true, argMaxChars: 120));\n.settings.php — loggers sectionAllows overriding loggers for named kernel points (main.HttpClient, main.Default, main.GeoIpManager) and your own identifiers.
return [\n 'services' => [\n 'value' => [\n 'formatter.withArgs' => [\n 'className' => \\Bitrix\\Main\\Diag\\LogFormatter::class,\n 'constructorParams' => [true],\n ],\n ],\n 'readonly' => true,\n ],\n 'loggers' => [\n 'value' => [\n 'main.Default' => [\n 'constructor' => static fn () => new \\Bitrix\\Main\\Diag\\FileLogger(\n '/var/log/bitrix/app.log', 10 * 1024 * 1024,\n ),\n 'level' => \\Psr\\Log\\LogLevel::INFO,\n 'formatter' => 'formatter.withArgs',\n ],\n\n 'main.HttpClient' => [\n 'constructor' => static function (\n \\Bitrix\\Main\\Web\\Http\\DebugInterface $debug,\n \\Psr\\Http\\Message\\RequestInterface $request,\n ) {\n $debug->setDebugLevel(\\Bitrix\\Main\\Web\\HttpDebug::ALL);\n return new \\Bitrix\\Main\\Diag\\FileLogger(\n '/var/log/bitrix/http-' . spl_object_hash($request) . '.log',\n );\n },\n 'level' => \\Psr\\Log\\LogLevel::DEBUG,\n ],\n\n 'vendor.module.myLogger' => [\n 'constructor' => static fn () => new \\Bitrix\\Main\\Diag\\FileLogger(\n '/var/log/bitrix/vendor.module.log',\n ),\n 'level' => \\Psr\\Log\\LogLevel::DEBUG,\n ],\n ],\n 'readonly' => true,\n ],\n];\nconstructor closures must be in .settings.php / .settings_extra.php — the file is not edited by Admin Panel, closures are not serialized.
level — threshold level; logger ignores messages below this.
formatter — key from services section.
Retrieving logger in code:
\n$logger = \\Bitrix\\Main\\Diag\\Logger::create('vendor.module.myLogger');\n$logger = \\Bitrix\\Main\\Diag\\Logger::create('vendor.module.myLogger', [$this, $extraArg]);\n| ID | \nUsed In | \nFactory Parameters | \n
|---|---|---|
main.Default | \nAddMessage2Log, general default | \nLOG_FILENAME, $showArgs | \n
main.HttpClient | \nBitrix\\Main\\Web\\HttpClient (including legacy and PSR-18) | \nDebugInterface $debug, RequestInterface $request | \n
main.GeoIpManager | \nBitrix\\Main\\Service\\GeoIp\\Manager | \n— | \n
main.EventLog.SysLogger | \nCEventLog → syslog path | \n— | \n
main.EventLog.FileLogger | \nCEventLog → file path | \n$path, $maxSize | \n
There are no named loggers main.Mail or main.Engine. Prefer constructor closures for FileLogger (see examples above) over className/settings arrays.
Configuring these loggers redirects all kernel calls — convenient for auditing external calls (see example in bitrix-http-client).
For classes that should be supplied with a logger \"by identifier\":
\nfinal class Indexer implements \\Psr\\Log\\LoggerAwareInterface\n{\n use \\Psr\\Log\\LoggerAwareTrait;\n\n public function run(): void\n {\n $this->ensureLogger()->info('Indexing started');\n }\n\n private function ensureLogger(): \\Psr\\Log\\LoggerInterface\n {\n if ($this->logger === null)\n {\n $this->setLogger(\\Bitrix\\Main\\Diag\\Logger::create('vendor.module.indexer', [$this]));\n }\n return $this->logger;\n }\n}\ncomposer require monolog/monolog\nIntegration into .settings.php:
'loggers' => [\n 'value' => [\n 'vendor.module.external' => [\n 'constructor' => static function () {\n $log = new \\Monolog\\Logger('vendor.module');\n $log->pushHandler(new \\Monolog\\Handler\\StreamHandler('/var/log/bitrix/monolog.log'));\n return $log;\n },\n 'level' => \\Psr\\Log\\LogLevel::DEBUG,\n ],\n ],\n],\n.settings.php rather than hardcoded in services.level is set for each environment.HttpClient) are redirected to separate files for audit.JsonLinesFormatter is used for external collectors.DOCUMENT_ROOT or protected by .htaccess.Link exception_handling.log in .settings.php with named loggers for unified error tracking. See skill bitrix-settings.