Events and Traces

Everything Omnodex captures is represented as a trace event. Events are the fundamental unit of the system - every other feature (detection, dashboards, reports) is built on top of the event stream.

Event Structure

Every event contains:

Field	Description
id	Unique identifier for this event
timestamp	When the event occurred (ISO 8601)
sessionId	Which agent session produced this event
kind	The interceptor that captured it (e.g., claude-code-hook, codex-hook)
type	What type of event this is (e.g., tool.invoked, session.start)
payload	The event-specific data (tool name, parameters, result, etc.)

Event Types

Type	Description
session.start	An agent session began
session.end	An agent session ended
tool.invoked	A tool was called by the agent
tool.result	A tool returned a result

The tool.invoked type is the most common. Its payload includes the tool name, the parameters the agent passed, and (when available) the result.

Sessions

Events are grouped into sessions. A session represents a single agent execution - from when the user starts the agent to when it finishes.

Sessions provide context for analysis: a tool call that looks suspicious in isolation might be perfectly normal in the context of what the agent was asked to do.

The Event Log

Events are stored in an append-only JSONL (JSON Lines) file. Each line is one complete event as JSON.

{"id":"evt_001","timestamp":"2026-05-16T10:00:00Z","sessionId":"sess_abc","kind":"claude-code-hook","type":"tool.invoked","payload":{"tool":"Read","params":{"file_path":"/etc/hosts"}}}

This format is:

• Human-readable - You can inspect it with standard text tools (cat, grep, jq)
• Appendable - New events are added to the end without modifying existing data
• Streamable - Consumers can tail the file for real-time updates
• Portable - Standard JSON, no proprietary format

Next Steps

• How Omnodex Works - The full pipeline architecture
• Event Schema Reference - Complete schema documentation