Extending and Improving Drupal’s Logging System with Monolog

Effective logging sits at the heart of building and operating dependable web applications. It gives engineering teams the visibility they need to understand runtime behavior, investigate errors, maintain audit trails, and act decisively when issues arise in live environments. Drupal ships with two native logging options: Database Logging (dblog) and Syslog. In the dblog approach, messages are written directly into database tables, whereas Syslog redirects those messages to the underlying operating system’s logging facility, avoiding database persistence altogether.

Although dblog is convenient during development and performs adequately on smaller or low-usage sites, its reliance on constant database writes can create performance strain as traffic and complexity increase. Syslog mitigates this concern by shifting logging responsibilities to the system level, making it a more practical choice for cloud-hosted or server-based deployments where centralized log access and quicker diagnostics are essential.

For Drupal applications operating at scale, especially in high-traffic or enterprise environments, Monolog stands out as the preferred logging solution. It introduces a highly configurable and extensible logging layer that supports multiple channels, handlers, and output formats. Monolog enables logs to be streamed to files, external services, or modern observability platforms, while also supporting structured formats like JSON, severity-based filtering, and environment-specific setups. This approach not only reduces runtime overhead but also delivers deeper operational insight and long-term scalability for production systems.

Difference Between dblog, Syslog, and Monolog in Drupal

What is Monolog?

Monolog is a popular and powerful PHP logging library used by many frameworks, including Symfony (which Drupal is built on). It provides advanced logging capabilities and supports multiple output destinations, known as handlers.

With Monolog, logs can be sent to:

• Files (with rotation)
• Stdout / stderr (ideal for Docker & Lando)
• Syslog
• Cloud logging services
• Centralized systems like:
  • Graylog
  • Logstash / ELK Stack
  • Papertrail
  • New Relic
• Notifications (Slack, Email, Webhooks)

Drupal integrates Monolog through the contributed Monolog module, allowing you to completely extend and replace the default logging system.

Why Use Monolog in Drupal?

Using Monolog in Drupal provides several benefits:

• Better performance than database logging
• Centralized log management for distributed systems
• Multiple handlers (log to file + terminal + external service)
• Log rotation to prevent disk overuse
• Severity‑based logging (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• Perfect for Docker / Lando / Kubernetes environments

In production environments, logging to stdout or external services is considered a best practice.

Installing Monolog in Drupal

Step 1: Install via Composer

composer require drupal/monolog

Step 2: Enable the Module

drush en monolog -y

Step 3: Disable Database Logging (Optional but Recommended)

drush pmu dblog -y

This step is optional, but highly recommended for production to reduce database overhead.

Basic Monolog Configuration in Drupal

Drupal allows you to define Monolog handlers using Symfony service definitions.

Step 4: Create a Site‑Specific Service File

Create a file named:

sites/default/monolog.services.yml

This file will define where and how logs are written.

Example 1: Output Logs to Terminal (Stdout)

This setup is ideal for Docker, Lando, and Kubernetes, where logs are collected from stdout.

parameters:
 monolog.channel_handlers:
  default: ['stdout']

services:
 monolog.handler.stdout:
  class: Monolog\Handler\StreamHandler
  arguments: ['php://stdout', 'DEBUG']
  tags:
   - { name: monolog.handler, channel: default }

Example 2: Output Logs to a Rotating File

Logs will be stored in:
public://logs/debug.log
→ sites/default/files/logs/debug.log

parameters:
 monolog.channel_handlers:
  default: ['rotating_file']

services:
 monolog.handler.rotating_file:
  class: Monolog\Handler\RotatingFileHandler
  arguments: ['public://logs/debug.log', 10, 'DEBUG']
  tags:
   - { name: monolog.handler, channel: default }

Explanation:

• 10 → Keeps the last 10 rotated log files
• DEBUG → Minimum log level
• Make sure the logs directory exists and is writable.

Example 3: Output Logs to Both Terminal and File

parameters:
 monolog.channel_handlers:
  default: ['stdout', 'rotating_file']

services:
 monolog.handler.stdout:
 class: Monolog\Handler\StreamHandler
 arguments: ['php://stdout', 'DEBUG']
 tags:
  - { name: monolog.handler, channel: default }

 monolog.handler.rotating_file:
 class: Monolog\Handler\RotatingFileHandler
 arguments: ['public://logs/debug.log', 10, 'DEBUG']
 tags:
  - { name: monolog.handler, channel: default }

This is a very common setup for local and staging environments.

Writing Drupal Monolog Logs to S3 / Azure Blob

Recommended Approach: Monolog logs in Drupal can be stored in Amazon S3 or Azure Blob Storage, but they should not be written there directly from the application layer. Instead, follow this two-step, production-ready approach:

• Write logs locally or to STDOUT: Configure Monolog to log into local files or STDOUT. This keeps logging fast, reliable, and independent of network latency.
• Forward logs to S3 / Azure Blob asynchronously: Use infrastructure-level tools such as:
  • AWS CloudWatch → S3
  • Azure Monitor / Log Analytics → Azure Blob
  • Cron-based batch uploads or log shippers (Fluent Bit, Filebeat)

This approach ensures better performance, lower cost, and higher reliability, while still centralizing logs in S3 or Azure Blob for long-term storage and analysis.

Step 5: Tell Drupal to Load the Monolog Services File

Add the following line to your settings.php file:

$settings['container_yamls'][] = 'sites/default/monolog.services.yml';

Clear caches after making this change:

drush cr

Step 6: Test Logging

Use Drupal’s logger service anywhere in custom code:

\Drupal::logger('custom_channel')->debug('This is a debug message.');
\Drupal::logger('custom_channel')->error('This is an error message.');

You can also create different channels for different modules or features.

Viewing Logs in Containers

Lando

lando logs -f

Docker

docker logs -f <container_name>
docker logs -f

This makes Monolog ideal for modern DevOps workflows.

Best Practices for Using Monolog in Drupal

• Use stdout logging in containers
• Disable dblog in production
• Separate log levels (ERROR vs DEBUG)
• Rotate file logs to prevent disk issues
• Send critical logs to alerting systems (Slack, Email)
• Avoid excessive DEBUG logging in production

Conclusion

By integrating Monolog into Drupal, you move from basic database logging to a scalable, high‑performance, and enterprise‑ready logging system. Whether you are running a small site, a headless Drupal backend, or a large‑scale cloud deployment, Monolog gives you the flexibility and control needed to make your logs meaningful and actionable.

Monolog is not just a logging replacement—it is a foundation for better monitoring, debugging, and observability in modern Drupal applications.