Audit Logs

GTM Clarity maintains a comprehensive audit trail of all mutations across the platform. Every create, update, and delete operation is recorded with full context, enabling compliance, debugging, and accountability.

What Gets Logged

All mutations that pass through the tRPC middleware are automatically recorded. The audit middleware intercepts every mutation procedure and logs:

• Who performed the action (userId)
• What action was taken (action)
• Which resource was affected (resource, resourceId)
• What changed (changes -- before/after payload)
• When it happened (createdAt)
• Additional context (metadata)

Logged Operations

Category	Operations Logged
Connectors	Add, edit, remove, re-authenticate, trigger sync
Scoring Config	Create, update, activate, deactivate
Field Mappings	Create, update, delete
Writeback	Enable, disable, configure, execute
Buying Groups	Create, confirm role, update template
Team	Invite user, remove user, change role
Tenant	Update settings

info

Read-only operations (queries, dashboard views, score lookups) are not logged in the audit trail. Only mutations that change data are recorded.

Audit Log Schema

The audit_log table captures every mutation:

Column	Type	Description
id	text (UUID)	Primary key
tenant_id	text	Tenant scope
user_id	text	Clerk user ID of the actor
action	text	Action performed (e.g., connector.create, scoring_config.update)
resource	text	Resource type (e.g., connector, scoring_config)
resource_id	text	ID of the affected resource (nullable)
changes	jsonb	Diff of before/after values
metadata	jsonb	Additional context (IP, user agent, etc.)
created_at	timestamptz	Timestamp of the action

Indexes

The table is indexed for efficient querying:

Index	Columns	Purpose
audit_log_tenant_created_idx	(tenant_id, created_at)	Timeline queries within a tenant
audit_log_tenant_resource_idx	(tenant_id, resource)	Filter by resource type
audit_log_user_idx	(user_id)	Find all actions by a user

Viewing Audit Logs

Via the Dashboard

Navigate to Settings > Audit Log to view the audit trail. The UI supports:

• Date range filtering -- View logs for a specific time period
• Resource type filtering -- Show only connector changes, scoring config changes, etc.
• User filtering -- See all actions by a specific team member
• Full diff view -- Expand any entry to see the complete before/after changes

Via the tRPC API

The audit router exposes two procedures:

// List recent audit entries with pagination
audit.list({ limit: 50, offset: 0 })

// Query with filters
audit.query({
  resource: "connector",
  userId: "user_abc123",
  startDate: "2026-01-01T00:00:00Z",
  endDate: "2026-03-01T00:00:00Z",
})

Example Audit Entries

Connector Added

{
  "action": "connector.create",
  "resource": "connector",
  "resourceId": "conn_abc123",
  "changes": {
    "type": "salesforce",
    "name": "Production Salesforce",
    "status": "connected"
  },
  "metadata": {
    "connectorType": "salesforce"
  }
}

Scoring Config Updated

{
  "action": "scoring_config.update",
  "resource": "scoring_config",
  "resourceId": "sc_def456",
  "changes": {
    "before": {
      "decayHalfLifeDays": 30
    },
    "after": {
      "decayHalfLifeDays": 14
    }
  }
}

Compliance Considerations

Data Retention

Audit logs are retained indefinitely by default. For compliance with data retention policies, admins can configure retention windows at the database level. GTM Clarity does not automatically purge audit records.

warning

The audit log table does not use soft delete. Records are append-only. There is no mechanism within the application to delete audit entries -- this is by design for compliance integrity.

SOC 2 and GDPR

The audit trail supports common compliance requirements:

Requirement	How GTM Clarity Addresses It
Access tracking	All data access mutations are logged with user identity
Change history	Full before/after diffs stored in changes JSONB
Tamper resistance	Append-only table, no delete/update operations
Tenant isolation	Every entry scoped by tenant_id
Timestamps	UTC timestamps with timezone (timestamptz)

Export

For external audit systems, logs can be exported via the tRPC API and integrated with SIEM tools or compliance platforms.

tip

Set up a regular export of audit logs to an external system (e.g., Datadog, Splunk) for long-term storage and cross-system correlation.

Related Pages

• RBAC & Roles -- Role-based access that generates audit entries
• Connector Management -- Connector operations that are audited
• Database Schema -- Full audit_log table definition