Configuration: logging

This page documents logging configuration for Ferron. It covers log signals, log formatters, available fields, and trace ID display in log output.

Log signals⁠#

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

Configure access logs per-host with the log directive. Configure application logs with 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 the file sink for the application log signal.

Directives⁠#

Access logging⁠#

Configure access logs with 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. Use the logformat-json module for this formatter.

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 you do not specify fields, the server emits all available access log fields.

text⁠#

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

By default, it uses the Enhanced Combined Log Format (ECLF). Ferron extends CLF 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:

You can access request headers via the %{Header-Name}i syntax. The header name is case-insensitive, and Ferron converts hyphens to underscores internally.

Application log formats⁠#

The error_format directive (in the observability { provider file ... } block or the error_log shorthand block) controls how the server formats application log messages. 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}}

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 the observability event system emits them.

Structured logs⁠#

Error log attributes⁠#

Structured error logs include contextual attributes to aid troubleshooting:

Ferron includes the client.address and server.address attributes in:

• Bad request (400) and timeout (408) logs: Ferron emits these logs when a request fails 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.

Variable interpolation in log filenames⁠#

The log and error_log directives support variable interpolation in file paths using the {{variable}} syntax. This enables use cases like per-host access logs or per-target error logs.

example.com {
    log "/var/log/ferron/{{accesslog.header_host}}/access.log"
}

Access log filename variables⁠#

When the server resolves an log filename, it uses the access log event fields as variables. All variable names are prefixed with accesslog..

Application log filename variables⁠#

When the server resolves an error_log filename, it uses the application log event fields as variables. All variable names are prefixed with log..

Common attribute keys used across the server include error.type, error.message, client.address, server.address, and upstream.address. The available attributes depend on the log event source.

Environment variables⁠#

You can also use environment variables in log filenames with the env. prefix:

example.com {
    log "/var/log/ferron/{{env.CUSTOMER_NAME}}/access.log"
}

Trace ID in console and file logs⁠#

Console and file loggers prefix log messages with [trace=<trace_id>] when a trace context exists. 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