Skip to content

Logging

David Ciulla edited this page Nov 7, 2026 · 1 revision

Logging

Laravex provides a structured logging layer in Laravex.Log.Logger that mirrors Laravel's channel-based logging API. Log entries are written synchronously to file, standard error, or discarded, depending on the configured channels.


Configuration

Logging is configured under the logging key (typically config/logging.exs):

config :laravex, logging: %{
  "default" => "stack",
  "channels" => %{
    "stack" => %{
      "driver"   => "stack",
      "channels" => ["single"]
    },
    "single" => %{
      "driver" => "single",
      "path"   => "storage/logs/laravex.log",
      "level"  => "debug"
    },
    "daily" => %{
      "driver"    => "daily",
      "path"      => "storage/logs/laravex.log",
      "level"     => "debug",
      "max_files" => 14
    }
  }
}

Writing Log Messages

The logger module exposes level-specific helpers that mirror Laravel's Log facade:

alias Laravex.Log.Logger

Logger.debug("Cache miss for key: #{key}")
Logger.info("User #{user_id} logged in")
Logger.warning("Rate limit approaching for IP #{ip}")
Logger.error("Failed to send email", %{user_id: user_id, error: reason})

You may also call Logger.log/3 directly with any atom level:

Logger.log(:notice, "Deployment finished")
Logger.log(:critical, "Database unreachable", %{host: host})

Log levels

Levels follow the RFC 5424 / PSR-3 severity hierarchy. Only messages at or above the channel's configured level are written:

Atom Severity
:debug 0 (lowest)
:info 1
:notice 2
:warning 3
:error 4
:critical 5
:alert 6
:emergency 7 (highest)

Channels and Drivers

The logging.default key names the channel used by all Logger.* calls. The channel's driver key determines how entries are written.

stack

Fans out to multiple sub-channels. Configure the list of channels to write to:

"stack" => %{
  "driver"   => "stack",
  "channels" => ["single", "daily"]
}

single

Appends every entry to a single log file at the given path:

"single" => %{
  "driver" => "single",
  "path"   => "storage/logs/laravex.log",
  "level"  => "debug"
}

daily

Writes to a date-stamped file and rotates old files automatically:

"daily" => %{
  "driver"    => "daily",
  "path"      => "storage/logs/laravex.log",
  "level"     => "debug",
  "max_files" => 14      # keep this many daily files; older files are deleted
}

Daily files are named {base}-{YYYY-MM-DD}.log, e.g. laravex-2026-11-07.log. After writing, the channel deletes the oldest files beyond max_files (default: 14).

monthly

Same as daily but rotated monthly:

"monthly" => %{
  "driver" => "monthly",
  "path"   => "storage/logs/laravex.log",
  "level"  => "warning"
}

Monthly files are named {base}-{YYYY-MM}.log, e.g. laravex-2026-11.log.

stderr / errorlog

Writes formatted log lines to standard error. Useful in containerised deployments:

"stderr" => %{
  "driver" => "stderr",
  "level"  => "error"
}

null

Discards all log entries silently:

"null" => %{"driver" => "null"}

Log Format

Each entry is written as a single line:

[2026-11-07T07:45:00.000000Z] error: Failed to send email %{error: :timeout, user_id: 42}

Fields:

Part Description
[timestamp] UTC ISO 8601 datetime
level Log level atom
message Log message string
meta Elixir map of extra context (omitted when empty)

Placeholder Replacement

Enable replace_placeholders: true on a channel to substitute common placeholders in messages:

"single" => %{
  "driver"               => "single",
  "path"                 => "storage/logs/laravex.log",
  "replace_placeholders" => true
}

Supported placeholders:

Placeholder Replaced with
{date} Today's date (YYYY-MM-DD)
{env:APP_NAME} Value of the APP_NAME environment variable
{env:APP_ENV} Value of the APP_ENV environment variable

Exception Logging

The Error-Handling layer automatically logs every unhandled exception at the error level before rendering the response:

[2026-11-07T07:45:01.000000Z] error: function clause error %{exception: FunctionClauseError}

Custom reporters registered with Laravex.Foundation.Exceptions.reportable/2 run in addition to — not instead of — this automatic log entry.


Unsupported Drivers

Drivers not in the supported set (single, daily, monthly, stderr, errorlog, null) raise ArgumentError at runtime. Third-party integrations (Slack, syslog, etc.) are not built in; use a custom reporter in the Error-Handling layer instead.


Related

  • Error-Handling — exception reporters and automatic error logging
  • Configuration — loading logging config from environment variables

Clone this wiki locally