TRUNCATE trigger at the database level blocks bulk deletion. Each record’s SHA-256 hash includes the previous record’s hash, so removing or re-dating a record breaks the chain everywhere downstream. If you need to remove a record for legal reasons (such as GDPR right-to-be-forgotten on PII), the answer is data minimization upfront, not retroactive editing.
Tracer maintains a complete, immutable of all validation decisions. This guide explains how the audit system works and how to query validation history for compliance reporting.
Compliance overview
Tracer is designed to meet the audit requirements of financial regulations including:
Audit trail architecture
Tracer records every validation decision with full context for compliance and investigation.
What gets recorded
Every validation creates an immutable audit record containing:Audit events are deduplicated for transaction validations. If you retry a validation request with the same
requestId, Tracer stores only the first audit event. This ensures the audit trail reflects unique business events, not API retry patterns.Immutability and hash chain
Audit records are write-once and cryptographically chained:- You cannot modify a record after creation.
- A
TRUNCATEtrigger protects the audit table at the database level and blocks bulk deletion. - Each record stores a SHA-256 hash computed over the record’s identity, timestamp, actor, and the previous record’s hash, forming an append-only chain. Removing, re-ordering, or re-dating a record makes every later record fail verification.
- A
pg_advisory_xact_lockserializes hash-chain writes to keep the order stable under concurrent inserts.
GET /v1/audit-events/{id}/verify, which returns:
isValid is true and message confirms it. When a record no longer matches its stored hash, isValid is false. The message field reports tampering. This is the cryptographic basis for SOX/GLBA tamper-evidence guarantees.
On a failed check, firstInvalidId carries an internal sequence number for the diverging record. It is not an audit-event id, so it is not a value you can pass to GET /v1/audit-events/{id}.
The audit trail is designed for compliance audits. You can reconstruct exactly what happened for any validation, even years later. You can also prove that the records never changed after the fact.
Data retention
Tracer retains data according to regulatory requirements and operational needs.
Retention periods
Compliance considerations
- SOX requirement: Maintain records for 7 years from the date of the audit report
- GLBA requirement: Retain records demonstrating compliance with privacy rules
- Data export: You can export records for external audit systems
Querying validation history
Use the
GET /v1/validations endpoint to query historical validations.
Basic query
Filtered query
Available filters
Date format requirement
Valid:Pagination
Results use cursor-based pagination. The response includesnextCursor and hasMore fields to navigate through results.
Cursor pagination keeps
sort_by and sort_order from the original query.Sorting
Getting validation details
Retrieve complete details for a specific validation using
GET /v1/validations/{id}.
The response contains everything needed to understand a validation decision:
- Request snapshot: The complete input payload as received
- Response snapshot: Full response including decision and reason
- Evaluated rules: All rules that Tracer checked
- Matched rules: Rules that triggered (if any)
- Limit details: Usage information for checked limits
- Timestamps: When the validation occurred and processing time
Querying audit events
Beyond validation records, Tracer also exposes a generic audit event log via
GET /v1/audit-events. This is the only way to see lifecycle changes for rules and limits: who created, updated, activated, deactivated, drafted, or deleted them.
Event types
Reservation events appear in the log but no filter selects them. The
event_type, action, and resource_type parameters accept only the values listed in the table below. Each one rejects a reservation value with error 0009. To read reservation events, query by date range and page through the results.Filters
GET /v1/audit-events accepts the same date-range and scope filters as GET /v1/validations, plus filters tailored to lifecycle events:
Use cases
- Who activated this rule?
GET /v1/audit-events?resource_type=rule&resource_id={ruleId}&action=ACTIVATE - All rule changes last week:
GET /v1/audit-events?resource_type=rule&start_date=...&end_date=... - All limit deletions in 2026:
GET /v1/audit-events?resource_type=limit&action=DELETE&start_date=2026-01-01T00:00:00Z
Single event detail
UseGET /v1/audit-events/{id} to retrieve a specific audit record, including the snapshot of state at the time of the event.
Compliance reporting scenarios
Common queries for audit and compliance reporting.
Scenario 1: Audit investigation
“Why was this transaction denied on January 15th?”Scenario 2: Monthly compliance report
“Show all denied transactions for corporate accounts in January”Scenario 3: Rule effectiveness analysis
“Which transactions were denied by a specific fraud rule?”Scenario 4: Limit usage review
“Which transactions exceeded spending limits this month?”Best practices for compliance
Recommendations for maintaining audit readiness.
Record keeping
- Store validation IDs in your transaction records for easy cross-reference
- Log the requestId you send to Tracer for correlation
- Export regularly if you need records in external audit systems
Audit preparation
- Test queries before audit season to ensure you can retrieve needed data
- Verify date ranges work correctly with your timezone requirements
- Document your retention policy alignment with Tracer’s 7-year retention
Investigation workflow
When investigating a specific transaction:- Find the validation ID from your transaction logs or Tracer history
- Retrieve full details using GET /v1/validations/
- Review the request snapshot to see the data in the request
- Check matched rules to understand the reason for the decision
- Verify limit status if limits apply
No-match behavior and audit
When a validation runs and no rule matches, Tracer returns a configured default decision instead of treating the empty match as an error. This is a per-request fallback, not an infrastructure resilience strategy. The
DEFAULT_DECISION_WHEN_NO_MATCH environment variable governs the decision (default: ALLOW).
Set
DEFAULT_DECISION_WHEN_NO_MATCH=DENY for fail-closed semantics in high-security deployments. The service logs a warning at startup if this remains at the default ALLOW.tracer_audit_persist_failures_total and the /readyz endpoint to detect these cases.
Quick reference
Key endpoints and retention information.