Send Logs Somewhere¶

The firewall logs every decision through Monolog, so any Monolog handler works. Each entry under logger: is one destination, and you can stack as many as you need.

This page is the common setups. For every handler and every option, see Logging.

A file, to start with¶

logger:
  - class: Monolog\Handler\StreamHandler
    args:
      - /var/log/firewall/firewall.log
      - Monolog\Level::Info

A relative path resolves against the YAML file that declares it, not the working directory — so the same config writes to the same place under php -S, php-fpm and cron.

A file that does not grow forever¶

StreamHandler never rotates. On a busy site that is a disk-space incident waiting to happen, so prefer:

logger:
  - class: Monolog\Handler\RotatingFileHandler
    args:
      - /var/log/firewall/firewall.log
      - 14                          # keep two weeks
      - Monolog\Level::Info

Somewhere you can query it¶

A file answers "what happened just now". It does not answer "how often did this rule fire last month", which is the question that actually comes up. For that, log to a database table:

logger:
  - class: Kanopi\Firewall\Logging\DatabaseHandler
    args:
      - { dsn: "mysql://firewall:secret@localhost/security" }
      - firewall_log
      - Monolog\Level::Info

That has real costs — a write on the request path, a table that grows, and a schema that changes between releases. All three are covered in Database logging; read it before turning this on in production, and set up retention at the same time rather than later.

Paging a human, but only when it matters¶

Every handler takes its own level, so tee everything to a file and escalate only what deserves waking somebody:

logger:
  # Everything
  - class: Monolog\Handler\StreamHandler
    args:
      - /var/log/firewall/firewall.log
      - Monolog\Level::Info

  # Only the things that mean something is broken
  - class: Monolog\Handler\SlackWebhookHandler
    args:
      - "%env(SLACK_WEBHOOK_URL)%"
      - "#alerts"
      - "firewall"
      - true
      - null
      - false
      - true
      - Monolog\Level::Critical

Slack, Pushover, IFTTT and Telegram all need ext-curl. Mail handlers may need a transport package installed.

Better: write lines, let something else ship them¶

logger:
  - class: Monolog\Handler\StreamHandler
    args:
      - php://stdout
      - Monolog\Level::Info
    formatter:
      class: Monolog\Formatter\JsonFormatter

Then point Vector, Fluent Bit, Filebeat or promtail at it. Delivery, retries, batching and backpressure are handled by software built for exactly that, and the firewall's cost is a write() to a local stream.

For a containerised deployment this is simply the right answer, and it needs nothing from this package. Reach for the next section only when you cannot do it.

If you must send HTTP from PHP: defer it¶

logger:
  - class: Kanopi\Firewall\Logging\Handler\DeferredHandler
    args:
      # The handler to flush into, once the visitor has been served.
      - class: Monolog\Handler\LogglyHandler
        args: ["%env(LOGGLY_TOKEN)%", Monolog\Level::Warning]
      - 0                       # buffer limit; 0 holds everything
      - Monolog\Level::Warning

handle()   →  buffer in memory, return immediately
shutdown   →  fastcgi_finish_request()   ← the visitor is served here
           →  flush the buffer to the wrapped handler

A wrapper rather than a thirteenth HTTP handler: Monolog's are maintained, and reimplementing the Datadog, Loki and Splunk payload formats is a treadmill. What was missing is a way to get any of them off the request path.

It works with any handler, not only the HTTP ones — and on a framework that already closes the connection itself (Symfony's Response::send() calls fastcgi_finish_request()), the call here is a harmless no-op.

Wrapping handlers, generally¶

A wrapping handler takes another handler as its first argument, and until 2.31.0 YAML had no way to say that — so the answer for wrapping anything was "write PHP instead". Any nested {class, args} block is now built as a handler, which makes Monolog's own wrappers configurable too:

logger:
  # Keep debug records in memory; write them all only if something goes wrong.
  - class: Monolog\Handler\FingersCrossedHandler
    args:
      - class: Monolog\Handler\StreamHandler
        args: [/var/log/firewall/firewall.log, Monolog\Level::Debug]
      - Monolog\Level::Error

A nested block that is not a handler class is rejected the same way a top-level one is, and a handler whose constructor genuinely takes an array is unaffected.

Check it is actually writing¶

$ firewall-doctor config/firewall.yml

A handler that cannot reach its destination — an unwritable path, an unreachable database — is reported there rather than failing silently on the next request.

Then what¶