Compliance Events in Tyk AI Studio

​

Availability

​

Why Compliance Events

​

Event Schema

• Events without an event_type are silently skipped. This avoids polluting the table with empty records when a script branch builds the event partially.
• severity values outside info|warning|critical are coerced to info.
• event_type on the API query side is limited to 100 characters; any longer is a 400.
• severity on the API query side is validated against the same whitelist; an invalid value is a 400.
• All API queries use GORM parameterized queries, so SQL injection attempts in event_type or severity are treated as literal string matches and return empty results.

​

Server-Side Enrichment

​

Filter Scopes

​

Emitting Events from a Filter Script

tyk := import("tyk")

modified_payload := tyk.redact_pattern(
    input,
    "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
    "[EMAIL_REDACTED]"
)

output := {
    block: false,
    payload: modified_payload,
    message: "",
    compliance_events: [
        {
            event_type: "pii_redacted",
            severity: "info",
            description: "Email addresses redacted from request",
            metadata: { "redacted_types": ["email"] }
        }
    ]
}

​

Behavior

• Recording is asynchronous. Events are queued and written by the analytics pipeline, so filter latency is unaffected.
• Compliance events never affect the block/allow decision. Setting block: false with critical events is legitimate (the filter chose to redact rather than block); setting block: true with no events is also legitimate.
• The list can be empty or omitted. Most filters won’t emit events on every invocation; typically only when a condition fires.
• Events are recorded per filter, per invocation. A single request can produce multiple events from multiple filters.

​

Edge Gateways

1. Filter script on the edge sets compliance_events in its output.
2. The Edge Gateway’s analytics handler (MicrogatewaAnalyticsHandler.RecordComplianceEvents) queues the events to the pulse plugin’s local buffer, which survives a gateway restart.
3. On the next analytics pulse (every 30 seconds by default), events are batched into the gRPC AnalyticsPulse message as ComplianceEventProto entries.
4. The control server’s SendAnalyticsPulse handler reconstructs the compliance event from each entry, preserving LLMID, AppID, UserID, severity, type, description, metadata, vendor, and model name, and persists it.

​

Querying Compliance Events

​

Admin API

GET /api/v1/compliance/events

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://studio.example.com/api/v1/compliance/events?start_date=2026-05-01&end_date=2026-05-14&severity=critical&limit=50"

{
  "events": [
    {
      "id": 1234,
      "app_id": 42,
      "user_id": 0,
      "llm_id": 7,
      "filter_name": "PII Detector",
      "filter_scope": "proxy_request",
      "event_type": "pii_redacted",
      "severity": "info",
      "description": "Email addresses redacted from request",
      "metadata": "{\"redacted_types\":[\"email\"]}",
      "vendor": "openai",
      "model_name": "gpt-4",
      "timestamp": "2026-05-14T09:23:17Z"
    }
  ],
  "total": 1
}

​

SQL

• (app_id, timestamp): composite, for per-app time-bounded queries.
• user_id, llm_id, filter_name, event_type, severity: single-column, for filtering.
• timestamp: for retention sweeps.

SELECT filter_name, event_type, COUNT(*) AS n
FROM compliance_events
WHERE timestamp >= NOW() - INTERVAL '7 days'
  AND severity IN ('warning', 'critical')
GROUP BY filter_name, event_type
ORDER BY n DESC;

​

Dashboard Surfaces

​

Summary Cards

• Critical Events: count over the selected window, with trend arrow. Escalates the card style above COMPLIANCE_EVENTS_CRITICAL_ESCALATE_AT (default 1, since a single critical event already warrants attention).
• Warning Events: count over the selected window, with trend arrow. Escalates above COMPLIANCE_EVENTS_WARNING_ESCALATE_AT (default 20, since warnings are advisory and need to accumulate before they matter).

​

Policy Violations Tab

• Blocked: 4xx proxy logs (existing).
• Flagged: warning and critical compliance events that passed through (new).
• Affected Apps: distinct apps appearing in either source.

​

Filter Events Tab

• Severity totals (info / warning / critical) with a stacked timeline chart.
• Severity and event-type filters (the event-type dropdown is populated from observed values in the window).
• Pagination over the event list.
• Expandable rows showing the raw metadata JSON.
• CSV export wired to GET /compliance/events.

​

App Risk Modal

​

Metrics

aistudio_compliance_events_total{filter_scope, severity, event_type}

​

Suggested Event-Type Conventions

• matched_pattern (string): the substring or regex match that fired the event.
• redacted_types (array of strings): categories of PII or content removed.

​

Migration Notes

• Schema: v2.1 GORM auto-migration creates the compliance_events table on first startup. No manual step required.
• Filter scripts written for v2.0 are forward-compatible. The compliance_events field is optional and ignored if absent.
• Bundled filter library: the ship-with scripts (PII redaction, content blocking, response guardrails) were updated in v2.1 to emit compliance events with the conventions above. Re-import them from the marketplace, or copy from the updated templates in the admin UI, if you want them out of the box.
• Custom analytics handlers: the AnalyticsHandler interface now takes context.Context on its recording methods, including the new RecordComplianceEvents. Custom implementations need to update their signatures; RecordComplianceEvents can be a no-op if you do not consume compliance events.

​

See Also

• Filters: script-level syntax and examples.
• Analytics & Monitoring: the surrounding analytics pipeline and the full metric catalog.
• Edge Gateway: hub-spoke architecture and the analytics pulse that carries edge events to control.
• Tyk AI Studio release notes: the AnalyticsHandler context change and related v2.1.0 SDK updates.