Configuration: logging

This page documents logging configuration for Ferron, including log signals, log formatters, available fields, and how trace IDs appear in log output.

Log signals

Ferron emits two log signals: access logs and application logs.

Access logs are configured per-host via the log directive. Application logs are configured via the console_log and error_log directives (core-directives) or the observability block with provider console or provider file. There is no separate “error log” signal — the error_log directive is simply the file sink for the application log signal.

Directives

Access logging

Access logs are configured via log blocks inside host or global scopes:

example.com {
    log "access" {
        format json
        fields "method" "path" "status" "duration_secs"
    }
}

Access log fields

Each access log entry contains the following fields:

Log formatters

json

The JSON formatter serializes each access log entry as a single-line JSON object. Provided by the logformat-json module.

example.com {
    log "access" {
        format json
    }
}

Example output:

{"method":"GET","path":"/index.html","status":200,"duration_secs":0.012,"client_ip":"127.0.0.1","remote_ip":"127.0.0.1"}

Use the fields directive to limit which fields appear in the JSON output. If fields is not specified, all available access log fields are emitted.

text

The text formatter generates each access log entry as a plain text string using a configurable pattern. Provided by the logformat-text module.

By default, it uses the Combined Log Format (CLF), the same format used by Apache and Nginx.

Configuration example:

example.com {
    log "access" {
        format text
    }
}

Example output:

127.0.0.1 - frank [05/Apr/2026:14:32:01 +0200] "GET /index.html HTTP/1.1" 200 1234 "http://www.example.com/start.html" "Mozilla/5.0"

Pattern syntax

The access_pattern directive supports the following tokens:

Request headers are available via the %{Header-Name}i syntax. The header name is case-insensitive and hyphens are converted to underscores internally.

Application log formats

The error_format directive (in the observability { provider file ... } block or the error_log shorthand block) controls how application log messages are formatted. It supports the same formatters as access logs: text (default) and json.

example.com {
    error_log /var/log/ferron/error.log {
        error_format json
    }
}

The text formatter produces human-readable lines:

[2026-04-05 14:32:01.123 INFO] Request processed successfully
[2026-04-05 14:32:01.124 DEBUG] Cache miss for key: user:123
[2026-04-05 14:32:01.125 ERROR] [trace=abc123def456] Upstream connection refused

The json formatter produces structured JSON records:

{"timestamp":1781327817042,"summary":"Request processed successfully","level":"INFO","target":"ferron::http","attributes":{},"trace_context":null}
{"timestamp":1781327818364,"summary":"Upstream connection refused","level":"ERROR","target":"ferron::proxy","attributes":{"upstream":"http://10.0.0.1:3000"},"trace_context":{"trace_id":"abc123def456","span_id":"789012345678","sampled":true}}

Log levels

The log_level directive (in the observability block or via console_log/error_log aliases) controls the minimum severity level for application logs:

Configuration example:

example.com {
    observability {
        provider console
        log_level debug
    }
}

Console vs file vs OTLP

The format directive (json/text) applies to file and console sinks. OTLP also a different mechanism:

Trace ID in console and file logs

Console and file loggers prefix log messages with [trace=<trace_id>] when a trace context is available. This enables grep-based filtering by trace ID without requiring an OTLP backend.

Example log output:

[2026-04-05 14:32:01.123 INFO] [trace=abc123def456] Request processed successfully
[2026-04-05 14:32:01.124 DEBUG] [trace=abc123def456] Cache miss for key: user:123