Skip to content

Audit Log

Logchef records configuration changes, sign-ins, OAuth decisions, query runs and data exports as audit events. Global admins read them in Administration → Audit Log, through the API, or with logchef audit list. Each event is also written as one JSON log line, so a log shipper can keep a copy off the host.

The audit log answers who queried or exported which data, over which time range, how many rows came back, and who downloaded the file. Each query is one query.run event with its full text. The audit log keeps every query for audit.retention_days. Query history keeps only the last queries of each user to reload in the editor, and Administration → Query Activity (/admin/query-activity) shows query usage as daily totals by user, source and filter shape. Each of the two admin pages links to the other.

One row of the audit_events table is one event. The API returns the same object.

Field Meaning
id UUIDv7. Time-ordered, so it breaks ties in the sort
occurred_at When the server built the event, UTC, millisecond precision
action <resource>.<verb>, such as source.update. See Actions
outcome success or failure
reason Empty on success. On failure, a fixed code such as invalid_credentials or internal_error, never driver text
actor_type user, service_account, system or anonymous
actor_id The user ID. No foreign key, so the event outlives the user
actor_label The email or service account name at the time. For system, the component. For a failed sign-in, the attempted email
auth_method How the actor authenticated. See the next table
credential_id API token ID, OAuth grant ID, provisioning run ID or report run. Empty for a session
client_id OAuth client ID, such as the CLI or an MCP host. Empty otherwise
target_type, target_id, target_label The object the action applies to. A setting uses its key as the ID. A query share uses its redacted token
team_id, source_id Set when the target belongs to one team or one source
ip The client address. It honors server.trusted_proxies. Empty for system
user_agent The first 256 bytes
http_method, route, status The method, the route pattern (such as /api/v1/admin/sources/:sourceID) and the response status. Never the raw path or query string
changes Field name to {"from": x, "to": y}. A create has only to, a delete only from. Only changed fields appear
detail Facts that are not a diff, such as an export’s format or a revoke’s cause
auth_method Caller credential_id
session A browser session empty
api_token A personal or service account API token token ID
oauth_api An OAuth access token for the API, such as the CLI grant ID
oauth_mcp An OAuth access token for /mcp grant ID
assistant Ask Chef acting for a user empty
provisioning A provisioning run run ID
startup Admin setup from auth.admin_emails and [auth.local], and OIDC auto-provisioning empty
scheduler A background job, such as a report run report_run:<id>
none A failed sign-in empty
  • Credentials. Passwords, API tokens, OAuth secrets, webhook URLs, connection headers and sensitive settings are recorded as {"secret": true, "changed": true}: the event says a secret changed, never its value. A field whose name contains password, secret, token, api_key, authorization, cookie, hash, headers, credential or dsn is replaced with [redacted].
  • Stored query text. Saved query content, alert queries and conditions, share payloads and saved view filters are recorded as a SHA-256 digest and a byte length: the event says the stored query changed, and the object itself holds the text. Alert labels and annotations are a digest plus the label names.
  • URLs. Any other absolute URL is reduced to its scheme and host.
  • Large objects. A dashboard is recorded by name, revision, panel count and tab count, never the panel definitions.

The text of a query that ran or was exported is the exception: query.run and log_export.create record it in full, because reading it is the point of the event. A literal in that text, such as a user ID or an email in a filter, reaches the table and the audit log line. Restrict who reads both.

One string value holds at most 1,024 bytes and ends with ... when cut. Query text holds at most 8 KiB. changes and detail together hold at most 16 KiB; later keys are dropped and detail.truncated is true.

Each action is a resource and a verb. A filter on source. matches every action of that resource. A request that changes nothing, such as removing a member who is not on the team, records nothing. A request refused with a 4xx before the change records nothing, except a failed sign-in.

Resource Actions Recorded when
Alert alert.create, alert.update, alert.delete, alert.resolve An alert rule changes or is resolved by hand
Alert silence alert_silence.create, alert_silence.update, alert_silence.delete A silence changes
API token api_token.create, api_token.delete A personal or service account token is issued or deleted. Creation fails closed
Audit log audit_event.export An admin downloads events. detail holds the filters and the row count
Collection collection.create, collection.update, collection.delete A collection changes
Collection item collection_item.add, collection_item.update, collection_item.remove A saved query is added to, converted in, or removed from a collection
Collection member collection_member.add, collection_member.remove A user is given or loses access to a collection
Collection team collection_team.add, collection_team.remove A collection is shared with or unshared from a team
Dashboard dashboard.create, dashboard.update, dashboard.delete A dashboard changes. A delete also removes the dashboard’s scheduled reports, with no report.delete of their own: detail.reports_removed counts them
Log export log_export.create, log_export.complete, log_export.download Logs are exported, streamed (detail.mode stream) or as a job (job), the export ends, and a job’s file is downloaded. See Exports. Creation fails closed
Notification destination notification_destination.create, notification_destination.update, notification_destination.delete, notification_destination.test A destination changes or is tested
OAuth consent oauth_consent.approve, oauth_consent.deny A user decides an OAuth authorization request. The event holds the client, the resource and the scopes
OAuth grant oauth_grant.revoke A grant is revoked: by the user in Connected apps, by the client at /oauth/revoke, or by the server on a replayed code or refresh token
Query query.run A data query runs. See Queries
Query share query_share.create, query_share.delete A share link is created or deleted
Report report.create, report.update, report.delete, report.pause, report.resume, report.claim A scheduled report’s configuration changes, or it is paused (by a user or by the scheduler), resumed, or claimed by a new owner. Report runs and sends are in the report’s own run history
Report recipient report_recipient.remove A direct recipient takes themself off a report. Recipients that the owner adds or removes are in the recipients field of report.create and report.update
Saved query saved_query.create, saved_query.update, saved_query.delete A saved query changes. A delete also removes the query’s scheduled reports, with no report.delete of their own: detail.reports_removed counts them
Saved view saved_view.create, saved_view.update, saved_view.delete, saved_view.set_default, saved_view.clear_default An Explorer view changes or becomes or stops being a default
Schema advisor dismissal schema_advisor_dismissal.create, schema_advisor_dismissal.delete An admin dismisses or restores a schema advisor finding
Schema advisor schedule schema_advisor_schedule.update An admin turns a source’s weekly schema analysis on or off
Service account service_account.create, service_account.delete A service account is created or deleted
Session session.login, session.logout A local or OIDC sign-in (detail.method), including a failed one, and a sign-out
Setting setting.update, setting.delete, setting.test A system setting changes, or the test email or webhook is sent
Source source.create, source.update, source.delete A source changes
Team team.create, team.update, team.delete A team changes
Team member team_member.add, team_member.remove A user joins or leaves a team. A role change is a team_member.add with a role diff
Team source team_source.link, team_source.unlink A source is linked to or unlinked from a team
User user.create, user.update, user.delete A user changes. Role and status are in changes

Every data query records one query.run event, whether it succeeds or fails: POST /logs/query (buffered or streamed), POST /logs/windowed and POST /logchefql/query, from the UI, the CLI or an API token, and also each live tail session, each log context request, and each MCP or Ask Chef tool call that reads logs. The target is the source, with team_id, source_id and the source name as target_label. A failed query has outcome failure and a reason of invalid_query, timeout, cancelled, rejected (a concurrency limit), upstream_error or internal_error.

detail key Meaning
query The query text as sent, up to 8 KiB. LogchefQL is recorded as LogchefQL, not the SQL it compiles to
language clickhouse-sql, logchefql, logsql or logql
mode buffered, stream, windowed, tail, context, mcp or ask_chef
tool The MCP tool that read the logs, for mcp and ask_chef
fields The fields whose values a field value tool read
anchor The timestamp that a log context read is around, UTC
time_from, time_to The requested time range, UTC. null for SQL that carries its own range
limit_requested, limit_applied The row limit the caller asked for and the one that applied
duration_ms Execution time. For a tail, how long the session ran
rows_returned Rows sent to the client. A failed stream counts the rows sent before it failed
rows_read, bytes_read What the backend scanned, when it reports it
result_truncated Whether a limit cut the result
query_id The query_id of the response, which the cancel route takes
cache For a dashboard panel answered through the result cache: hit, miss, coalesced or bypass. Such an event has no row counts

A windowed search records one event per request, including each later page.

A live tail is one event, recorded when the session ends: the client disconnects, the session TTL expires, the server shuts down or the backend fails. query is the filter as sent, rows_returned counts the rows sent (not the rows that the row ceiling dropped), and only a backend error fails it. A tail refused at the concurrency limit is a rejected failure. A log context request records anchor, the rows it asked for on both sides as limit_requested, and the before, target and after rows together as rows_returned.

An MCP or Ask Chef tool call is one event per call that reads logs, with the user it ran for as the actor. An MCP call has auth_method oauth_mcp with the grant and the client, and route /mcp. An Ask Chef call has the credential of the turn request (session or api_token) and its route. The tools that read logs are query_logs, get_log_histogram, query_logchefql, compare_windows (one event for both windows, with the range that covers both), get_field_values, top_values, get_all_field_dimensions and get_log_context. Tools that read only metadata, such as get_sources, get_source_schema, translate_logchefql, list_saved_queries and list_alerts, record nothing. A call refused before its source is authorized records nothing either.

Tails, log context and tool calls write no query history. A windowed count request, the histogram and the field sidebar in the UI record no query.run yet.

The query answers before its event is stored: the event goes through the background writer that also writes query history, so a slow audit insert never slows a query. When the writer’s queue is full, the event is dropped, counted in logchef_audit_events_total{result="dropped"}, and a warning names the count.

An export is one target, log_export, from create to download, so History of this target shows the whole export. A job uses its job ID. A streamed export has no job, so its query ID is the ID of its create and complete events.

Action Holds
log_export.create In changes: the full query, language, format, row_limit, and time_from and time_to as sent
log_export.complete The creator as actor, outcome, a failure reason, and in detail rows_exported, bytes_written and duration_ms. It runs after the request, so it has no IP or route
log_export.download The downloader, and in detail format, file_name, rows_exported, bytes_written and created_by (the creator’s user ID)

A download is one event. A Range request that resumes it, one whose first range does not start at byte 0, records nothing. A job’s file and its row are deleted after export.artifact_ttl, but its events stay for audit.retention_days.

Some changes happen outside the request handlers. Except for a client revoke at /oauth/revoke, they have actor_type system and no IP address.

Writer Actions Actor
Provisioning source.*, team.*, team_member.*, team_source.*, user.create, and user.update when a run marks an existing user as managed provisioning, with one run ID per run in credential_id. Adopting an existing source or team is an update with managed going from false to true
Admins from auth.admin_emails at startup user.create, user.update startup, label auth.admin_emails
The local admin from [auth.local] at startup user.create startup, label auth.local
OIDC auto-provisioning on first sign-in user.create, team_member.add startup, label auth.auto_provision, with the matched domain in detail.domain
The OAuth server oauth_grant.revoke On a replayed authorization code or refresh token, with detail.cause code_replay or refresh_replay. A client revoke at /oauth/revoke has the grant’s user as actor
The report scheduler report.pause scheduler, with the run in credential_id and the cause in detail.reason

A provisioning run records its events only after its transaction commits. A dry run, or a run that fails, records nothing.

Two gaps are known:

  • The local admin that ensureLocalAdmin creates at startup, and the password it sets, record no event.
  • A replayed OAuth token records no client IP, because a system event has none. The grant ID and the cause identify the replay.

Only global admins read the audit log. Team admins and members have no access. Nobody can change or delete an event through Logchef.

Administration → Audit Log (/admin/audit-log) lists events newest first. Filter by time range, action (an exact action or a resource. prefix), actor, outcome, and target type and ID. The filters live in the URL, so /admin/audit-log?target_type=source&target_id=7 is the history of one source, and each expanded row links to its target’s history. A row expands to show the changed fields, the detail, the route, the status, the auth method, the credential and client IDs and the user agent, and names the event’s source and team. A query or export event shows its query in full with the time range, rows, bytes and duration. Load more fetches the next page, and Download exports the events that match the filters.

Both routes need a global admin: a session, or an API token with the audit:read scope (or *). OAuth tokens, including a logchef auth sign-in and MCP clients, are always refused. audit:read is not part of the Read-only token preset, because events hold emails and IP addresses.

GET /api/v1/admin/audit-events
Parameter Meaning
from, to RFC 3339. Default: the 7 days before to, which defaults to now
action An exact action, or a resource with a trailing dot such as source.
actor_id, auth_method, credential_id Exact match
target_type, target_id Exact match. target_id needs target_type
team_id, source_id, outcome Exact match
order desc (default) or asc
limit Default 100, at most 500
cursor The next_cursor of the previous page

The response is the standard envelope, {"status": "success", "data": {"events": [...], "next_cursor": "..."}}. Pass data.next_cursor as cursor with the same filters to get the next page; it is empty on the last page. A bad parameter, or an unknown action or resource, is a 400.

Terminal window
curl -H "Authorization: Bearer $LOGCHEF_TOKEN" \
"https://logchef.example.com/api/v1/admin/audit-events?action=source.&limit=50"
GET /api/v1/admin/audit-events/export

The export takes the same filters and streams application/x-ndjson, one event per line. to is capped at now. Above 100,000 matching events it answers 400 and asks for a narrower time range. Each export records an audit_event.export event with the filters and the row count.

Terminal window
# Every source change in the last 24 hours
logchef audit list --action source. --since 24h
# One source's history as JSON lines
logchef audit list --target source:7 --output jsonl
# Failed sign-ins over the last week
logchef audit list --action session.login --outcome failure --since 7d

--since and --until take a lookback such as 24h or an RFC 3339 time. --actor takes a user ID, --target a type or type:id, and --limit (default 100) is the total; the CLI follows the cursor for you. The CLI needs an API token with audit:read, passed with --token or LOGCHEF_AUTH_TOKEN.

Each event is also written to the server log as one JSON line with msg audit, level info, every field above as a top-level attribute, and stored, which says whether the database insert succeeded. A line with "stored": false is the only copy of an event whose insert failed.

{"time":"2026-11-16T09:12:03.512Z","level":"INFO","msg":"audit","id":"019a8c3e-...","occurred_at":"2026-11-16T09:12:03.511Z","action":"source.update","outcome":"success","reason":"","actor_type":"user","actor_id":1,"actor_label":"admin@example.com","auth_method":"session","credential_id":"","client_id":"","target_type":"source","target_id":"7","target_label":"nginx","team_id":null,"source_id":7,"ip":"203.0.113.10","user_agent":"Mozilla/5.0 ...","http_method":"PUT","route":"/api/v1/admin/sources/:sourceID","status":200,"changes":{"ttl_days":{"from":7,"to":30}},"detail":null,"stored":true}

To keep a copy off the host, have your shipper select lines whose msg is audit. For example, with Vector:

[transforms.logchef_audit]
type = "filter"
inputs = ["logchef_logs"]
condition = '.msg == "audit"'

Set audit.log_events = false to turn the line off.

[audit]
retention_days = 30
max_rows = 1000000
log_events = true
Key Default Meaning
audit.retention_days 30 Delete events older than this many days. 0 keeps every event
audit.max_rows 1000000 Delete the oldest events above this count. 0 removes the bound
audit.log_events true Write the audit log line

A negative value falls back to the default. The keys live in the config file, not in system settings, so an admin session cannot shorten retention from the UI. Like every key, they can be set with environment variables, such as LOGCHEF_AUDIT__RETENTION_DAYS.

Every five minutes each server deletes at most 5,000 events, oldest first, by both bounds. A larger backlog drains over the following runs. Pruning is idempotent, so replicas can run it at once. It logs the count and records no audit event.

Every query adds a query.run event, and query events count toward max_rows like any other. On a busy instance max_rows can end retention before retention_days: at 50,000 queries a day, 1,000,000 rows hold about 20 days. Raise max_rows to cover retention_days at your query volume, or ship the audit log line for longer retention.

With demo.read_only set, events go to the log line only.

Most events are recorded after the change commits, and fail open. If the insert fails, the change stands, the request succeeds, the log line says "stored": false, and logchef_audit_events_total{result="failed"} counts it. A provisioning run also fails open: a failed insert does not stop startup. Sign-in fails open too, so a broken audit table cannot lock out the admins who need to repair it.

Three actions fail closed: no credential and no log data leaves the server without a stored event.

Action On a failed insert
api_token.create, personal and service account The token is rolled back. The request answers 503 and no token exists
log_export.create, streamed The request answers 503 before the query runs. No log data is sent
log_export.create, export job The job is rolled back. The request answers 503 and no job exists

log_export.complete and log_export.download fail open, because log_export.create already recorded who made the file. query.run fails open too: the query has already answered when its event is written.

Bound Value What you see
changes plus detail 16 KiB Later keys dropped, detail.truncated is true
One string value 1,024 bytes The value ends with ...
Query text 8 KiB The text ends with ...
List page 500 events limit is clamped
Export 100,000 events 400 asking for a narrower time range
Insert timeout 2 seconds Fails open or closed by action
Pruning 5,000 events per 5 minutes per server A backlog drains over several runs
Failed sign-in events 600 per minute per server Extra events go to the log line only, counted as limited

The failed sign-in bound exists because that is the one event an unauthenticated caller can cause. Without it, a credential-stuffing run could fill the table and push real events past audit.max_rows. With several replicas the bound is per process, and events from different replicas that are milliseconds apart can sort out of order under clock skew.

Metric Meaning
logchef_audit_events_total{result} Events by result: stored, failed (the insert failed; the log line has the event), limited (the failed sign-in bound kept it out of the table) or dropped (a full query queue lost a query.run event, which has no log line either)
logchef_audit_redactions_total Values the serializer replaced with [redacted]
logchef_audit_unstaged_total Events whose handler staged no target or fields. Above zero means a code path is missing its audit fields

See Metrics Reference.