Skip to content
Platform & Configuration
Event Logging
Reference

Event Logging Reference

Event logging emits a structured, compliance-grade audit trail for security-relevant activity: authentication, authorization, admin and user/permission management, token lifecycle, encryption key use, data import/export (including report downloads), file uploads, access to confidential data, integration connectivity failures, and application errors. Each event is a single log line shaped entirely by your own configuration, so it can be mapped directly into your SIEM or log-ingestion pipeline's expected schema without any code changes.

Event logging is a core Astralis capability, always active — there is no on/off switch for the feature as a whole. What you configure is what a given event's output line looks like, and whether that event is enabled at all.

For a step-by-step walkthrough, see Configure Event Logging. This page is the full reference.

Enabling and shaping events

Two TOML sections under [logging] control event output:

  • [logging.log_event_defaults] — the shared shape applied to every event, unless a specific event overrides it.
  • [logging.log_event_mapping.<event_name>] — one optional block per event (see the event catalog below for the valid <event_name> values), overriding the defaults for that event only. An event with no block here just uses the defaults unmodified.
NameTypeDefaultDescription
enabledbooleanfalseWhether this event produces a log line at all. Defaults to false in log_event_defaults — a new deployment emits nothing until you opt in. Settable per-event too; a per-event value always wins over the default, including a per-event true overriding log_event_defaults.enabled = false — so setting enabled = false in log_event_defaults alone does not guarantee no events fire. An event left unset inherits the default.
log_formatstring"{serialized_fields}"The literal text wrapper around the event's serialized fields. Must contain only the {serialized_fields} placeholder — no other braces of any kind (no JSON envelope built from extra {/}, no {event.record.*} syntax, which is valid only inside serialized_fields values, not here). An invalid format string is rejected at startup, not at emit time.
serialized_fieldstable{}The output field map for this event: each key is an output field name, each value is either a literal string or a template referencing data from the log call. Merges key-by-key with the defaults; a per-event key wins on collision. This is a pure union — there's no way for a specific event's mapping to remove or suppress a field the defaults set for every other event.
field_name_overridestable{}Renames the output key of a reserved system field to a non-empty name. Merges key-by-key with the defaults, same precedence as serialized_fields.
timestamp_formatstringISO-8601log_event_defaults only. A strftime (opens in a new tab) format for both timestamp fields, applied to the UTC time, for example %Y-%m-%dT%H:%M:%S.%fZ, or epoch_millis / epoch_seconds for an integer since the Unix epoch. Applies to every event; setting it in a log_event_mapping block is rejected at startup. A format with no directive (no %Y, %H, and so on) is also rejected, since every event would get the same timestamp.
severity_namestable{}log_event_defaults only. Renames the levels written to event_severity, for example { WARNING = "WARN", CRITICAL = "FATAL" }. Keys are DEBUG, INFO, WARNING, ERROR or CRITICAL; a level you don't map keeps its own name. Only the label changes, not the level the event is logged at. Rejected at startup if a key isn't one of those levels, a name is empty, or two levels would end up with the same name.

log_event_mapping is keyed by event name as a plain TOML table, so each event needs its own [logging.log_event_mapping.<event_name>] header — it cannot be written as a single inline table of tables.

Both tables reject unknown keys outright — a typo (serialised_fields, feild_name_overrides) raises a configuration error at startup rather than being silently dropped.

Event logging is not gated by log_pii. The identifiers a deployment typically wants in these events (an internal user or client ID, a resource ID) are pseudonymous, not raw PII — but each deployment is responsible for keeping a raw identity value (an email address, a name) out of serialized_fields.

Setting these via environment variables

Every field in both tables is also settable via environment variable, following Astralis's standard nested-env-var pattern (see Configuration variables): FIDES__LOGGING__LOG_EVENT_DEFAULTS__<FIELD> for log_event_defaults, and FIDES__LOGGING__LOG_EVENT_MAPPING__<event_name>__<FIELD> for a specific event's mapping —

FIDES__LOGGING__LOG_EVENT_DEFAULTS__ENABLED=true
FIDES__LOGGING__LOG_EVENT_MAPPING__user_added__ENABLED=true
⚠️

Environment variable names are matched case-insensitively, so the <event_name> segment is lowercased before Astralis reads it: FIDES__LOGGING__LOG_EVENT_MAPPING__MyEvent__ENABLED=true sets the mapping key myevent, not MyEvent. Every name in the event catalog is already lowercase, so this only matters if you mistype the case in an env var — a key set this way in fides.toml (TOML, not env) is unaffected.

Reserved system fields

Five fields always reflect the actual, real-time facts of the log call — the point of a compliance log is that these can never be authored by configuration:

FieldAlways reflects
event_start_utc_timestampSee timestamps below — not always identical to the end timestamp.
event_end_utc_timestampThe instant the event was logged.
event_severityThe real log level (INFO, WARNING, ERROR, etc.) the event was logged at, under the name set in severity_names if you've mapped it.
event_detailThe real message passed to the logging call.
event_outcomeThe real SUCCESS/FAILURE outcome the instrumented code reported.

These five names cannot appear as a key in serialized_fields — Astralis rejects the configuration at startup if one does. The only thing configurable about a reserved field is its output key, via field_name_overrides:

[logging.log_event_defaults]
field_name_overrides = { event_outcome = "outcome", event_severity = "severity" }

This renames the reserved fields' keys in the emitted JSON, but their values are still populated by Astralis, never by config. Conversely, field_name_overrides only accepts these five names — every other field is already named by its own key in serialized_fields, so there's nothing else to rename.

Two reserved fields can't be renamed to the same output key, and a rename target can't collide with an existing serialized_fields key — either would silently overwrite one value with the other in the emitted line. Astralis rejects the configuration at startup if either happens, including when the collision only appears after merging log_event_defaults with a specific event's mapping (for example, a rename set in the defaults colliding with a serialized_fields key introduced by one event's own override).

Timestamps

event_end_utc_timestamp is always the instant the event was logged. event_start_utc_timestamp is usually earlier, reflecting when the underlying operation actually began:

  • For an event emitted while handling an API request, it's the time the request was received — so a slow authentication check or a long-running action shows a real elapsed span between the two timestamps, not two identical values.
  • For an event emitted outside of any request (a background/worker task, for example), the two timestamps are identical, since there's no earlier "start" to report.

Both are always UTC. By default they're ISO-8601 (2026-01-01T12:00:00.123456+00:00). Set timestamp_format in log_event_defaults to render them in another shape your pipeline expects:

[logging.log_event_defaults]
timestamp_format = "%Y-%m-%dT%H:%M:%S.%fZ"

For numeric timestamps, set timestamp_format to epoch_millis or epoch_seconds. Both fields are then written as JSON integers rather than strings, for example "event_end_utc_timestamp": 1767268800123.

Referencing call-site data

The instrumented code at each event's call site passes along context — for example, an authorization-denial event includes which account was denied and what scopes were required. This data is only included in the output if your serialized_fields configuration references it, using an {event.record.extra.<key>} template:

[logging.log_event_mapping.authorization_denied]
serialized_fields = { actor_id = "{event.record.extra.account_id}", required_scopes = "{event.record.extra.required_scopes}" }

A template referencing a key the call site didn't pass resolves to the literal string "unknown" rather than raising or omitting the field. See each event's Extra fields available column in the event catalog for what's available to reference.

Every event emitted while handling an API request can also reference two more keys, whichever event it is:

  • path — the request path, for example /api/v1/user.
  • request_id — the ID Astralis assigns the request, which also appears on the request's other log lines.

account_id is always an identifier Astralis has resolved — a user ID, or the OAuth client's ID for a service account or the root client — never a value the caller typed. account_type is one of ADMIN (the root client), USER, SERVICEACCOUNT, or unknown when no caller could be resolved.

Event catalog

Eventevent_typeFires whenExtra fields available
user_authentication_requestAUTHEvery sign-in attempt: password login (the login page and the OAuth password grant), the OAuth client-credentials grant, SSO sign-in, and the MCP gateway login form. SUCCESS when the caller authenticates; FAILURE (logged at WARNING) for every rejection — bad or missing credentials, a disabled account, password login blocked because SSO is configured, a failed SSO callback, or a rejected MCP gateway login.grant_type (password, client_credentials, sso, or authorization_code for the MCP gateway); account_id, account_type once the caller resolves to a known user or client, otherwise unknown — never the typed username or the SSO provider's email (a failed login for the configured root username is recorded against the root client); oidc_provider (SSO); mcp_client_id (MCP gateway); reason (SSO and MCP gateway failures); target_resource_id (the disabled user, on a client-credentials rejection for a disabled account)
authentication_failedAUTHA presented access token is rejected (unparseable, expired, missing a claim, naming an unknown client, or issued before the user's password was reset), the MCP gateway refuses a bearer token (revoked, or older than its acceptance window), or — as a catch-all — any other request receives a 401 Unauthorized. Logged at WARNING, at most once per request.reason and client_id (the client the token names) from direct instrumentation; account_id, account_type once the token's client resolves (always present on the catch-all, as unknown when no caller was authenticated)
authorization_deniedAUTHAn authenticated caller is denied for lacking a required scope, tries to give an OAuth client scopes it doesn't hold itself, tries to change or test a secrets manager its organization can see but doesn't own, or — as a catch-all — any other request receives a 403 Forbidden. Logged at WARNING, at most once per request.account_id, account_type; required_scopes (scope check) or attempted_scopes (scope assignment) from direct instrumentation; for a refused secrets manager operation, reason (organization_mismatch), target_resource_type (secrets_manager) and target_resource_id (the manager's ID, absent when the refused request was a create)
admin_perform_actionAUTH, IAMA caller holding the user:read scope lists user accounts. Callers that can only read their own account don't produce this event.account_id, account_type
user_addedIAMA new user account is created.account_id, account_type, target_resource_id
user_deletedIAMA user account is deleted.account_id, account_type, target_resource_id
permissions_changedIAMAn OAuth client is created (even with no scopes), or an existing client's directly assigned scopes change. Saving a client's scopes unchanged produces nothing.account_id, account_type, target_resource_id (the client); assigned_scopes on creation (empty when none), or added_scopes and removed_scopes on a change — each a comma-separated list
credential_source_changedIAMA secrets manager is created, updated or deleted, or an integration's credentials move onto, between or off secrets managers: linked to a manager, moved to another secret within the same manager, moved to another manager, or switched back to manual entry. A save that changes nothing produces nothing. Logged only after the change is saved; a refused or failed change produces nothing. A Jira ticket integration that follows its source integration onto or off a manager isn't logged yet.account_id, account_type, action (create, update or delete for a manager; link, reference_changed, repoint or unlink for an integration); for a manager, target_resource_id (the manager's ID, never its key), target_resource_type (secrets_manager), manager_type and, on an update, changed_fields (a comma-separated list of name, details, secrets, never their values); for an integration, target_resource_id (the connection key), target_resource_type (the integration type), secrets_manager_id and previous_secrets_manager_id (absent when there is none), and secrets_wiped (true when the change removed credentials the integration had stored, such as a hand-entered key on link or a cached access token on unlink) — never the secret reference
token_issuedAUTHAn access token is issued: immediately after every successful sign-in user_authentication_request, and when the MCP gateway exchanges an authorization code or a refresh token.account_id, account_type, target_resource_id (the client the token was issued to), grant_type (as above, or refresh_token); oidc_provider (SSO); mcp_client_id (MCP gateway)
token_invalidatedAUTHAn OAuth client is deleted.account_id, account_type, target_resource_id
token_rotatedAUTHAn OAuth client's secret is rotated, or a secrets manager's ExternalId is rotated. Never includes the old or new value.account_id, account_type, target_resource_id (the client, or the manager's ID); target_resource_type (secrets_manager), manager_type and dependent_count (how many integrations stop working until the new ExternalId is added to the role's trust policy) for an ExternalId rotation
encryption_key_usedSYS EVENTAn encryption key is generated, used to encrypt/decrypt a value, or the application's own key-encryption key is used to unwrap a data-encryption key (including on failure — a missing or mismatched key).target_resource_id (a one-way fingerprint of the key, never the key itself), target_resource_type, account_id+account_type where applicable
data_importedSYS EVENTA bulk privacy-preference import job finishes (SUCCESS, or FAILURE at ERROR if it fails), or historical privacy requests are bulk-imported. The job is logged when it finishes, not when it's queued, and attributed to whoever started it.account_id, account_type, target_resource_type; target_resource_id (the job ID) and row_count (preference import), or row_count and failed_count (privacy request import)
data_exportedSYS EVENTA bulk privacy-preference export job finishes (SUCCESS, or FAILURE at ERROR if it fails; logged when it finishes, not when it's queued), or a report is downloaded: the privacy requests CSV, the consent report, the data map (CSV, XLSX or JSON), the asset report, data purposes, classification workbench results, manual task fields, or a DROP cycle file, or an access package is downloaded or exported. A download is logged once the file has been built or fully sent, so a download that fails partway isn't logged. Records what was exported and how much — never the rows or the filters used.account_id, account_type, target_resource_type (the job type or report: privacy_request_report, consent_report, datamap_report, datamap, asset_report, data_purposes, classification_workbench_results, manual_fields, drop_cycle_file, access_package); target_resource_id (the job ID) and row_count (preference export), or export_format, row_count where known, and target_resource_id when the report comes from one resource: the workbench run ID, the access package's privacy request ID, or the DROP file ID along with cycle_id and file_variant (downloaded or uploaded) (report downloads)
file_uploadedSYS EVENTA file is uploaded to a privacy request attachment — SUCCESS when it's stored, FAILURE when it's rejected (file uploads turned off, too large, a disallowed file type, a failed virus scan, or the scanner or storage being unavailable). An upload rejected because file uploads are turned off is a 403, so it also produces the catch-all authorization_denied. Unauthenticated (data-subject-facing), so no account_id.target_resource_id (on success), target_resource_type
confidential_data_accessSYS EVENTPrivacy preferences are read for a data subject — SUCCESS when they're returned, FAILURE when the read is rejected. target_resource_id is a list of notice history IDs, never the subject's identity value.account_id, account_type, target_resource_id (on success), target_resource_type; on success, the shape of the query but never its values: identity_types (the kinds of identity filtered on, such as email), include_latest, include_historical, page_size
confidential_data_changeSYS EVENTPrivacy preferences are saved for a data subject — SUCCESS when they're saved, FAILURE when the save is rejected or fails. A save queued with async=true is logged when the background save runs, attributed to whoever queued it. Same identity-safety guarantee as above.account_id, account_type, target_resource_id (on success), target_resource_type
input_validation_errorERRORA request fails schema validation.none — folded into event_detail
output_validation_errorERRORA response fails schema validation before being sent.none — folded into event_detail
runtime_errorERRORA resource fails to be created due to a database error, or — as a catch-all — any request receives a 500 Internal Server Error. Logged at ERROR.target_resource_id, target_resource_type (direct instrumentation); account_id, account_type (catch-all)
connectivity_errorERRORAstralis can't reach an integration: a connection test fails (for any integration type, whether a user ran it or a discovery monitor checked it before running), or a privacy request step runs out of retries because its integration is unreachable. Also logged when a secrets manager fails its Test or a Verify all check, except when Astralis's own cloud identity failed and the manager was never contacted. Logged at WARNING.target_resource_id (the integration's connection key), target_resource_type (the integration type), reason (credentials could not be resolved, target unreachable, target rejected the request, or connection test failed — never the underlying error text); privacy_request_id and collection (privacy request steps only). For a secrets manager: target_resource_id (the manager's ID), target_resource_type (secrets_manager), manager_type, reason (secrets manager test failed) and error_class, the same failure class the manager's health shows

runtime_error may be logged twice for the same underlying failure — once with rich detail from the specific code path that caught it, once generically from the catch-all safety net that fires on any 500 response. This is intentional: the safety net exists to catch failures that aren't individually instrumented, and doesn't attempt to suppress overlap with sites that are.

Output format

By default, an event's serialized_fields are JSON-encoded and written as the log line's message — no log_format wrapper is applied unless configured. Set log_format to add literal text before or after that JSON, as a prefix your log-ingestion pipeline can key on:

[logging.log_event_defaults]
log_format = 'example_prefix: {serialized_fields}'

log_format cannot introduce its own braces to wrap the JSON in a larger structure (a JSON envelope, for example) — the {serialized_fields} placeholder is the only brace-delimited syntax it accepts. See the field reference above.

Event log lines share the same output destination as all other Astralis logging (destination, colorize, serialization under [logging] — see Configuration), but are written independent of the configured level: a disabled event produces nothing, and an enabled event is always written regardless of the minimum log level.

Example configuration

[logging.log_event_defaults]
enabled = true
log_format = 'example_prefix: {serialized_fields}'
serialized_fields = { business_application_name = "MyDeployment" }
field_name_overrides = { event_outcome = "outcome", event_severity = "severity" }
 
[logging.log_event_mapping.user_authentication_request]
serialized_fields = { event_name = "auth.user_authentication_request", event_type = "AUTH" }
 
[logging.log_event_mapping.authorization_denied]
serialized_fields = { event_name = "auth.authorization_denied", event_type = "AUTH", actor_id = "{event.record.extra.account_id}" }
 
# Disabled outright -- no log line is produced for this event at all.
[logging.log_event_mapping.file_uploaded]
enabled = false

Any event without its own [logging.log_event_mapping.*] block — user_added, runtime_error, and so on in this example — still fires, using log_event_defaults unmodified.

Related documentation