Logs

This page describes the operator-visible logging behavior of a self-hosted Lombok deployment: what the API logs, where those logs go, how to control verbosity, and how to read them from the container runtime.

It is intentionally narrow. See What this page does not cover below.

Where logs go

The Lombok API writes its logs to the container’s standard output and error streams. It does not write to a log file inside the container and does not manage log rotation itself.

Because everything goes to the standard streams, you retrieve logs the same way you would for any container — through your container runtime, which captures and stores them according to its own logging driver and configuration.

On startup the API emits a line confirming it is up, for example:

API started and listening on port 3000

The API listens on port 3000 inside the container as an internal upstream behind the bundled Nginx; operators normally connect through the container’s published or proxied HTTP port instead.

Retrieving logs

Use your container runtime’s standard log commands. For a Docker or Docker Compose deployment:

# Follow live logs for the running container
docker logs -f <container-name>

# Or, when using Docker Compose, by service name
docker compose logs -f <service-name>

Replace <container-name> or <service-name> with the name from your compose file or docker ps. Standard flags such as --tail, --since, and --timestamps work as usual.

If you need logs to persist beyond the container lifecycle or be shipped elsewhere, that is handled by your container runtime’s logging driver, not by Lombok.

Log format

API log lines are human-readable text, not JSON. Each line is composed of a timestamp, the log level, the originating context, and the message, for example:

06/10/2026, 12:00:00 PM   LOG [Bootstrap] API started and listening on port 3000

ANSI colors and timestamps are enabled. Do not build parsing or alerting around an assumption that API logs are structured JSON — the API does not emit JSON by default.

[!NOTE] The separate docker-bridge component does emit JSON. See Docker bridge logs. Keep the two log surfaces distinct when configuring collection.

Controlling verbosity with `LOG_LEVEL`

Verbosity is controlled by the LOG_LEVEL environment variable. It sets the minimum level to emit: the chosen level and every more-severe level are enabled, while less-severe levels are suppressed.

Levels, ordered from least to most severe:

verbose  →  debug  →  log  →  warn  →  error  →  fatal

Recognized values are case-insensitive and surrounding whitespace is ignored.

`LOG_LEVEL`	Levels emitted
`verbose`	verbose, debug, log, warn, error, fatal
`debug`	debug, log, warn, error, fatal
`log`	log, warn, error, fatal (default)
`warn`	warn, error, fatal
`error`	error, fatal
`fatal`	fatal

Default and fallback behavior

If LOG_LEVEL is unset, the API uses log, which emits log, warn, error, and fatal.
If LOG_LEVEL is empty or set to an unrecognized value, the API falls back to the same default set (log, warn, error, fatal) rather than failing to start.

That means values like info or trace are not valid API log levels and are treated as the default behavior.

A note on the bundled compose files

The development and demo compose files in the repository set LOG_LEVEL=DEBUG. That is a convenience for development or demo use and is not the built-in default. For a real self-hosted deployment, decide the level explicitly.

A typical compose snippet looks like:

services:
  app:
    environment:
      LOG_LEVEL: log

Docker bridge logs (separate surface)

Lombok includes a separate docker-bridge process that is started on demand when Docker hosts are configured. It is a distinct logging surface from the main API:

It emits JSON log lines (one JSON object per line, with fields such as level, ts, and msg), unlike the API’s plain-text output.
It uses its own level scale: debug, info, warn, error.
Its level is derived from the same LOG_LEVEL environment variable, defaulting to info when the value is not one of the bridge’s four levels.

Because the bridge runs inside the same container/runtime, its JSON lines may appear interleaved with the API’s text lines in the same stream. If you ingest logs downstream, account for the two different formats.

What this page does not cover

To keep this page accurate and focused on operator-visible logging, it does not cover:

metrics, tracing, alerting, dashboards, or general observability tooling
log retention, rotation, aggregation, or shipping
in-product or admin-facing application logs and audit trails
worker or sandbox execution output controlled by separate settings