LibreChatLogging System
This doc explains how to use the logging feature of LibreChat, which saves error and debug logs in the `/api/logs` folder. You can use these logs to troubleshoot issues, monitor your server, and report bugs. Debug logs are written only when you opt in with DEBUG_LOGGING=true.
General
LibreChat has central logging built into its backend (api).
- With the docker install, log files are saved in
/logs
- With the npm install, log files are saved in
/api/logs
Error logs are saved by default. Debug log files are written only when DEBUG_LOGGING=true; the provided .env.example sets it to true, but if the variable is unset no debug file is created.
This allows you to monitor your server through external tools that inspect log files, such as the ELK stack.
Debug logs are essential for developer work and fixing issues. If you encounter any problems running LibreChat, reproduce as close as possible, and report the issue with your logs found in ./api/logs/debug-%DATE%.log.
Errors logs are also saved in the same location: ./api/logs/error-%DATE%.log. If you have meilisearch configured, there is a separate log file for this as well.
Note:
Log files rotate daily: a new file is started each day, and a file is also split once it reaches 20 MB. Rotated files are gzip-compressed and kept for 14 days. Errors are also present in debug log files, but the error log files provide stack traces and more detail.
Setup
- Debug log files are written only when this variable is set to
true. If it is unset or set to anything else, no debug file is created.
| Key | Type | Description | Example |
|---|---|---|---|
| DEBUG_LOGGING | boolean | Write debug logs to file. Required for debug log files to be created. | DEBUG_LOGGING=true |
Note: it's recommended to leave debug logs disabled in a production environment.
- For verbose server output in the console/terminal, you can set the following to
TRUE:
| Key | Type | Description | Example |
|---|---|---|---|
| DEBUG_CONSOLE | boolean | Enable verbose console/stdout logs in the same format as file debug logs. | DEBUG_CONSOLE=false |
This is not recommended however, as the outputs can be quite verbose. It's disabled by default and should be enabled sparingly.
- When handling console logs in cloud deployments (such as GCP or AWS), enabling this will dump the logs with a UTC timestamp and format them as JSON.
| Key | Type | Description | Example |
|---|---|---|---|
| CONSOLE_JSON | boolean | Enable verbose JSON console/stdout logs suitable for cloud deployments like GCP/AWS. | CONSOLE_JSON=false |
By default, the JSON string length is truncated to 255 characters. You can configure this with the following environment variable:
| Key | Type | Description | Example |
|---|---|---|---|
| CONSOLE_JSON_STRING_LENGTH | number | Configure the truncation size for string values in JSON console/stdout logs. Default: 255. | # CONSOLE_JSON_STRING_LENGTH=255 |
- Console verbosity can be set with
CONSOLE_LOG_LEVEL(error,warn,info,http,verbose,debug,activity,silly, orsilent).silentturns off console output without disabling file logging. Invalid values fall back to the default with a warning.
| Key | Type | Description | Example |
|---|---|---|---|
| CONSOLE_LOG_LEVEL | string | Console verbosity. Defaults to info, or debug when DEBUG_CONSOLE=true; an explicit value takes precedence. | # CONSOLE_LOG_LEVEL=info |
- Debug log messages are truncated to 150 characters by default, and log redaction is bounded to 5000 values per record. Tune these with
DEBUG_MESSAGE_LENGTHandLOG_REDACTION_MAX_NODES.
| Key | Type | Description | Example |
|---|---|---|---|
| DEBUG_MESSAGE_LENGTH | number | Maximum length of a debug log message before it is truncated. Default: 150. | # DEBUG_MESSAGE_LENGTH=150 |
| LOG_REDACTION_MAX_NODES | number | Maximum number of values one log record may redact before the remainder is replaced. Default: 5000. | # LOG_REDACTION_MAX_NODES=5000 |
-
To write log files somewhere other than the default location, set
LIBRECHAT_LOG_DIR. See Logging in the.envreference. -
File-backed log transports are enabled by default. Set
LOG_TO_FILE=falseif your deployment should only emit logs to stdout/stderr.
| Key | Type | Description | Example |
|---|---|---|---|
| LOG_TO_FILE | boolean | Set to false to disable file-backed Winston transports. | LOG_TO_FILE=true |
OpenTelemetry Tracing
LibreChat can emit backend OpenTelemetry traces for server, database, Redis, and outbound HTTP visibility. Redis command-level spans are opt-in so default traces stay high-level. This is separate from Langfuse, which remains the recommended option for GenAI-specific prompt and model observability.
| Key | Type | Description | Example |
|---|---|---|---|
| OTEL_TRACING_ENABLED | boolean | Enable backend OpenTelemetry tracing. | # OTEL_TRACING_ENABLED=false |
| OTEL_SERVICE_NAME | string | Service name reported to OpenTelemetry. Default: librechat. | # OTEL_SERVICE_NAME=librechat |
| OTEL_SERVICE_VERSION | string | Service version reported to OpenTelemetry. | # OTEL_SERVICE_VERSION= |
| OTEL_EXPORTER_OTLP_ENDPOINT | string | Base OTLP exporter endpoint. | # OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 |
| OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | string | Trace-specific OTLP endpoint. | # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT= |
| OTEL_EXPORTER_OTLP_HEADERS | string | OTLP exporter headers. | # OTEL_EXPORTER_OTLP_HEADERS= |
| OTEL_TRACES_EXPORTER | string | Trace exporter selection. | # OTEL_TRACES_EXPORTER=otlp |
| OTEL_TRACES_SAMPLER | string | OpenTelemetry trace sampler. | # OTEL_TRACES_SAMPLER=parentbased_always_on |
| OTEL_LOG_LEVEL | string | OpenTelemetry SDK log level. | # OTEL_LOG_LEVEL=INFO |
| OTEL_SDK_DISABLED | boolean | Disable the OpenTelemetry SDK even when tracing is enabled. | # OTEL_SDK_DISABLED=false |
| OTEL_IOREDIS_TRACING_ENABLED | boolean | Enable Redis command-level spans. Disabled by default to keep backend traces high-level. | # OTEL_IOREDIS_TRACING_ENABLED=false |
How is this guide?