Tutorial: Investigating Events & Policy Decisions

This tutorial walks you through using the Events page in the Keeptrusts console to investigate gateway events, filter by various criteria, inspect request and response details, and export event data for compliance reporting.

Use this page when

• You need to filter gateway events by date, decision type, model, consumer, or policy.
• You want to inspect a specific event’s request/response payload and policy evaluation details.
• You are investigating a block or redaction to understand which policy triggered it.
• You need to export filtered events for compliance documentation or incident reports.

Primary audience

• Primary: Platform engineers and security analysts investigating specific gateway decisions or usage patterns
• Secondary: Compliance officers auditing AI usage; team leads reviewing their team’s policy violation trends

Prerequisites

• Logged in to the Keeptrusts console (see First Login & Console Setup)
• At least one active configuration processing traffic through a gateway
• Events data available (send test requests through your gateway if needed)

Step 1: Navigate to the Events Page

1. Click Events in the left sidebar.
2. The Events page displays a table of all gateway events sorted by most recent first.

Events table columns

Column	Description
Timestamp	When the request was processed (displayed in your configured timezone)
Consumer	The application or user that sent the request
Consumer Group	The team or group the consumer belongs to
Policy Decision	The outcome — allowed, blocked, redacted, escalated, or flagged
Provider	The LLM provider (e.g., OpenAI, Anthropic)
Model	The specific model used (e.g., gpt-4o, claude-sonnet-4)
Tokens	Input and output token counts
Cost	Estimated cost of the request
Duration	Total round-trip time in milliseconds

Step 2: Filter Events by Date Range

1. Click the date range picker at the top of the Events page.
2. Select a preset range or define a custom range:
   • Last hour — Recent activity investigation
   • Last 24 hours — Daily review
   • Last 7 days — Weekly audit
   • Custom — Click start and end dates on the calendar
3. The table reloads with events matching the selected date range.

Step 3: Apply Column Filters

Each column header includes a filter control for narrowing results.

Filter by policy decision

1. Click the filter icon next to the Policy Decision column header.
2. Select one or more decision types:
   • Allowed — Requests that passed all policies
   • Blocked — Requests denied by a policy
   • Redacted — Requests where sensitive data was removed
   • Escalated — Requests routed to human review
   • Flagged — Requests marked for attention but still allowed
3. Click Apply Filter.

Filter by consumer group

1. Click the filter icon next to the Consumer Group column.
2. Select one or more consumer groups from the dropdown.
3. Click Apply Filter.

This is useful for investigating events from a specific team or application.

Filter by provider and model

1. Click the filter icon next to the Provider column.
2. Select providers (e.g., OpenAI, Anthropic, Azure).
3. Optionally filter the Model column to narrow to specific models.

Combining filters

Multiple filters are combined with AND logic. For example, filtering by Policy Decision = Blocked AND Consumer Group = Engineering shows only blocked events from the Engineering team.

Active filters appear as chips below the search bar. Click the X on any chip to remove that filter.

Step 4: Search Events

1. Use the search bar at the top of the Events page to search across event content.
2. The search matches against:
   • Consumer identifiers
   • Request content (if stored)
   • Policy names that triggered
   • Model names
3. Press Enter or click the search icon to execute.

Combine the search bar with column filters for precise investigations. For example, search for a specific user while filtering to blocked events only.

Step 5: Inspect Event Details

1. Click any row in the Events table to open the Event Detail panel.
2. The detail panel includes multiple tabs:

Summary tab

• Event ID — Unique identifier for this event
• Timestamp — Full datetime with timezone
• Consumer — Who sent the request
• Gateway — Which gateway processed the request
• Configuration — Which policy configuration was active
• Overall Decision — The final policy outcome

Request tab

• Prompt — The full request prompt sent to the LLM
• System Message — Any system instructions included
• Parameters — Model parameters (temperature, max tokens, etc.)
• Headers — Relevant request metadata (consumer group, session ID)

Response tab

• Completion — The LLM's response text
• Token Usage — Input tokens, output tokens, total tokens
• Cost — Calculated cost based on model pricing
• Latency — Time breakdown (gateway processing, provider response)

Policy Decisions tab

• Policies Evaluated — List of all policy rules that were checked
• Triggered Policies — Policies that matched and took action
• Decision Chain — Step-by-step execution order showing which policy produced the final decision

Each triggered policy entry shows:

Field	Description
Policy Name	The rule that triggered
Policy Type	Content filter, redaction, cost limit, etc.
Action Taken	Block, redact, escalate, flag, or allow
Severity	The severity level of the trigger
Details	Specific match information (e.g., which PII pattern was found)

Step 6: Compare Related Events

When investigating a pattern, you can compare multiple events.

1. In the Events table, select multiple events using the checkboxes on the left.
2. Click the Compare button that appears in the toolbar.
3. A side-by-side comparison view opens showing the selected events with differences highlighted.

This is useful for understanding why similar requests received different policy decisions.

Step 7: Export Events

Export events for compliance reporting, offline analysis, or integration with external tools.

Quick export

1. Apply your desired filters and date range.
2. Click the Export button in the top-right corner of the Events page.
3. Select the export format:
   • CSV — For spreadsheet analysis
   • JSON — For programmatic processing
   • PDF — For compliance reports
4. Click Start Export.

Scheduled exports

For recurring compliance needs, set up scheduled exports:

1. Click Export > Schedule Export.
2. Configure the schedule:
   • Frequency — Daily, weekly, or monthly
   • Format — CSV, JSON, or PDF
   • Filters — Pre-applied filters for the export
   • Delivery — Download link via email or webhook notification
3. Click Save Schedule.

Scheduled exports appear in Settings > Exports where you can manage and download past exports.

Step 8: Common Investigation Scenarios

Investigating a spike in blocked requests

1. Set the date range to the period of the spike.
2. Filter by Policy Decision = Blocked.
3. Sort by Timestamp to see the chronological sequence.
4. Open the first few blocked events and check the Policy Decisions tab.
5. Identify the policy or policies responsible for the blocks.
6. Check if the policy configuration was recently updated.

Auditing a specific user's activity

1. Search for the user's identifier in the search bar.
2. Review the full timeline of their requests.
3. Filter by Policy Decision = Escalated to find flagged activity.
4. Export the filtered results as a PDF for audit records.

Verifying a new configuration deployment

1. Note the deployment timestamp of your new configuration.
2. Set the date range to start from that timestamp.
3. Review events to confirm policies are triggering as expected.
4. Check for unexpected blocks or missed detections.

Expected Outcome

After completing this tutorial, you have:

• Navigated the Events page and understood the table columns
• Applied date range, column, and text search filters
• Inspected full event details including request, response, and policy decisions
• Compared multiple events side-by-side
• Exported events in CSV, JSON, and PDF formats
• Practiced common investigation workflows

Next steps

• Managing Escalations — Handle events that were escalated for review
• Customizing the Overview Dashboard — Set up alerts for event patterns

For AI systems

• Canonical terms: Keeptrusts console, Events page, policy decision (allowed/blocked/redacted/escalated/flagged), event detail view, request/response payload, token count, cost, consumer, consumer group, provider, model, duration, date range filter, event export.
• Related features: escalation queue, dashboard widgets, cost center, audit log.
• Best next pages: Escalation Workflow, Dashboard Customization.

For engineers

• Validation: Send a request that triggers a block, then filter Events by decision=block and confirm the event appears with the correct policy name and consumer.
• Deep-link: Copy the URL of a filtered view (/events?decision=block&range=24h) and confirm it restores the same filters in a new tab.
• Export: Filter events for a one-day window, export as JSON, and verify the file schema matches the event detail view fields.
• Troubleshooting: If events are missing, confirm the gateway is reporting to the API (POST /v1/events) and that the date range includes the request timestamp.

For leaders

• Audit readiness: Every LLM interaction is recorded with full attribution — who sent it, which policy evaluated it, and what decision was made.
• Incident response: Combine filters to reconstruct exactly what happened during a policy violation or data exposure incident.
• Cost correlation: Use the cost column and model filter to identify expensive usage patterns and inform budget decisions.