PHP 로깅 라이브러리 비교: Monolog와 다른 네 가지 선택지
Monolog, Log4php, KLogger, Analog, PHP 내장 로그를 비교합니다. PSR-3 호환 범위와 JSON 필드 차이를 실행 예제로 확인하세요.
PHP 서비스에서 로거를 바꾼 뒤 가장 먼저 드러나는 문제는 알림이 잠잠해지는 일일 수 있다. 애플리케이션은 여전히 $logger->error()를 호출하지만, 기존 쿼리가 문자열 ERROR를 찾는 필드에는 이제 숫자가 들어온다. PHP 로깅 라이브러리를 고를 때는 코드를 호출하는 인터페이스와 수집기가 읽을 출력 형식을 함께 봐야 한다.
다섯 가지 선택지를 출력 기준으로 비교하기
| 선택지 | 애플리케이션 인터페이스 | 출력 방식과 용도 |
|---|---|---|
| Monolog | PSR-3. 3.12.1은 psr/log 2.x 또는 3.x를 사용한다. |
핸들러가 출력 대상, 프로세서가 공통 필드, 포매터가 형식을 정한다. |
| Apache Log4php | 자체 Logger API. | 계층형 로거와 appender, 패턴·XML 레이아웃을 제공한다. Apache 미러는 보관 상태이며 Composer 패키지는 유지 보수가 중단됐다. |
| KLogger | 2022년에 나온 1.2.2는 psr/log 1.x에 의존한다. |
텍스트 파일에 쓴다. 레벨 임계값과 형식을 설정할 수 있고 기본 파일명에는 날짜가 들어간다. |
| Analog | 정적 API와 PSR-3 래퍼 Analog\Logger. 2023년 안정 버전 1.0.21은 psr/log 3.x에 의존한다. |
기본 핸들러나 사용자 정의 클로저가 출력 대상과 형식을 정한다. |
PHP error_log() / syslog() |
인자가 서로 다른 내장 함수. | PHP나 시스템 로그가 어디에 남는지 아는 환경에서 작은 스크립트와 런타임 진단에 쓸 수 있다. |
Composer 제약도 확인한다. Monolog 3과 psr/log 3.x를 쓰는 프로젝트에는 같은 의존성 그래프에 KLogger 1.2.2를 추가할 수 없다. Analog의 래퍼는 3.x와 함께 쓸 수 있지만 실제 출력은 핸들러에 달려 있다. 기존 Log4php를 옮길 때는 현재 appender, 레벨 임계값, 레이아웃부터 파악한다. Monolog 패키지 · KLogger 패키지 · Analog 패키지 · Apache Log4php 패키지
지금 로그가 지나가는 경로 확인하기
PSR-3의 Psr\Log\LoggerInterface는 여덟 가지 레벨과 context 배열을 제공한다. 예외를 로거에 넘길 때는 exception 키를 쓴다. 호출부는 같은 인터페이스를 쓸 수 있다. JSON 필드명, 출력 위치, 파일 순환과 보관 기간은 구현체와 배포 환경에 따라 달라진다. PHP-FIG PSR-3(영어)
Laravel에서는 config/logging.php의 채널을 먼저 본다. 기반은 Monolog이고 실제 핸들러와 형식은 채널 설정으로 결정된다. Symfony에는 간단한 PSR-3 로거가 내장되어 있고 MonologBundle을 설치해 Monolog를 쓸 수도 있다. 핸들러를 바꾸기 전에 어떤 로거가 실제로 동작하는지 확인한다. Laravel 로깅(영어) · Symfony 로깅(영어)
작은 CLI 스크립트에는 error_log($message)만으로 충분할 수 있다. 기본 타입 0은 PHP 오류 로그 설정을 따르며 반환값이 기록 성공을 뜻하지 않는다. 타입 3은 지정한 파일에 추가하며 줄바꿈을 자동으로 붙이지 않는다. syslog(LOG_ERR, $message)는 시스템 로거에 우선순위를 전달한다. 웹 서비스의 PHP 엔진 오류와 애플리케이션 로그는 SAPI나 프레임워크 설정에 따라 다른 곳에 기록될 수 있다. PHP error_log(영어) · PHP syslog(영어) · PHP 오류 설정(영어)
새 포매터로 이벤트 한 건 보내 보기
PHP 8.1 이상이 설치된 환경에서 빈 실습 디렉터리를 만들고 composer require monolog/monolog:3.12.1을 실행한다. 아래 코드를 checkout.php에 저장해 php checkout.php로 실행한다. 호출부는 PSR-3 인터페이스를 받으며 표준 출력 형식은 핸들러와 포매터에서 정한다.
<?php
require __DIR__ . '/vendor/autoload.php';
use Monolog\Formatter\JsonFormatter;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Psr\Log\LoggerInterface;
function reportCheckoutFailure(LoggerInterface $logger): void
{
$logger->error('Checkout failed', [
'event' => 'checkout_failed',
'request_id' => 'fixture-42',
'exception' => new RuntimeException('Synthetic failure'),
]);
}
$handler = new StreamHandler('php://stdout');
$handler->setFormatter(new JsonFormatter());
$logger = new Logger('checkout', [$handler]);
reportCheckoutFailure($logger);
고정 버전에서 JSON 한 줄이 출력됐다. 숫자 level은 400, 문자열 level_name은 ERROR였고 예외는 context.exception에 들어갔다. datetime에는 시간대 오프셋이 있는 시각이 기록됐다. 이전 필드명이나 중첩 구조를 쓰는 쿼리는 새 형식에 맞춰야 한다. Monolog JsonFormatter
전환 전에 실제 애플리케이션의 정상 로그와 예외 로그를 한 건씩 비교한다. DataKit이 파일이나 컨테이너 출력을 수집한다면 Pipeline 파싱 후 필드를 확인하고 두 샘플에 기존 오류 쿼리를 적용한다. 애플리케이션 요청 ID와 trace ID는 구분하고 토큰과 개인정보는 기록하지 않는다. DataKit 로그 수집
출력 대상이 느려졌을 때까지 고려하기
동기 네트워크 핸들러가 대상의 응답을 기다리는 동안 PHP-FPM 워커는 계속 사용 중이다. 로컬 출력을 수집기에서 전달하면 해당 네트워크 작업을 요청 처리에서 분리할 수 있다. 부하가 높으면 로컬 쓰기도 대기할 수 있다. 버퍼를 둔다면 언제 묶어서 보내고 비정상 종료 시 얼마나 유실될 수 있는지 확인한다. 파일명에 날짜를 붙이는 것만으로는 보관 기간을 관리할 수 없다.
