Configure Event Logging
Event logging emits structured, compliance-grade audit events for security-relevant activity in Astralis — authentication, authorization, admin actions, data access, and more. This guide walks through shaping that output to match your SIEM or log-ingestion pipeline's expected schema: setting shared defaults, customizing an individual event, renaming a reserved field's output key, formatting timestamp and severity values, and disabling events you don't need.
Before you start, you need the ability to edit your deployment's fides.toml (or set environment variables) and to restart the Astralis webserver. See the Event Logging reference for the full config schema and the complete event catalog.
Set the shared defaults for every event
Add a [logging.log_event_defaults] section to fides.toml. Every field you set here applies to all events, unless a specific event's own mapping overrides it. enabled defaults to false, so set it to true here to turn event logging on for your deployment:
[logging.log_event_defaults]
enabled = true
log_format = 'example_prefix: {serialized_fields}'
serialized_fields = { business_application_name = "MyDeployment" }log_format adds literal text around the JSON-encoded serialized_fields — it must contain only the literal {serialized_fields} placeholder, with no other braces (no JSON envelope, no {event.record.*} syntax, which belongs in serialized_fields values, not here). An invalid format string is rejected at startup.
Map an individual event to your schema
Pick an event from the event catalog — for example, authorization_denied — and add its own [logging.log_event_mapping.<event_name>] section:
[logging.log_event_mapping.authorization_denied]
serialized_fields = { event_name = "auth.authorization_denied", event_type = "AUTH", actor_id = "{event.record.extra.account_id}" }serialized_fields here merges with (and takes precedence over) the defaults set in the previous step. The {event.record.extra.account_id} template pulls the account ID the instrumented code passed when it emitted the event — check the catalog's Extra fields available column for what each event exposes. Repeat this section for every event you want to customize; any event without its own section just uses the defaults unmodified.
Rename a reserved field's output key
Five fields — event_outcome, event_severity, event_detail, event_start_utc_timestamp, and event_end_utc_timestamp — always reflect the real facts of the log call and can't be set directly. If your schema expects a different key name for one of them, add field_name_overrides to log_event_defaults (applies everywhere) or to a specific event's mapping (applies to that event only):
[logging.log_event_defaults]
field_name_overrides = { event_outcome = "outcome", event_severity = "severity" }This only renames the output key — the value is still populated by Astralis, never by configuration.
Format timestamp and severity values
If your pipeline expects timestamps or severity levels in a different form, set these in log_event_defaults. Both apply to every event and can't be set on a single event's mapping:
[logging.log_event_defaults]
timestamp_format = "%Y-%m-%dT%H:%M:%S.%fZ"
severity_names = { WARNING = "WARN", CRITICAL = "FATAL" }timestamp_formatis astrftimeformat for both timestamp fields, applied to the UTC time. Useepoch_millisorepoch_secondsfor numeric timestamps instead.severity_namesrenames the levels written toevent_severity. A level you don't map keeps its own name, so hereINFOandERRORare unchanged.
Like a key rename, these change only how the real value is written: the timestamps and the level an event is logged at still come from Astralis. See the reference for the values each one accepts.
Turn off events you don't need
Add enabled = false to an event's mapping to stop it from producing a log line entirely:
[logging.log_event_mapping.file_uploaded]
enabled = falseEvery other event keeps producing output; disabling one event has no effect on the rest of the catalog.
There's no single master switch to disable event logging entirely: a specific event's own enabled = true always overrides log_event_defaults.enabled = false. To turn off every event, make sure no [logging.log_event_mapping.<event_name>] block sets enabled = true.
Restart Astralis and verify the output
Configuration is read once at startup; restart the Astralis webserver (for example, restarting the container) so your changes are picked up.
Trigger the event you configured. For authorization_denied, send a request using an OAuth client that lacks the required scope. Then check your application's log output — the location set by destination in [logging], or your terminal/container logs by default — for a line matching your configuration. Applying every example above together produces:
example_prefix: {"actor_id": "fid_7c1e2d4a", "business_application_name": "MyDeployment", "event_detail": "Authorization denied: caller lacks required scope(s)", "event_end_utc_timestamp": "2026-01-01T12:00:00.123456Z", "event_name": "auth.authorization_denied", "event_start_utc_timestamp": "2026-01-01T12:00:00.098765Z", "event_type": "AUTH", "outcome": "FAILURE", "severity": "WARN"}If the line doesn't appear, confirm the event is enabled (directly or via the defaults) and that you restarted the webserver after editing fides.toml.
Related documentation
- Event Logging — the full config schema, reserved system fields, and event catalog
- Configuration variables — general Astralis configuration, including environment variable and TOML precedence
- Security Best Practices — broader deployment and operational security guidance