Skip to content

Audit Trail

The Flywheel audit trail is a feature available with Flywheel Validated Instance. See the Product Documentation on Audit Trail for more information.

The Flywheel Audit Trail is a detailed and immutable record of every creation, change to, and deletion of data on the Flywheel system, as well as administrative and project-level events.

Querying the Audit Trail requires admin permissions.

What the audit trail records

The audit trail captures access events including:

  • File downloads and uploads
  • Container creation, modification, and deletion
  • Permission changes
  • Gear rule changes
  • Locking and unlocking projects

Each log entry describes who did what, to which resource, and when it occurred.

The audit trail report model

The Flywheel audit trail uses an asynchronous report model. You create a report request that Flywheel processes, then download the result when it is ready.

The AuditTrailReport object has the following key fields:

Field Description
id Unique report identifier
label Human-readable report name
status Processing status (pending, complete, failed)
project_id Project scoped to the report (optional)
subject_ids Subject IDs included in the report (optional)
origin Origin of the report
revision Revision of the report, default 1
created Timestamp when the report was requested
finished Timestamp when processing completed
deleted Timestamp when the report was deleted
size Size of the generated report in bytes
celery_task_id Celery task ID of the report
error Error string of the report, if error encountered

Asynchronous audit trail reports

For large projects or projects with high occurrences of updates/modifications, it may take an hour or more for the Audit Trail report to complete.

Create an audit trail report for a project
import time
from pathlib import Path

report = fw.add_audit_trail_report(
    flywheel.CoreModelsAuditTrailCreateReportInput(
        label="Docs Test Audit",
        project_id=project_id,
    )
)
report_id = report.id

# Poll until the report is ready
while True:
    reports = fw.list_audit_trail_reports()
    report = next((r for r in reports if r.id == report_id), None)
    if report and report.status in ("complete", "failed"):
        break
    time.sleep(10)

if report and report.status == "complete":
    dest_file = Path("/path/to/audit_report.csv")
    response = fw.download_audit_trail_report(report_id, _preload_content=False)
    dest_file.write_bytes(response.content)

Note

If the Audit Trail report does not complete after 24 hours, contact Flywheel Support.

Listing existing audit trail reports

List all audit trail reports
reports = fw.list_audit_trail_reports()
for r in reports:
    print(r.id, r.label, r.status)