Skip to main content
LibreChat provides comprehensive logging and monitoring capabilities to help you track system health, debug issues, and understand usage patterns.

​
Overview

Application Logs

View and manage application logs

Performance Monitoring

Track system performance metrics

User Activity

Monitor user actions and usage

Error Tracking

Track and debug errors

​
Application Logs

LibreChat uses Winston for structured logging.

​
Log Locations

Logs are stored in the logs/ directory:
  • logs/app.log - General application logs
  • logs/error.log - Error logs only
  • logs/debug.log - Debug-level logs (if enabled)
  • logs/moderation.log - Content moderation events
  • logs/meili.log - Meilisearch sync logs

​
Log Levels

Configure logging level with environment variables:
​
LOG_LEVEL
string
default:"info"
Logging level: error, warn, info, http, verbose, debug, silly
​
DEBUG_LOGGING
boolean
default:"false"
Enable debug-level logging
​
DEBUG_CONSOLE
boolean
default:"false"
Output debug logs to console

​
Example Configuration

.env
# Production: minimal logging
LOG_LEVEL=warn
DEBUG_LOGGING=false

# Development: verbose logging
LOG_LEVEL=debug
DEBUG_LOGGING=true
DEBUG_CONSOLE=true

​
Viewing Logs

View live logs:
docker logs -f LibreChat
View last 100 lines:
docker logs --tail 100 LibreChat
View logs from specific time:
docker logs --since 2024-03-03T10:00:00 LibreChat

​
Log Rotation

LibreChat uses winston-daily-rotate-file for automatic log rotation: 
// Logs rotate daily
// Maximum 14 days of logs kept
// Maximum log file size: 20MB
Manual log rotation: 
# Archive old logs
mv logs/app.log logs/app.log.$(date +%Y%m%d)

# Restart to create new log file
npm run backend:stop && npm run backend

​
Performance Monitoring

​
System Metrics

Monitor key performance indicators:

​
Response Times

// Enable response time logging
app.use(responseTime((req, res, time) => {
  logger.http(`${req.method} ${req.url} - ${time}ms`);
}));

​
Memory Usage

Monitor Node.js memory: 
# Run backend with memory inspection
npm run backend:inspect
Access Chrome DevTools at chrome://inspect to analyze:
  • Heap snapshots
  • Memory allocation
  • Memory leaks

​
Database Performance

Monitor MongoDB performance:
1

Enable MongoDB Profiling

db.setProfilingLevel(1, { slowms: 100 })
2

View Slow Queries

db.system.profile.find({ millis: { $gt: 100 } }).sort({ ts: -1 })
3

Analyze Query Plans

db.conversations.find({ user: userId }).explain("executionStats")

​
Meilisearch Monitoring

Monitor search index health: 
# Check Meilisearch stats
curl http://localhost:7700/stats

# Check index status
curl http://localhost:7700/indexes/messages/stats

​
User Activity

Track user actions and usage patterns.

​
User Statistics

View statistics for a specific user: 
npm run user-stats [email protected]
Displays:
  • Total conversations
  • Messages sent
  • Tokens used
  • Files uploaded
  • Agents created
  • Last login
  • Registration date

​
Activity Logs

Important user actions are logged: 
{
  "timestamp": "2024-03-03T10:30:00Z",
  "userId": "user123",
  "action": "conversation_created",
  "resource": "conv_abc123",
  "metadata": {
    "endpoint": "openai",
    "model": "gpt-4"
  }
}

​
Usage Analytics

Query MongoDB for usage insights: 
db.messages.aggregate([
  { $group: { _id: "$user", count: { $sum: 1 } } },
  { $sort: { count: -1 } },
  { $limit: 10 }
])

db.messages.aggregate([
  { $group: {
    _id: { $dateToString: { format: "%Y-%m-%d", date: "$createdAt" } },
    count: { $sum: 1 }
  }},
  { $sort: { _id: -1 } },
  { $limit: 30 }
])

​
Error Tracking

​
Error Logs

All errors are logged to logs/error.log: 
{
  "level": "error",
  "message": "Failed to generate response",
  "timestamp": "2024-03-03T10:30:00Z",
  "stack": "Error: API request failed...",
  "context": {
    "userId": "user123",
    "conversationId": "conv_abc",
    "endpoint": "openai"
  }
}

​
Common Error Patterns

Monitor for these common issues: 
grep "rate limit" logs/error.log
Solutions:
  • Implement request queuing
  • Add API key rotation
  • Use rate limiting middleware
grep "MongoNetworkError" logs/error.log
Solutions:
  • Check MongoDB is running
  • Verify connection string
  • Increase connection pool size
grep "out of memory" logs/error.log
Solutions:
  • Increase Node.js memory limit
  • Optimize queries
  • Implement pagination

​
Debugging Tools

Start with debugging enabled:
npm run backend:inspect
Connect Chrome DevTools:
  1. Open chrome://inspect
  2. Click “inspect” under Remote Target
  3. Set breakpoints and debug

​
Health Checks

Implement health check endpoints for monitoring:

​
Application Health

curl http://localhost:3080/health
Response: 
{
  "status": "healthy",
  "uptime": 3600,
  "timestamp": "2024-03-03T10:30:00Z"
}

​
Database Health

curl http://localhost:3080/health/db

​
Search Health

curl http://localhost:3080/health/search

​
Monitoring Tools Integration

​
Prometheus

Expose metrics for Prometheus:
api/server/middleware/metrics.js
const promClient = require('prom-client');

// Create metrics
const httpRequestDuration = new promClient.Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of HTTP requests in seconds',
  labelNames: ['method', 'route', 'status_code'],
});

// Expose metrics endpoint
app.get('/metrics', (req, res) => {
  res.set('Content-Type', promClient.register.contentType);
  res.end(promClient.register.metrics());
});

​
Grafana Dashboards

Create dashboards for:
  • Request rates and latencies
  • Error rates
  • Database query performance
  • Memory and CPU usage
  • User activity

​
Best Practices

1

Use Appropriate Log Levels

  • Production: warn or error
  • Development: debug or info
  • Troubleshooting: verbose or silly
2

Implement Log Rotation

Prevent disk space issues by rotating logs regularly.
3

Monitor Key Metrics

Track:
  • Response times
  • Error rates
  • Database performance
  • Memory usage
4

Set Up Alerts

Configure alerts for:
  • High error rates
  • Slow responses
  • Database issues
  • Disk space
5

Regular Log Review

Review logs regularly to identify patterns and potential issues.

​
Troubleshooting

  • Enable log rotation
  • Reduce log level in production
  • Archive or delete old logs
  • Use external log aggregation
  • Check log level configuration
  • Verify write permissions on logs directory
  • Ensure logger is properly configured
  • Check disk space availability
  • Use docker logs command
  • Mount logs directory as volume
  • Configure Docker logging driver

Build docs developers (and LLMs) love

Get started for freeTalk to us