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 Enhanced Combined Log Format (ECLF; Ferron’s extended version of CLF), which extends Combined Log Format with Host header and trace ID fields.

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" "www.example.com" "abc123def456"

Common format string examples

You can customize the text log format using the access_pattern directive. Here are common format strings:

Enhanced Combined Log Format (Ferron default):

%client_ip - %auth_user [%t] "%method %path_and_query %version" %status %content_length "%{Referer}i" "%{User-Agent}i" "%{Host}i" "%trace_id"

Combined Log Format (Apache/Nginx standard):

%client_ip - %auth_user [%t] "%method %path_and_query %version" %status %content_length "%{Referer}i" "%{User-Agent}i"

Common Log Format (CLF):

%client_ip - %auth_user [%t] "%method %path_and_query %version" %status %content_length

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:

Admin API structured logs

The admin API emits structured log events through the observability pipeline for important operational events:

Reload log events

The metrics-reload module emits application log events during configuration reloads:

These events carry the ferron-metrics-reload target and are emitted through the observability event system.

Structured logs

Error log attributes

Structured error logs include contextual attributes to aid troubleshooting:

The client.address and server.address attributes are included in:

• Bad request (400) and timeout (408) logs — emitted when a request is rejected before handler execution.
• TLS handshake failure logs — emitted when a TLS connection fails to establish or negotiate a protocol.
• TCP connection error logs — emitted when an HTTP/1.x or HTTP/2 connection encounters a transport-level error.
• Request validation error logs — emitted for invalid Host headers, malformed URLs, CONNECT path errors, and URL sanitization failures.

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