Skip to main content

​
Why the schema exists

AI agent activity is emitted from many places: local developer machines, CI jobs, cloud-hosted coding agents, SDK integrations, OpenTelemetry exporters, and runtime-specific hook systems. Each source has its own event names, payload shapes, identifiers, and ideas about what counts as a prompt, tool call, command, approval, file change, or policy decision. Beacon’s unified telemetry schema turns those different signals into one normalized event model. The goal is to make agent activity searchable, detectable, and explainable across local, CI, and cloud environments without requiring every downstream rule, dashboard, or SIEM parser to understand each runtime’s native format.

​
What normalization provides

The schema gives every event a consistent backbone:

​
Provenance: how Beacon knows what it wrote

Normalizing many runtimes into one event shape has a cost: a field that reads the same for every source hides how differently the sources behave. event.action is the field where that matters most. A Claude Code PermissionRequest hook hands Beacon a typed payload naming the operation. A Codex OTLP log record hands it a body string that Beacon classifies by pattern, with a fallback for records that match nothing. Both produce an event.action, and without a marker a detection cannot tell a report from a reading. Two optional fields carry that context. harness.collection_method describes the mechanism that carried the event off the runtime: event.fidelity describes the specific action on the event: The two are independent. One OTLP stream carries both kinds: a record that declares its event.name is observed, while a record carrying only prose is inferred. Both are collection_method: otlp. Both fields are optional, and omitted rather than written empty. Events Beacon emits about itself, such as health heartbeats and self-update results, have no collecting harness and no source action to be faithful to, so they carry neither. Rules can match on both, so a detection that needs certainty can require it:
Approvals are the clearest case for that. Several runtimes expose a pre-tool notification but no approval hook, and Beacon turns the former into an approval.allowed event so approval-shaped detections still have something to match. Those events are inferred: nothing was gated, a tool call was seen. Anything counting real operator decisions should exclude them.

​
Required fields

event.id is written alongside these: a deterministic UUID identifying the event, described under event identity. It is not required, so events written by earlier agent versions remain valid.

​
Event ordering

Two events can only be reasoned about together if you can tell which came first, so the schema carries two ordering fields. sequence numbers one writer’s stream, not the log as a whole. The hook adapter runs as a fresh short-lived process per hook and the collector exporter runs as one long-lived export loop, so neither can see the other’s counter, and a hook event numbered 1 may well have happened after an exporter event numbered 900. Order by timestamp first and use sequence only to separate events that tie on it, most often the datapoints of a single metric export, which all carry that export’s collection instant. Do not order events by their position in the log. Append order is not emission order: a hook writes synchronously the moment it intercepts a tool call, while the exporter writes on its export interval, so an event that happened earlier routinely lands in the file later. beacon scan and the dashboard’s detection view sort the log by (timestamp, sequence) before evaluating correlation rules for exactly this reason.

​
How it extends OpenTelemetry

Beacon accepts OpenTelemetry attributes, including the GenAI semantic conventions, and projects them into fields that are easier to query across agent runtimes. OpenTelemetry context is preserved under gen_ai where available, while commonly investigated values are also normalized into Beacon fields such as model, tool.name, prompt.text, command.command, file.path, and gen_ai.usage. This lets teams use OpenTelemetry-native data without giving up a security-focused vocabulary for agent behavior. A detection can ask for a normalized command, MCP tool, approval decision, or file operation instead of branching on every source runtime’s attribute names.

​
Why it matters

The normalized schema is the contract between collection, detection, investigation, and forwarding. It lets Asymptote:
  • Correlate agent activity across local endpoints, ephemeral CI jobs, and cloud agent sessions.
  • Write detections once against stable fields instead of per-runtime payloads.
  • Preserve source-specific OpenTelemetry and GenAI context without forcing downstream tools to parse raw traces.
  • Keep prompt, tool, command, file, approval, policy, and token-usage telemetry comparable across supported harnesses.
  • Say how each event was collected and how sure Beacon is of its action, so a consumer can weigh a runtime-reported fact differently from a derived one.
  • Forward one predictable JSONL shape into customer-managed analytics, SIEM, object-storage, and review workflows.

Schema normalization

See how OTLP attributes and hook payloads map into Beacon fields and actions.

Schema fields

Review entities, optional context, and shared top-level fields.

Schema examples

Inspect example events and content handling behavior.

Data inventory

Review runtime coverage and the event fields Beacon can write when a source provides them.

Core Concepts

Review the glossary behind events and entities.

Open Source Architecture

See how runtime telemetry becomes normalized JSONL.

Detections

See how events are evaluated by threat rules.

Wazuh

Configure Wazuh ingestion for Beacon events.

Datadog

Configure Datadog Agent custom log collection for Beacon events.

Sumo Logic

Configure Sumo Logic HTTP Source forwarding for Beacon events.