Audit Trail Guide

Qarion emits structured audit events for governance-sensitive operations. This guide explains how audit events are generated, what they contain, and how to query the audit log API.

How Audit Events Are Emitted

Audit events are emitted server-side by services whenever a governance-sensitive action occurs. Each service calls emit_audit_event() with structured metadata, producing a persisted AuditLog record.

Services That Emit Audit Events

Service	Event Examples
Governance	Owner changed, steward assigned, classification updated
Glossary	Term created, updated, deleted, linked to field
Access Requests	Request submitted, approved, rejected, revoked
Catalog	Product created, updated, deleted
Source Systems	System created, deleted, credential updated
Quality	Check created, threshold changed
Connectors	Connector created, deleted, sync triggered
Permissions	Role assigned, permission rule created/modified

Audit Log API

List Audit Logs

GET /spaces/{slug}/audit-logs

Query Parameters

Parameter	Type	Default	Description
entity_type	string	—	Filter by entity type (product, glossary_term, source_system, etc.)
entity_id	UUID	—	Filter by specific entity
action	string	—	Filter by action (created, updated, deleted, etc.)
user_id	UUID	—	Filter by acting user
start_date	ISO datetime	—	Events after this timestamp
end_date	ISO datetime	—	Events before this timestamp
limit	integer	50	Max records to return
offset	integer	0	Pagination offset

Response

{
  "items": [
    {
      "id": "uuid",
      "entity_type": "glossary_term",
      "entity_id": "uuid",
      "action": "updated",
      "user_id": "uuid",
      "user_name": "Jane Smith",
      "changes": {
        "description": {
          "old": "Original definition",
          "new": "Updated definition with examples"
        }
      },
      "metadata": {},
      "created_at": "2026-02-17T10:30:00Z"
    }
  ],
  "total": 142
}

Audit Event Fields

Field	Type	Description
entity_type	string	The type of entity affected
entity_id	UUID	The specific entity's ID
action	string	The action performed
user_id	UUID	The user who performed the action
user_name	string	Display name of the acting user
changes	object	Diff of changed fields (old/new values)
metadata	object	Additional context (e.g., space slug, request ID)
created_at	string	ISO timestamp of the event

Audit Event Lifecycle

User Action → API Endpoint → Service Layer → emit_audit_event() → AuditLog table

Events are captured synchronously during the request lifecycle. If the primary operation succeeds but the audit event fails to persist, the operation still completes — audit emission is best-effort.

Best Practices

• Compliance reporting — Use date-range queries to generate periodic audit reports
• Change investigation — Filter by entity_id to see the full history of a specific entity
• User activity — Filter by user_id to review a user's actions across entities
• Webhook integration — Combine with webhooks to push audit events to external SIEM systems

Related Documentation

• Webhooks — Push audit events to external systems
• Observability — Monitoring and logging infrastructure