LibreChat로깅 시스템
이 문서는 LibreChat의 로깅 기능을 사용하는 방법을 설명하며, 오류 및 디버그 로그를 `/api/logs` 폴더에 저장합니다. 이 로그를 사용하여 문제를 해결하고, 서버를 모니터링하며, 버그를 보고할 수 있습니다. 또한 공간을 절약하려면 디버그 로그를 비활성화할 수도 있습니다.
일반
LibreChat은 백엔드(api)에 중앙 집중식 로깅 기능이 내장되어 있습니다.
- Docker 설치 시, 로그 파일은
/logs에 저장됩니다.
- npm 설치 시, 로그 파일은
/api/logs에 저장됩니다.
오류 로그는 기본적으로 저장됩니다. 디버그 로그는 기본적으로 활성화되어 있지만, 원하지 않는 경우 끌 수 있습니다.
이를 통해 **the ELK stack**과 같이 로그 파일을 검사하는 외부 도구를 사용하여 서버를 모니터링할 수 있습니다.
디버그 로그는 개발 작업과 문제 해결에 필수적입니다. LibreChat을 실행하는 동안 문제가 발생하면, 가능한 한 동일한 상황을 재현한 뒤 ./api/logs/debug-%DATE%.log에서 찾을 수 있는 로그와 함께 **이슈를 보고**해 주시기 바랍니다.
오류 로그 또한 동일한 위치인 ./api/logs/error-%DATE%.log에 저장됩니다. Meilisearch를 구성한 경우, 이를 위한 별도의 로그 파일도 생성됩니다.
참고:
참고: 로그는 14일 주기로 순환되므로, 14일마다 하나의 오류 로그 파일, 하나의 디버그 로그 파일, 그리고 하나의 meiliSync 로그 파일이 생성됩니다. 오류는 디버그 로그 파일에도 포함되지만, 오류 로그 파일에서 스택 추적 및 더 자세한 내용을 확인할 수 있습니다.
설정
- 다음 환경 변수를 사용하여 디버그 로그를 전환할 수 있습니다. 기본적으로 이 변수를 설정하지 않아도 디버그 로그가 생성되지만,
FALSE로 설정하여 비활성화할 수 있는 옵션이 있습니다.
| Key | Type | Description | Example |
|---|---|---|---|
| DEBUG_LOGGING | boolean | 디버그 로그를 활성 상태로 유지합니다. | DEBUG_LOGGING=true |
참고: 프로덕션 환경에서는 디버그 로그를 비활성화하는 것이 좋습니다.
- 콘솔/터미널에서 상세한 서버 출력을 확인하려면 다음을
TRUE로 설정할 수 있습니다:
| Key | Type | Description | Example |
|---|---|---|---|
| DEBUG_CONSOLE | boolean | 파일 디버그 로그와 동일한 형식으로 상세 콘솔/stdout 로그를 활성화합니다. | DEBUG_CONSOLE=false |
하지만 출력값이 매우 장황해질 수 있으므로 권장되지 않습니다. 기본적으로 비활성화되어 있으며 꼭 필요한 경우에만 활성화해야 합니다.
- 클라우드 배포(GCP 또는 AWS 등)에서 콘솔 로그를 처리할 때, 이 옵션을 활성화하면 UTC 타임스탬프와 함께 로그를 JSON 형식으로 덤프합니다.
| Key | Type | Description | Example |
|---|---|---|---|
| CONSOLE_JSON | boolean | GCP/AWS와 같은 클라우드 배포에 적합한 상세 JSON 콘솔/stdout 로그를 활성화합니다. | CONSOLE_JSON=false |
기본적으로 JSON 문자열 길이는 255자로 잘립니다. 다음 환경 변수를 사용하여 이를 구성할 수 있습니다:
| Key | Type | Description | Example |
|---|---|---|---|
| CONSOLE_JSON_STRING_LENGTH | number | JSON 콘솔/stdout 로그의 문자열 값에 대한 잘림 크기를 설정합니다. 기본값: 255. | # CONSOLE_JSON_STRING_LENGTH=255 |
- 파일 기반 로그 전송은 기본적으로 활성화되어 있습니다. 배포 시 로그를 stdout/stderr로만 출력하려면
LOG_TO_FILE=false로 설정하세요.
| Key | Type | Description | Example |
|---|---|---|---|
| LOG_TO_FILE | boolean | file-backed Winston 전송을 비활성화하려면 false로 설정하세요. | LOG_TO_FILE=true |
OpenTelemetry Tracing
LibreChat은 서버, 데이터베이스, Redis 및 아웃바운드 HTTP 가시성을 위한 백엔드 OpenTelemetry 추적을 내보낼 수 있습니다. Redis 명령 수준 스팬(span)은 선택 사항이므로 기본 추적은 상위 수준으로 유지됩니다. 이는 GenAI 관련 프롬프트 및 모델 관측 가능성을 위해 권장되는 옵션인 Langfuse와는 별개입니다.
| Key | Type | Description | Example |
|---|---|---|---|
| OTEL_TRACING_ENABLED | boolean | 백엔드 OpenTelemetry 추적을 활성화합니다. | # OTEL_TRACING_ENABLED=false |
| OTEL_SERVICE_NAME | string | OpenTelemetry에 보고되는 서비스 이름입니다. 기본값: librechat. | # OTEL_SERVICE_NAME=librechat |
| OTEL_SERVICE_VERSION | string | OpenTelemetry에 보고된 서비스 버전입니다. | # OTEL_SERVICE_VERSION= |
| OTEL_EXPORTER_OTLP_ENDPOINT | string | 기본 OTLP exporter endpoint. | # OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 |
| OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | string | 추적 전용 OTLP endpoint. | # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT= |
| OTEL_EXPORTER_OTLP_HEADERS | string | OTLP exporter 헤더. | # OTEL_EXPORTER_OTLP_HEADERS= |
| OTEL_TRACES_EXPORTER | string | Trace exporter 선택. | # OTEL_TRACES_EXPORTER=otlp |
| OTEL_TRACES_SAMPLER | string | OpenTelemetry 트레이스 샘플러. | # OTEL_TRACES_SAMPLER=parentbased_always_on |
| OTEL_LOG_LEVEL | string | OpenTelemetry SDK 로그 레벨. | # OTEL_LOG_LEVEL=INFO |
| OTEL_SDK_DISABLED | boolean | 추적(tracing)이 활성화된 경우에도 OpenTelemetry SDK를 비활성화합니다. | # OTEL_SDK_DISABLED=false |
| OTEL_IOREDIS_TRACING_ENABLED | boolean | Redis 명령 수준 스팬을 활성화합니다. 백엔드 추적을 상위 수준으로 유지하기 위해 기본적으로 비활성화되어 있습니다. | # OTEL_IOREDIS_TRACING_ENABLED=false |
이 가이드는 어떤가요?