AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
icon: 📜
Audit Logs
Records security-relevant actions for compliance and forensics, persisted to the audit_event table and queryable by platform admins. Enterprise/Cloud only, gated by platform.plan.auditLogEnabled.
Entities & services
- ApplicationEvent: discriminated union of all auditable types; ApplicationEventName is a 41-value enum (
flow.created,flow.published,user.signed.in,variable.value.revealed, etc.). audit_evententity:action,userEmail,userId,projectId(nullable),data(jsonb),ip. Composite indices on(platformId, projectId, userId, action)and narrower.audit-event-service.ts:setup()andlist().
How it works
setup()registers two fire-and-forget listeners on theapplicationEventsbus —userEvent(user actions) andworkerEvent(background actions) — so events are captured transparently without callers coupling to the audit code.GET /v1/audit-events(platformAdminOnly) returnsSeekPage<ApplicationEvent>sorted bycreateddesc, or asc withorder=ASC(the retention dialog reads the oldest event withorder=ASC&limit=1). Filters:action[],projectId[],userId,createdBefore/After, cursor/limit.
Retention
- Retention ceiling:
AP_AUDIT_LOG_RETENTION_DAYS, the instance maximum; empty keeps events forever. Read it only throughauditLogRetentionCeiling(digits only, 30–3650, anything else is null = keep forever). Its floor matches the platform minimum, so every ceiling leaves an admin at least one period to pick. - Platform retention: nullable
platform.auditLogRetentionDays, set by a platform admin from the Audit Logs page (at least 30, at most the ceiling or 3650). The effective value isLEAST(platform, ceiling); NULL with NULL skips the platform. SystemJobName.AUDIT_LOG_RETENTIONruns hourly at:15, EE/Cloud only. One probe query lists platforms with expired rows in random order. The run then goes round those platforms, at most 100k rows per platform per round, until none has expired rows or the run reaches 1M rows or 10 minutes, so a single-platform install gets the whole budget. Each batch deletes 5000 rows oldest first withFOR UPDATE SKIP LOCKED, then pauses for as long as it took.- Pause flag:
AP_AUDIT_LOG_RETENTION_PAUSED=trueskips the job and keeps every retention value. The ceiling cannot pause anything, becauseLEASTonly shortens. The flagAUDIT_LOG_RETENTION_PAUSEDcarries it to the Retention dialog, which says the cleanup is paused. - Run summary:
stoppedByisdoneonly when no platform has expired rows left, andfailedwhen every platform still left failed this run. A platform still more thanAUDIT_LOG_RETENTION_BACKLOG_GRACE_DAYSbehind its period goes into one warn line per run (worst 10). - Retention change event:
audit.log.retention.updated, sent byplatformSideEffectsfromplatformService.updateonly when the value changes.previousRetentionDaysandretentionDaysare the platform values (null = use the instance limit);instanceLimitDaysis the ceiling at that moment, so a reader can tell "forever" from "instance limit".
Gotchas
Event capture is decoupled via the event bus — new auditable actions just emit onto
applicationEvents.Emit from the service that performs the operation, not from each caller. Controller-only emission is how #14591 happened: flow events lived in
flow.controller.ts, so all 15 MCP flow tools plusapp-connection.handler.ts,worker-rpc-service.ts,project-state-helper.tsandplatform-teardown-jobs.tsmutated flows and audited nothing. Flow runs never had that bug becauseflowRunSideEffectsis called fromflow-run-service.ts. Put the*-side-effects.tshook call inside the service and default it on; where a bulk/system path genuinely wants silence (project release apply, platform teardown), give it an explicitemitEvents: falseopt-out so the decision is reviewable instead of accidental. Request-derivedipis optional in the schema — pass it down from the controller as one optional param rather than keeping emission up there to preserve it.The list endpoint sorts by
created DESC, id DESC—Paginatorappends theidtiebreaker itself (withIdTiebreaker), so the index has to cover both columns.(platformId, created DESC)alone leaves an Incremental Sort node on top;(platformId, created DESC, id DESC)is a plain index scan. Without either, Postgres reads every row for the platform (via theplatformId-leadingactionindex) and sorts the lot to return 11, so the page 500s on statement timeout (GIT-1705). Cloud prod, Aug 2026:audit_eventis 362M rows / 475 GB, one platform holding ~6.5M — plan cost 7.4M, and it never finishes. The table is never pruned (GIT-1574), so any new query shape here needs an index covering the sort, not just the filter.Building any index on
audit_eventin prod is an operation, not a migration step: at 475 GBCREATE INDEX CONCURRENTLYruns for hours, and migrations run inmain.tsbefore the server listens — so a boot-time build never reaches the healthcheck and the deploy is rolled back on top of a half-built index. Build it by hand ahead of the deploy and let the migration'sIF NOT EXISTSno-op.CREATE INDEX CONCURRENTLYalso obeysstatement_timeout, soSET statement_timeout = 0in the psql session doing the build (and expect the boot-time path to fail outright wherever a role-level timeout is set). A CONCURRENTLY build that gets killed leaves the index present butindisvalid = false, where a plainIF NOT EXISTSretry skips it and reports success on an index the planner will never use; the 1820 migration checkspg_index.indisvalidand drops the invalid leftover before rebuilding, for that reason.Anything you read about this paginator emitting
DATE_TRUNC('second', created)cursors is stale — it now selectscreated::textand emits a plain composite cursor(created < c) OR (created = c AND id < i), so the old "events in the same second get skipped across pages" bug is gone.summarizeApplicationEvent()builds detailed summaries (e.g. forflow.updated).buildMockEvent()yields a typed mock per event name, reused by event-destination test delivery.Never read the retention ceiling with
system.getNumber. It usesparseInt, so0reads as 0 and1e3as 1, and the startup validator only warns. A ceiling of 0 would delete every platform's events each hour.Retention deletes walk
(platformId, created DESC, id DESC)backwards. Do not add acreated-leading index for them; on the Cloud table that build is a manual, hours-long operation (see above).Each retention batch carries a keyset cursor
(created, id)from the last row it deleted. Without it every batch re-walks the dead index entries that earlier batches left at the old end of the index until vacuum runs, which grows with the square of the rows deleted per run. The cursor is ato_char(..., 'US')ISO string so it keeps microseconds, and theidpart matters: events takecreatedfrom JSnew Date(), so many share a millisecond.Each retention batch re-reads the platform's period with
SELECT ... FOR SHAREon the platform row. The probe's value can be minutes old by the last batch, and an admin who lengthens or clears the period must not lose rows after the save returned. The share lock makes that save wait for one batch at most.The job sets
autovacuum_vacuum_scale_factor = 0.02onaudit_eventthe first time it has rows to delete, and only when the table has no value, so an operator's setting wins. It is not a migration:ALTER TABLE ... SETwaits behind a running anti-wraparound vacuum, and migrations run before the healthcheck. Itslock_timeoutis 100 ms, under the default 1 sdeadlock_timeout, so it gives up before Postgres would cancel a running autovacuum to let it in.platformService.updatereads the previousauditLogRetentionDayswithSELECT ... FOR UPDATEinside the save transaction, and writes that locked value back when the request does not set the field. Otherwise two admins saving at once both report the same "before" inaudit.log.retention.updated, and a save of any other field writes back a stale retention value. Every other platform field is still last-write-wins: the save writes the row as it was read at the start of the request. PGlite runs one connection, so the API tests cannot reproduce either race.Tests that need a race during a sweep (a period changed mid-run, a batch that fails) install a
BEFORE DELETEtrigger onaudit_event; PGlite runs PL/pgSQL.Count deleted rows inside the statement, as
WITH deleted AS (DELETE ... RETURNING ...) SELECT count(*) OVER () ..., not withaffected. TypeORM fillsaffectedfromrowCount, which a PGlite result does not have. A top-levelSELECTreturns rows the same way on both drivers, where a bareDELETEthroughem.querydoes not.Flow-run STARTED/FINISHED events, test runs included, carry the whole
FlowRunand are most of the rows. Retention bounds the table; it does not lower the write rate.Every event is saved for every platform, whatever
plan.auditLogEnabledsays. The flag gates the read endpoint and the retention setting, not capture, so only the instance ceiling cleans a platform without the feature.The retention job reads
platform_plan.auditLogEnableditself, with aLEFT JOIN, in the probe and in every batch. A saved period counts only while the plan has audit logs, because the API refuses every retention change (clearing included) on a plan without them, so a downgraded admin could not stop it. A platform with no plan row falls back to the ceiling. On Cloud the plan row only refreshes from Autumn when something reads the plan, so a churned platform nobody opens can keepauditLogEnabled = trueand its saved period keeps running.A
DELETEdoes not shrink the table file; Postgres reuses the space. A one-time shrink needspg_repackorVACUUM FULL.AP_AUDIT_LOG_RETENTION_PAUSEDis read by the app server that picks up the hourly job, and every app server runs the system-job worker. A pause set on only some servers does not stop the cleanup.The piece-upgrade revert (
POST /v1/admin/flows/revert-upgrade) readsflow.pieces.upgradedrows, so it can only revert upgrades still inside the platform's retention period.A new event's docs page renders from
openapi-schema, which resolves againstdocs/openapi.json. Nothing regenerates that file; commit its entries by hand.z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'input' | 'output' })plus$id: '#/components/schemas/<name>[Input]'reproduces the existing entries exactly. The fourflow.approval.*pages point at schemas that are not in the file.
Key files
Entry point: auditLogService, wired up in auditEventModule which calls .setup() and mounts the controller at /v1/audit-events. Retention: auditLogRetention (the job) and auditLogRetentionCeiling (the only reader of the env ceiling).
packages/server/api/src/app/ee/audit-logs/— module, service, TypeORM entity, and the retention jobpackages/server/api/src/app/helper/retention/— the retention ceiling reader (CE, shared with the platform service and flags)packages/server/api/src/app/platform/—platformSideEffects, which sends the retention change eventpackages/core/shared/src/lib/ee/audit-events/— event types, theApplicationEventunion,summarizeApplicationEvent(), andbuildMockEvent()packages/web/src/features/platform-admin/api/audit-events-api.ts— frontend API clientpackages/web/src/features/platform-admin/hooks/audit-log-hooks.ts— React Query hookspackages/web/src/app/routes/platform/security/audit-logs/— platform admin UI pagepackages/web/src/features/platform-admin/—AuditLogRetentionButtonandauditLogRetentionUtilspackages/server/api/test/integration/cloud/audit-event/— integration testsdocs/admin-guide/security/audit-logs/— one user-facing doc page per event type
Paths verified 2026-10-01.