로깅

로깅 (Logging)

LLM 애플리케이션을 만들 때든 운영할 때든, 로깅은 모니터링과 디버깅에 아주 중요한 역할을 해요. Haystack은 용도에 따라 바로 쓸 수 있는 여러 로깅 방법을 기본으로 제공합니다.

출처: 공식문서

표준 라이브러리 로깅 (기본값)

Haystack은 Python의 표준 라이브러리를 통해 로그를 남겨요. 덕분에 로그 형식을 내 필요에 맞게 자유롭게 바꿀 수 있는 유연함을 갖습니다.

로그 레벨 바꾸기

기본적으로 Haystack의 로깅 레벨은 WARNING으로 설정되어 있어요. 더 자세한 정보를 보고 싶다면 INFO로 바꾸면 되는데, 그러면 경고뿐 아니라 정보성 메시지까지 콘솔에 표시됩니다.

로깅 레벨을 INFO로 바꾸려면 이렇게 실행하세요:

import logging

logging.basicConfig(
    format="%(levelname)s - %(name)s - %(message)s",
    level=logging.WARNING,
)
logging.getLogger("haystack").setLevel(logging.INFO)

더 고급 설정이 필요하다면 Python의 로깅 문서를 참고하세요.

실시간 파이프라인 로깅

Haystack의 LoggingTracer를 쓰면 파이프라인을 흐르는 데이터를 실시간으로 들여다볼 수 있어요. 실험하거나 프로토타입을 만들 때 특히 유용한데, 사전에 어떤 트레이싱 백엔드도 설정해 둘 필요가 없기 때문입니다.

트레이서를 켜는 방법은 이렇습니다. 아래 예제에서는 컴포넌트 이름과 입력을 눈에 띄게 강조하려고 색상 태그를 추가했는데, 이 색상 부분은 선택 사항이에요.

import logging
from haystack import tracing
from haystack.tracing.logging_tracer import LoggingTracer

logging.basicConfig(
    format="%(levelname)s - %(name)s - %(message)s",
    level=logging.WARNING,
)
logging.getLogger("haystack").setLevel(logging.DEBUG)
tracing.tracer.is_content_tracing_enabled = True # to enable tracing/logging content (inputs/outputs)
tracing.enable_tracing(
    LoggingTracer(
        tags_color_strings={
            "haystack.component.input": "\x1b[1;31m",
            "haystack.component.name": "\x1b[1;34m",
        },
    ),
)

파이프라인을 실행하면 위 설정에 따라 로그가 색상까지 입혀진 모습으로 출력돼요.

구조화 로깅 (Structured Logging)

Haystack은 structlog 라이브러리를 활용해 구조화된 키-값 로그를 제공합니다. 로그 메시지마다 추가 메타데이터가 붙기 때문에, ELK, Grafana, Datadog 같은 도구로 로그를 아카이브할 때 특히 유용해요.

시스템에 structlog 설치가 감지되면, Haystack은 import 시점에 structlog 기반 포맷팅 핸들러를 설치해요. 다만 Haystack 자신의 로거 네임스페이스(haystack, haystack_integrations, haystack_experimental)에만 적용됩니다. 루트 로거와 프로세스 전역의 structlog 설정은 건드리지 않기 때문에, Haystack을 import해도 내 애플리케이션이나 다른 라이브러리가 로그하는 방식을 바꾸지 않아요.

스코프와 중복 로그 라인

  • configure_logging(logger_name="")은 포맷팅 핸들러를 루트 로거에 연결해서, 프로세스의 모든 로그 레코드를 포맷하던 과거 동작을 되살립니다.
  • configure_logging(propagate=False)는 Haystack의 로그 레코드가 상위 로거로 전파(propagate)되는 것을 막습니다.
from haystack.logging import configure_logging

# 프로세스의 모든 로그 레코드를 포맷 (과거 동작)
configure_logging(logger_name="")

# 호스트 앱이 루트 로거를 설정할 때 중복 로그 라인을 피하려면
configure_logging(propagate=False)

콘솔 렌더링

개발 경험을 좋게 하기 위해, Haystack은 기본적으로 structlog의 ConsoleRender를 사용해 구조화 로그를 정렬되고 색상이 들어간 깔끔한 형태로 보여줍니다.

리치(Rich) 포맷팅을 원한다면 rich를 설치해서 로그를 더욱 예쁘게 꾸밀 수 있어요!

JSON 렌더링

  • 환경 변수 HAYSTACK_LOGGING_USE_JSON을 true로 설정해 Haystack을 실행하세요.
  • 또는 Python으로 Haystack에게 JSON 로그를 쓰라고 알려줄 수도 있어요:
import haystack.logging

haystack.logging.configure_logging(use_json=True)

구조화 로깅 끄기

structlog가 이미 설치되어 있어도 구조화 로깅을 쓰고 싶지 않다면, Haystack을 실행할 때 환경 변수 HAYSTACK_LOGGING_IGNORE_STRUCTLOG를 true로 설정하면 됩니다.

더 알아보기 (Learn more)