LibreChatHệ thống ghi nhật ký
Tài liệu này giải thích cách sử dụng tính năng ghi nhật ký của LibreChat, tính năng này lưu các nhật ký lỗi và gỡ lỗi trong thư mục `/api/logs`. Bạn có thể sử dụng các nhật ký này để khắc phục sự cố, giám sát máy chủ và báo cáo lỗi. Bạn cũng có thể tắt nhật ký gỡ lỗi nếu muốn tiết kiệm dung lượng.
Tổng quan
LibreChat có tính năng ghi nhật ký tập trung được tích hợp sẵn trong backend (api) của nó.
- Với cài đặt Docker, các tệp nhật ký được lưu trong
/logs
- Với cài đặt npm, các tệp nhật ký được lưu trong
/api/logs
Các nhật ký lỗi được lưu theo mặc định. Các nhật ký gỡ lỗi được bật theo mặc định nhưng có thể tắt nếu không cần thiết.
Điều này cho phép bạn giám sát máy chủ của mình thông qua các công cụ bên ngoài có khả năng kiểm tra tệp nhật ký, chẳng hạn như the ELK stack.
Nhật ký gỡ lỗi (debug logs) rất cần thiết cho công việc của nhà phát triển và việc khắc phục sự cố. Nếu bạn gặp bất kỳ vấn đề nào khi chạy LibreChat, hãy tái hiện lại lỗi sát với thực tế nhất có thể và báo cáo vấn đề kèm theo nhật ký của bạn được tìm thấy trong ./api/logs/debug-%DATE%.log.
Các tệp nhật ký lỗi (error logs) cũng được lưu tại cùng vị trí: ./api/logs/error-%DATE%.log. Nếu bạn đã cấu hình meilisearch, cũng sẽ có một tệp nhật ký riêng cho thành phần này.
Lưu ý:
Lưu ý: Nhật ký được xoay vòng theo chu kỳ 14 ngày, vì vậy bạn sẽ tạo ra một tệp nhật ký lỗi, một tệp nhật ký gỡ lỗi và một tệp nhật ký meiliSync cho mỗi 14 ngày. Các lỗi cũng sẽ xuất hiện trong các tệp nhật ký gỡ lỗi, nhưng các tệp nhật ký lỗi sẽ cung cấp dấu vết ngăn xếp (stack trace) và thông tin chi tiết hơn.
Thiết lập
- Bật/tắt nhật ký gỡ lỗi (debug logs) bằng biến môi trường sau. Theo mặc định, ngay cả khi bạn không bao giờ thiết lập biến này, nhật ký gỡ lỗi vẫn sẽ được tạo, nhưng bạn có tùy chọn tắt chúng bằng cách đặt giá trị là
FALSE.
| Key | Type | Description | Example |
|---|---|---|---|
| DEBUG_LOGGING | boolean | Giữ nhật ký gỡ lỗi hoạt động. | DEBUG_LOGGING=true |
Lưu ý: bạn nên tắt nhật ký gỡ lỗi (debug logs) trong môi trường production.
- Để có đầu ra máy chủ chi tiết trong console/terminal, bạn có thể đặt giá trị sau thành
TRUE:
| Key | Type | Description | Example |
|---|---|---|---|
| DEBUG_CONSOLE | boolean | Bật nhật ký console/stdout chi tiết ở cùng định dạng với nhật ký gỡ lỗi tệp. | DEBUG_CONSOLE=false |
Tuy nhiên, điều này không được khuyến khích vì đầu ra có thể khá dài dòng. Tính năng này bị tắt theo mặc định và chỉ nên được bật khi thực sự cần thiết.
- Khi xử lý các bản ghi console trong các triển khai trên đám mây (như GCP hoặc AWS), việc bật tính năng này sẽ xuất các bản ghi kèm theo dấu thời gian UTC và định dạng chúng dưới dạng JSON.
| Key | Type | Description | Example |
|---|---|---|---|
| CONSOLE_JSON | boolean | Bật nhật ký console/stdout JSON chi tiết phù hợp cho các triển khai đám mây như GCP/AWS. | CONSOLE_JSON=false |
Theo mặc định, độ dài chuỗi JSON được cắt bớt thành 255 ký tự. Bạn có thể cấu hình điều này bằng biến môi trường sau:
| Key | Type | Description | Example |
|---|---|---|---|
| CONSOLE_JSON_STRING_LENGTH | number | Cấu hình kích thước cắt bớt cho các giá trị chuỗi trong nhật ký console/stdout JSON. Mặc định: 255. | # CONSOLE_JSON_STRING_LENGTH=255 |
- Các transport log dựa trên tệp được bật theo mặc định. Hãy đặt
LOG_TO_FILE=falsenếu quá trình triển khai của bạn chỉ nên xuất log ra stdout/stderr.
| Key | Type | Description | Example |
|---|---|---|---|
| LOG_TO_FILE | boolean | Đặt thành false để vô hiệu hóa các Winston transport dựa trên tệp. | LOG_TO_FILE=true |
Theo dõi OpenTelemetry
LibreChat có thể phát ra các dấu vết OpenTelemetry phía backend cho server, cơ sở dữ liệu, Redis và khả năng hiển thị HTTP gửi đi. Các span ở cấp độ lệnh Redis là tùy chọn (opt-in) để các dấu vết mặc định vẫn ở mức cao. Điều này tách biệt với Langfuse, vốn vẫn là tùy chọn được khuyến nghị để quan sát prompt và model dành riêng cho GenAI.
| Key | Type | Description | Example |
|---|---|---|---|
| OTEL_TRACING_ENABLED | boolean | Bật tính năng theo dõi OpenTelemetry cho backend. | # OTEL_TRACING_ENABLED=false |
| OTEL_SERVICE_NAME | string | Tên dịch vụ được báo cáo cho OpenTelemetry. Mặc định: librechat. | # OTEL_SERVICE_NAME=librechat |
| OTEL_SERVICE_VERSION | string | Phiên bản dịch vụ được báo cáo cho OpenTelemetry. | # OTEL_SERVICE_VERSION= |
| OTEL_EXPORTER_OTLP_ENDPOINT | string | Endpoint của OTLP exporter cơ sở. | # OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 |
| OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | string | Endpoint OTLP dành riêng cho trace. | # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT= |
| OTEL_EXPORTER_OTLP_HEADERS | string | Các header của OTLP exporter. | # OTEL_EXPORTER_OTLP_HEADERS= |
| OTEL_TRACES_EXPORTER | string | Lựa chọn bộ xuất vết (trace exporter). | # OTEL_TRACES_EXPORTER=otlp |
| OTEL_TRACES_SAMPLER | string | Bộ lấy mẫu dấu vết OpenTelemetry. | # OTEL_TRACES_SAMPLER=parentbased_always_on |
| OTEL_LOG_LEVEL | string | Cấp độ nhật ký OpenTelemetry SDK. | # OTEL_LOG_LEVEL=INFO |
| OTEL_SDK_DISABLED | boolean | Vô hiệu hóa OpenTelemetry SDK ngay cả khi tính năng theo dõi (tracing) đã được bật. | # OTEL_SDK_DISABLED=false |
| OTEL_IOREDIS_TRACING_ENABLED | boolean | Bật các span ở cấp độ lệnh Redis. Mặc định bị tắt để giữ cho các trace của backend ở mức khái quát. | # OTEL_IOREDIS_TRACING_ENABLED=false |
Hướng dẫn này thế nào?