Audit Trail Basics
Every action in AiQarus creates an immutable, cryptographically-verified audit trail. This isn’t logging as an afterthought—traceability is built into the core architecture.
What Gets Logged
Every event during agent execution is captured as a trace:
| Event Type | Description | When |
|---|---|---|
run_started | Agent execution begins | Start of run |
step_started | TDAO iteration begins | Each step |
think_completed | Think phase output | Each step |
decide_completed | Decision made | Each step |
tool_called | Tool invocation started | On tool use |
tool_completed | Tool returned result | On tool completion |
decision_point_created | Human approval requested | On HITL |
decision_point_resolved | Human responded | On HITL response |
step_completed | TDAO iteration finished | Each step |
run_completed | Agent execution finished | End of run |
run_failed | Agent execution failed | On failure |
Trace Structure
Each trace contains:
{
"id": "trace_abc123",
"org_id": "org_456",
"run_id": "run_789",
"step_id": "step_012",
"event_type": "tool_completed",
"payload": {
"tool": "okta_revoke_access",
"input": {
"user_id": "sarah.chen@company.com",
"application": "aws-production"
},
"output": {
"success": true,
"revoked_at": "2026-01-15T14:30:00Z"
},
"duration_ms": 1250
},
"sequence_num": 15,
"previous_hash": "sha256:a1b2c3d4...",
"current_hash": "sha256:e5f6g7h8...",
"timestamp": "2026-01-15T14:30:01.234Z"
}The Hash Chain
Traces are cryptographically linked using SHA-256:
Trace 1 Trace 2 Trace 3 Trace 4
│ │ │ │
▼ ▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│Data 1│ │Data 2│ │Data 3│ │Data 4│
│ │ │ │ │ │ │ │
│Hash A│──────▶│Hash B│───────▶│Hash C│───────▶│Hash D│
│ │ │ │ │ │ │ │
│prev: │ │prev:A│ │prev:B│ │prev:C│
│ null │ │ │ │ │ │ │
└──────┘ └──────┘ └──────┘ └──────┘Hash Computation
CurrentHash = SHA256(
OrgID +
RunID +
StepID +
EventType +
Payload +
SequenceNum +
PreviousHash +
Timestamp
)Why This Matters
If any trace is modified:
- Its hash changes
- All subsequent hashes become invalid
- The chain fails verification
This provides cryptographic proof that audit logs haven’t been tampered with.
Viewing the Audit Trail
Run Detail View
┌─────────────────────────────────────────────────────────────────────┐
│ Audit Trail: Run off_123 │
│ Status: Chain Verified ✓ │
│ │
│ ────────────────────────────────────────────────────────────────── │
│ │
│ 14:29:55.123 run_started │
│ Agent: Employee Offboarding (v4) │
│ Input: {employee: "sarah.chen@company.com"...} │
│ │
│ 14:29:55.456 step_started │
│ Step 1 of estimated 8 │
│ │
│ 14:29:56.789 think_completed │
│ Reasoning: "Analyzing offboarding request..." │
│ │
│ 14:29:57.012 decide_completed │
│ Decision: continue │
│ Action: fetch_employee_data │
│ │
│ 14:29:57.345 tool_called │
│ Tool: okta_get_user │
│ Input: {email: "sarah.chen@company.com"} │
│ │
│ 14:29:58.678 tool_completed │
│ Success: true │
│ Duration: 1.3s │
│ │
│ [Load More] [Export JSON] [Export CSV] [Verify Chain] │
│ │
└─────────────────────────────────────────────────────────────────────┘Filtering Traces
Filter by:
- Event type
- Time range
- Step number
- Tool name
- Verification status
Verification
Via UI
Click Verify Chain to validate the entire audit trail:
┌─────────────────────────────────────────────────────────────────────┐
│ Chain Verification Results │
│ │
│ ✓ Chain is VALID │
│ │
│ Total traces: 47 │
│ Verified: 47 │
│ Failed: 0 │
│ │
│ First trace: 2026-01-15T14:29:55.123Z │
│ Last trace: 2026-01-15T14:35:22.456Z │
│ │
│ Genesis hash: sha256:abc123... │
│ Final hash: sha256:xyz789... │
│ │
│ [Download Verification Report] │
│ │
└─────────────────────────────────────────────────────────────────────┘Via API
query VerifyAuditChain($runId: ID!) {
verifyTraceChain(runId: $runId) {
isValid
totalTraces
verifiedTraces
failedTraces
firstTrace {
id
timestamp
hash
}
lastTrace {
id
timestamp
hash
}
errors {
traceId
sequenceNum
error
}
}
}Export Formats
JSON Export
Complete trace data with all fields:
{
"run_id": "run_789",
"verified_at": "2026-01-15T15:00:00Z",
"chain_valid": true,
"traces": [
{ ... },
{ ... }
]
}CSV Export
Flattened for spreadsheet analysis:
timestamp,event_type,step_id,tool,success,duration_ms,hash
2026-01-15T14:29:55,run_started,,,,sha256:abc...
2026-01-15T14:29:56,tool_called,step_1,okta_get_user,,sha256:def...PDF Report
Formatted audit report for compliance:
- Executive summary
- Run details
- Full trace timeline
- Verification certificate
Retention Policies
Configure how long traces are retained:
| Plan | Retention |
|---|---|
| Free | 7 days |
| Starter | 30 days |
| Pro | 90 days |
| Enterprise | Custom (years) |
After retention period:
- Traces are archived
- Archived traces can be restored
- Hash chain integrity is preserved
Best Practices
Export for Compliance
For regulated industries:
- Export audit trails regularly
- Store exports in immutable storage
- Include verification certificates
Monitor Verification
Set up alerts for:
- Failed chain verifications
- Missing traces
- Unexpected gaps
Document Retention
Work with compliance team to:
- Define retention requirements
- Set up archival processes
- Test restoration procedures