Configure logging

Set the level with --log-level {error,warn,info,debug,trace} or [log] level. -v selects debug and -vv selects trace:

peryx serve --log-level debug

At the default info level, request records include the HTTP method, path, status, and latency. Ecosystem guides describe their client request sequences.

Sinks

--log-sink or [log] sink selects one destination:

• stdout: terminal text, or JSON Lines with --log-format json
• file: a rotating file at --log-file <path>
• journald: the systemd journal on Linux
• syslog: the local syslog daemon on Unix

[log]
level = "info"
format = "json"
sink = "file"
file = "/var/log/peryx/peryx.log"

Startup rejects invalid combinations, including a file sink without a path.

Security events

Repository actions emit structured records on the peryx::security target. JSON output supports filtering by actor, action, target, or result.

peryx serve --log-format json --log-sink file --log-file /var/log/peryx/events.log

Each repository-action record sets security_event=true and event=index_action. Shared fields include action, result, actor, index, request_id, and user_agent. Ecosystem owners may add subject identifiers. Missing string and numeric values use empty strings and zero. Records exclude credentials, bearer tokens, Basic passwords, and URL secrets.

Server-role checks use event=authorization. Allowed records include user, scope, resource_kind, resource, result, and reason. Denied records omit the resource fields and use reason=no_grant or reason=storage_unavailable. They also omit the rejected URL and query parameters.

grep '"security_event":true' /var/log/peryx/events.log
jq 'select(.fields.security_event == true and .fields.result == "denied")' /var/log/peryx/events.log

Availability trace context

When distributed availability is configured, a replicated write carries W3C trace context in its operation envelope. The producer, follower apply, and content copy can join one trace. A replay retains the trace ID and operation identity but creates a new span ID for the apply work.

A sampled operation emits one availability operation event:

The event excludes payload bytes, metadata mutations, content references, credentials, and private paths. An operation without the sampled trace flag emits no event.

Use the trace ID or the source and serial pair to correlate an operation across nodes:

jq 'select(.fields.message == "availability operation" and .fields."operation.serial" == 7)' \
  /var/log/peryx/events.log

Related

• Logging configuration
• Metrics and monitoring