Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Logging

View as Markdownllms.txt

A log is your app’s diary: short messages it writes while it runs (“payment failed for invoice 42”), so you can find out later what happened. Strutvane’s logging is built into the framework and works like Laravel’s: you write Log.info('…') in your code, and channels, chosen in .env, decide where each message goes.

Log a message from anywhere in your app:

app/http/controllers/post.controller.ts
import { Log } from '@strutvane/framework'
Log.info('Post published', { postId: 42 })

What you’ll see: a new line at the end of today’s file, storage/logs/strutvane-2026-11-15.log:

[2026-11-15 10:22:01.123] local.INFO: Post published {"postId":42,"requestId":"01JD7Q6Y9X3V2K8M4N5P6R7S8T"}

Read it as: the time, the environment (local), the level (INFO), your message, then the context (the extra data) as JSON. The request id was added for you. Nothing to configure: a new app logs to a daily file out of the box.

Every message has a level: how serious it is. These are the eight levels from RFC 5424, the same as Laravel’s, from most to least serious:

Level Use it when… Example
emergency the whole app is unusable the database is gone
alert someone must act now the disk is full
critical a key part is broken payments are failing
error something failed, but the app keeps going one email couldn’t be sent
warning something odd that isn’t an error yet an API answered slowly
notice normal, but worth noticing a user changed their email
info normal events a post was published
debug details for developers the SQL a query ran

LOG_LEVEL sets the least serious level that’s still written. With LOG_LEVEL=warning, warning and everything above it is kept, and notice, info and debug are dropped. The default is debug in local development and info everywhere else.

The 0.1 names still work as aliases: warn means warning, fatal means critical, trace means debug.

app/http/controllers/post.controller.ts
import { Log } from '@strutvane/framework'
Log.debug('Loading posts', { page: 2 })
Log.info('Post published', { postId: 42 })
Log.warning('Slug was changed to stay unique', { from: 'hello', to: 'hello-k3f9' })
Log.error('Could not send the "post published" email', { postId: 42 })

What you’ll see: four lines in the log file, each with its level in capitals (DEBUG, INFO, WARNING, ERROR).

Always put values in the context object, never inside the message text. Log.info('Post published', { postId: 42 }) can be searched and filtered; Log.info('Post 42 published') can’t, and a value pasted into the text escapes redaction.

Inside a request, every message automatically gets:

  • requestId: one id per request, also sent back in the response, so a user’s error report leads straight to its log lines;
  • the signed-in user’s id;
  • the current team’s id (the tenant), when teams are on.
app/http/controllers/invoice.controller.ts
import { Log } from '@strutvane/framework'
// For the rest of THIS request: every message below also carries orderId.
Log.withContext({ orderId: 'ord_123' })
Log.info('Charging the card') // context: { orderId: 'ord_123', requestId: ... }
// For every channel, from now on (for example in a provider's boot()).
Log.shareContext({ region: 'eu-west' })
// Drop the context you added (the automatic request id stays).
Log.withoutContext()

What you’ll see: Charging the card {"orderId":"ord_123","region":"eu-west","requestId":"01JD7Q6Y9X3V2K8M4N5P6R7S8T"}, once shareContext has run.

app/jobs/send-invoice.ts
import { logger, report } from '@strutvane/framework'
try {
await sendInvoice(invoice)
} catch (error) {
report(error) // logs it at "error", with the stack trace, and carries on
}
logger().info('Invoice job finished') // the same as Log.info(...)

report(error) is Laravel’s report(): it writes the error to the log the same way the error page would, without stopping your code.

A channel is one destination with its settings. LOG_CHANNEL picks the default channel; config/logging.ts defines the channels. Every driver:

Driver Where messages go Good for
single one file, storage/logs/strutvane.log small apps, quick experiments
daily one file per day, storage/logs/strutvane-2026-11-15.log, old days deleted after LOG_DAILY_DAYS most apps (the default, through stack)
stack several channels at once, listed in LOG_STACK “a file and Slack”
stderr / stdout the process’s output, where containers and hosting platforms collect it Docker images, Kubernetes, PaaS
slack a Slack channel through a webhook, for critical and above waking someone up
null nowhere (messages are discarded) silencing a channel in tests
custom a function you write that returns a transport anything else

The commonest change needs no code. A new app logs through stack, which writes to daily:

.env
LOG_CHANNEL=stack
LOG_STACK=daily
LOG_LEVEL=debug
LOG_DAILY_DAYS=14
LOG_FORMAT=line
LOG_MAX_FILE_SIZE=100mb

To also send serious problems to Slack, add slack to the stack and the webhook:

.env
LOG_STACK=daily,slack
LOG_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url

What you’ll see: every message still lands in the daily file, and critical, alert and emergency messages also arrive in Slack.

Key What it does Default
LOG_CHANNEL The default channel: single, daily, stack, stderr, stdout, slack, null, or any channel you define. stack
LOG_STACK The channels stack writes to, comma-separated. daily
LOG_LEVEL The least serious level that’s written. debug in local, info otherwise
LOG_DAILY_DAYS Days of daily files to keep. 14
LOG_FORMAT line (readable) or json (one JSON object per line). line
LOG_MAX_FILE_SIZE Size at which a file is closed and a new part starts. 100mb
LOG_PATH The folder for log files. storage/logs
LOG_SLACK_WEBHOOK_URL The Slack webhook for slack. Treat it as a secret. not set
LOG_DEPRECATIONS_CHANNEL Where deprecation warnings go. null (discarded)

config/logging.ts, and your own payments channel

Section titled “config/logging.ts, and your own payments channel”

Channels are defined in config/logging.ts. You can add your own and give them any name. Here, payments get their own file, kept for 90 days:

config/logging.ts
import { defineConfig } from '@strutvane/framework'
export default defineConfig((env) => ({
default: env.string('LOG_CHANNEL', 'stack'),
channels: {
stack: { driver: 'stack', channels: env.string('LOG_STACK', 'daily').split(',') },
single: { driver: 'single', path: 'storage/logs/strutvane.log' },
daily: { driver: 'daily', path: 'storage/logs/strutvane.log', days: env.integer('LOG_DAILY_DAYS', 14) },
stderr: { driver: 'stderr' },
slack: { driver: 'slack', url: env.optional('LOG_SLACK_WEBHOOK_URL'), level: 'critical' },
null: { driver: 'null' },
// Your own channel: one daily file only for payments.
payments: { driver: 'daily', path: 'storage/logs/payments.log', days: 90, level: 'info' },
},
}))

Use it by name:

app/services/payments.ts
import { Log } from '@strutvane/framework'
Log.channel('payments').warning('Card declined', { invoiceId: 42, reason: 'insufficient_funds' })

What you’ll see: the line in storage/logs/payments-2026-11-15.log, and not in the main file.

Several channels for one message, or a channel made on the spot

Section titled “Several channels for one message, or a channel made on the spot”
app/services/payments.ts
import { Log } from '@strutvane/framework'
// This one message goes to the daily file AND to Slack.
Log.stack(['daily', 'slack']).critical('Payment provider is down', { provider: 'stripe' })
// A channel built right here, without touching config/logging.ts.
Log.build({ driver: 'single', path: 'storage/logs/import-2026-11-15.log' }).info('Import started', { rows: 1200 })

LOG_FORMAT=line (the default) is readable in any text editor, like Laravel’s:

[2026-11-15 10:22:01.123] local.ERROR: Payment failed {"invoice":42,"requestId":"…"}

LOG_FORMAT=json writes one JSON object per line (often called NDJSON), which log shippers such as Loki, Datadog or CloudWatch read directly:

{"time":"2026-11-15T10:22:01.123Z","level":"error","env":"local","message":"Payment failed","context":{"invoice":42,"requestId":"…"}}

(The JSON field names are not final.) In both formats, newlines and terminal colour codes inside values are escaped, so one message is always exactly one line. Someone can’t fake a log line by putting a newline in their name.

File Written by
storage/logs/strutvane.log the single channel
storage/logs/strutvane-2026-11-15.log the daily channel, main process, on 15 November
storage/logs/strutvane-2026-11-15.worker-2.log the same day, from another process (a queue worker, the scheduler, a cluster worker)
storage/logs/strutvane-2026-11-15-2.log the second part of the day, after the first reached LOG_MAX_FILE_SIZE

The rules behind those names:

  • The main process writes the plain name; every other process writes its own file.
  • When a file reaches LOG_MAX_FILE_SIZE, a new part starts. Files are never renamed, so a program reading a file never loses its place.
  • Retention (LOG_DAILY_DAYS) deletes whole days, never half a day.
  • log:tail and the log viewer merge all the files of a day by timestamp, so you still read one timeline.

Why one file per process? Laravel lets every process append to the same file. The 0.1 measurements (spike 09) found that with several writers on one file, the size cap broke in 24 to 25 files out of every 28 to 30: files grew past their limit. Separate files keep the guarantee, and the names stay close to Laravel’s.

node strut log:tail shows new messages as they’re written, from every process, merged in time order. Like Laravel Pail, you can narrow it to some levels or one channel.

Terminal window
node strut log:tail

What you’ll see (something like this):

[2026-11-15 10:22:01.123] local.INFO: Post published {"postId":42}
[2026-11-15 10:22:03.981] local.ERROR: Could not send the "post published" email {"postId":42}

Press Ctrl+C to stop.

The other log commands:

Command What it does
node strut log:tail Follow new messages live; filter by level and by channel
node strut log:list List the log files, with their size and dates
node strut log:clear Delete the local log files
node strut log:clear --days=7 Delete only files older than 7 days
  • Without Docker, files are written to storage/logs/ in your project and log:tail reads them directly.
  • With Docker, your app runs in the app container, but your project folder is shared with it, so the files still appear in storage/logs/ on your computer and you can open them in your editor. node strut log:tail typed on your computer is forwarded into the container like every other command. See Docker.

On Windows and macOS, storage/logs/ is a normal folder you can open in Explorer or Finder. storage/ is git-ignored, so logs are never committed.

In a container, write to the process output and let the platform collect it:

.env.production
LOG_CHANNEL=stderr
LOG_FORMAT=json

The production Dockerfile the installer can write (question “Where will you deploy?”, answer “Docker image”) already sets these two values. On a plain server (a VPS), keep daily, and make sure LOG_DAILY_DAYS fits your disk and your data-retention rules.

You can’t switch these off, on any channel:

  • Redaction is always on. Values under keys that look secret (passwords, tokens, API keys, cookies, authorization headers) are replaced before anything is written. The same matcher hides secret columns from the generated API and screens.
  • Request bodies are not logged by default.
  • Slack is rate-limited and goes through the framework’s HTTP client, which refuses private and internal network addresses, so a crafted webhook URL can’t reach your internal services.
app/http/controllers/session.controller.ts
import { Log } from '@strutvane/framework'
Log.info('Login attempt', { email: 'asha@example.com', password: 'hunter2hunter2' })

What you’ll see:

[2026-11-15 10:30:12.044] local.INFO: Login attempt {"email":"asha@example.com","password":"[REDACTED]","requestId":"01JD7QA1B2C3D4E5F6G7H8J9K0"}

(The exact redaction marker may differ.) Redaction is a safety net, not permission: don’t log secrets on purpose.

Seeing logs in the browser: @strutvane/log-viewer

Section titled “Seeing logs in the browser: @strutvane/log-viewer”

The optional @strutvane/log-viewer package adds a screen at /_strutvane/logs to tail, search and filter your logs. It reads both formats and merges the per-process files. It’s pre-selected in the installer’s “Extra features” question, so most new apps have it. To add it later:

Terminal window
node strut install:log-viewer

The screen is a developer tool behind sign-in and a permission; logging itself works without it.

LOG_LEVEL=info

Why: LOG_LEVEL is the least serious level that’s written, and debug is below info. Outside local development, the default is info. Fix: lower it while you investigate, then put it back:

.env
LOG_LEVEL=debug

I used console.log() and the message isn’t in the log file

Section titled “I used console.log() and the message isn’t in the log file”

Why: console.log writes to the terminal only. It skips channels, levels, context and redaction, so it can also leak a secret. Fix: use the logger:

import { Log } from '@strutvane/framework'
Log.info('Imported posts', { count: 120 })

Two processes write to one file and the lines are mixed up

Section titled “Two processes write to one file and the lines are mixed up”

Why: a channel you defined points every process at one fixed path, or another tool appends to Strutvane’s file. Several writers on one file break the size cap and interleave lines. Fix: let each process keep its own file (the default), and read them together with node strut log:tail or the log viewer. Point other tools at their own file:

config/logging.ts
// in channels:
reports: { driver: 'daily', path: 'storage/logs/reports.log', days: 30 },

Why: daily deletes files older than LOG_DAILY_DAYS (14 by default). Fix: keep them longer, or ship them elsewhere before they go:

.env
LOG_DAILY_DAYS=90

Why: the slack channel only sends critical and above, it’s rate-limited (a burst of errors doesn’t all reach Slack), and it does nothing unless slack is in LOG_STACK or you call it by name. Fix: add it to the stack, set the webhook, and test with a critical message:

.env
LOG_STACK=daily,slack
LOG_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url
import { Log } from '@strutvane/framework'
Log.critical('Testing the Slack channel')

Why: LOG_FORMAT=json is set (often copied from a production setup). It’s made for log shippers, not for reading. Fix: use the readable format locally:

.env
LOG_FORMAT=line