Ruby on Rails 서비스에서 Semantic Logger를 활용한 현대적인 관측 가능성 로깅 구현

Semantic Logger 기본 설정 및 사용Semantic Logger는 Rails 애플리케이션의 기본 로거를 대체하는 rails_semantic_logger Gem을 통해 쉽게 통합됩니다. 초기 설정 시 SemanticLogger.add_appender(io: $stdout, formatter: :json)을 사용하여 JSON 형식으로 표준 출력에 로그를 기록하는 것이 권장됩니다. 성능 향상을 위해 비동기 로깅이 기본으로 활성화되어 있으나, 크래시 로그 보장을 위해 SemanticLogger.sync!를 호출하여 동기 모드로 전환할 수 있습니다.

로그 레벨 및 관리Semantic Logger는 TRACE, DEBUG, INFO, WARN, ERROR, FATAL 등 다양한 로그 레벨을 지원합니다. SemanticLogger.default_level을 통해 전역 로그 레벨을 설정하거나, include SemanticLogger::Loggable을 사용하여 클래스별로 로그 레벨을 재정의할 수 있습니다. 특히 SemanticLogger.add_signal_handler를 활성화하면 SIGUSR2 시그널을 통해 런타임에 로그 레벨을 동적으로 변경할 수 있어, 재시작 없이 문제 해결을 위한 상세 진단이 가능합니다. 테스트 환경에서는 logger.silence(:error)와 같이 특정 코드 블록 내에서 로그 레벨을 일시적으로 높여 불필요한 메시지를 억제할 수 있습니다.

컨텍스트 로깅 및 예외 처리Semantic Logger는 payload와 tags를 통해 풍부한 컨텍스트를 로그에 주입합니다.

• Payloads: logger.info("메시지", user_id: "usr-1234")와 같이 개별 이벤트에 대한 메타데이터를 구조화된 형태로 전달합니다.
• Tags: SemanticLogger.tagged(invoice_id: invoice.id) do ... end 블록 내에서 생성되는 모든 로그에 공통 속성을 자동으로 추가하여, 여러 메서드 호출에 걸쳐 특정 워크플로우의 컨텍스트를 유지합니다.예외 발생 시, 예외 객체를 직접 전달하면 exception 필드에 클래스 이름, 메시지, 스택 트레이스가 구조화된 배열 형태로 기록됩니다. 컨텍스트 페이로드와 예외 객체를 함께 전달하여 실패 원인을 더 명확하게 파악할 수 있으며, 중첩된 예외(cause)도 자동으로 직렬화하여 전체 오류 체인을 추적할 수 있습니다.

고급 기능: Appender, 필터링, OpenTelemetry 통합Semantic Logger는 다양한 appender(출력 대상)와 formatter(형식) 조합을 지원합니다. 개발 환경에서는 color 포맷을, 프로덕션에서는 json 포맷을 사용하는 것이 일반적입니다. 로그 볼륨 제어 및 민감 데이터 스크러빙을 위해 filter를 정의할 수 있습니다. filter는 Proc 형태로 로그 객체를 받아 로깅 여부를 결정하거나 페이로드 내의 민감 정보를 [REDACTED] 처리할 수 있습니다.가장 중요한 기능 중 하나는 OpenTelemetry와의 연동입니다. rails_semantic_logger와 OpenTelemetry SDK를 함께 사용하여 trace_id, span_id, trace_sampled를 로그에 자동으로 주입함으로써 로그와 분산 추적 간의 상관관계를 구축합니다. 이는 문제 발생 시 특정 오류에서 관련 로그로 즉시 이동하여 근본 원인을 파악하는 데 필수적입니다. 또한, OpenTelemetry Logs Data Model에 맞춰 로그 출력 형식을 사용자 지정 formatter로 조정하여 표준화된 텔레메트리 스택을 구축할 수 있습니다.