Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

9.1 KB
Raw Blame
---
title: "Schema Fields"
description: "Beacon event entities, optional context, and shared fields"
---

## Field reference

Beacon models each event as an action plus a set of typed entities. The [`event` object and surrounding entities](/concepts/core-concepts#entity-model) describe what happened and who or what participated in that action.

## Entity model

| Entity | Purpose | Common fields |
|--------|---------|---------------|
| `endpoint` | Device and agent context for the machine where telemetry was collected | `hostname`, `os`, `agent_version` |
| `user` | Local operating system user context | `name`, `uid` |
| `harness` | Agent harness that produced the signal | `name`, `version`, `executable_path`, `config_path`, `profile` |
| `origin` | Event origin for local endpoint, cloud, or CI telemetry | `local`, `cloud`, `ci` |
| `run` | CI or ephemeral run context | `provider`, `run_id`, `run_attempt`, `workflow`, `job`, `event_name`, `commit`, `repository`, `branch`, `pr`, `pr_number`, `actor`, `ephemeral` |
| `session` | Conversation or runtime session context | `id`, `working_directory` |
| `error` | Standard error context when an MCP/JSON-RPC/tool operation fails | `type` |
| `jsonrpc` | JSON-RPC request and protocol context for MCP calls | `request.id`, `protocol.version` |
| `network` | Network protocol and transport context | `protocol.name`, `protocol.version`, `transport` |
| `rpc` | RPC response context | `response.status_code` |
| `server` | Peer server context when available | `address`, `port` |
| `tool` | Tool invocation context, including shell-like tools | `name`, `command`, `path` |
| `file` | File activity context | `path`, `operation`, `language`, `diff_hash`, `diff_bytes` |
| `command` | Shell or process execution context | `command`, `exit_code`, `duration_ms` |
| `mcp` | MCP server, tool, method, protocol, resource, and session context | `server`, `tool`, `method.name`, `protocol.version`, `resource.uri`, `session.id` |
| `approval` | Approval or policy decision context | `required`, `decision`, `reason` |
| `handoff` | On a `session.handoff` event, the session this one continues from a [handoff brief](/cli/handoff#linking-a-new-session-to-the-one-it-continues) | `source_harness`, `source_session_id` |
| `share` | On a `session.share_requested` event, the visibility [auto-share](/cli/share#auto-share) asks beacon.sh to publish the session with | `visibility` (`direct`, `private`, `public`) |
| `policy` | Policy metadata when available from a runtime or integration | `id`, `name`, `decision`, `enforcement`, `reason` |
| `prompt` | Prompt text when the source emits it and content handling allows it | `text` |
| `system_context` | On a `session.context` event, what the runtime gave the model outside the conversation. Metadata, so it is kept when content is not; the text is in `gen_ai.system_instructions` | `kind` (`skill_listing`), `source` (`system_prompt`, `transcript`), `skills[].skill_name`, `skills[].skill_name_hash` |
| `content` | Content handling state for the event | `retention`, `included`, `redacted`, `truncated` |
| `gen_ai` | OpenTelemetry GenAI semantic convention context | `agent`, `conversation`, `input`, `output`, `provider`, `request`, `response`, `retrieval`, `system_instructions`, `tool`, `usage`, `workflow` |
| `destination` | Output or validation destination state | `type`, `mode`, `status` |
| `health` | Endpoint or component health state | `component`, `status`, `reason` |
| `user_agent` | Browser that produced a browser chat event, as the browser names itself | `name`, `version` |
| `vcs` | On a `session.commit_linked` event, the commit a session was [linked to](/cli/git), in the OpenTelemetry VCS shape. On a `git.hook_budget_exceeded` event, the [git hook run that ran out of time](/cli/git#hook-runs-that-run-out-of-time) | `ref.head.revision`, `ref.head.name`, `ref.head.type`, `repository.url.full`, `attribution.method`, `attribution.changed_files`, `attribution.matched_files`, `hook.name`, `hook.phase`, `hook.budget_ms`, `hook.elapsed_ms`, `hook.phase_elapsed_ms`, `hook.git_spawns`, `hook.cut_short` |

Top-level `sequence`, `model`, `repository`, `branch`, `message`, `raw`, and `field_truncated` fields add shared context that can apply across multiple entities. For example, a command event can include both `tool` and `command`; a file edit can include `file`, `session`, `repository`, and `branch`; a CI event can include `origin` and `run`; and a GenAI tool call can include both `tool` and nested `gen_ai.tool` metadata.

`sequence` is the emitting writer's monotonic emission counter, used to order events that share a timestamp. See [event ordering](/telemetry-schema/event-schema#event-ordering) for what it does and does not compare across.

For hook-based runtimes, when the runtime payload does not supply a branch, Beacon fills `branch` from the working directory's git checkout by reading `.git/HEAD` directly. No git binary is required, and the field is omitted when the directory is not a git repository or HEAD is detached. Set `BEACON_DISABLE_GIT_METADATA=1` (accepts `1`, `true`, or `yes`) in the runtime's environment to turn off local git metadata enrichment; runtime-provided branch values still pass through.

## GenAI context

When a runtime emits OpenTelemetry GenAI semantic convention attributes, Beacon preserves them under `gen_ai` while also projecting commonly queried values into top-level fields such as `model`, `tool.name`, or `prompt.text`.

| Field | Detail |
|-------|--------|
| `gen_ai.request` | Request settings such as `model`, `max_tokens`, `temperature`, `top_p`, `top_k`, `seed`, `stream`, `choice_count`, `encoding_formats`, and `stop_sequences` |
| `gen_ai.response` | Response metadata such as `id`, `model`, `finish_reasons`, and `time_to_first_chunk` |
| `gen_ai.usage` | Token counters such as `input_tokens`, `output_tokens`, `cache_creation.input_tokens` (with its optional one-hour subset `cache_creation.ephemeral_1h_input_tokens`), `cache_read.input_tokens`, and `reasoning.output_tokens`, plus runtime-reported `cost_usd` |
| `gen_ai.input.messages`, `gen_ai.output.messages` | Message arrays or objects emitted by the runtime |
| `gen_ai.system_instructions` | Instructions given to the model outside the conversation, as a list of parts (`type`, `content`). A skill index on `session.context` has one `text` part per skill, so each skill is limited on its own |
| `gen_ai.tool` | Tool metadata such as `name`, `type`, `description`, `definitions`, and `call.id`, `call.arguments`, or `call.result` |
| `gen_ai.retrieval` | Retrieval context such as `query_text` and `documents` |
| `gen_ai.evaluation` | Evaluation metadata such as `name`, `explanation`, `score.label`, and `score.value` |
| `gen_ai.agent`, `gen_ai.provider`, `gen_ai.workflow` | Runtime-specific agent, provider, and workflow metadata |

## Optional context

Optional context fields add detail when available:

| Field | Detail |
|-------|--------|
| `user` | Local user metadata |
| `origin` | Whether the event came from local endpoint telemetry, cloud telemetry, or CI telemetry |
| `run` | CI provider and run metadata, including repository, branch, commit, workflow, job, actor, and pull-request identifiers |
| `session` | Conversation or runtime session metadata |
| `tool` | Tool name, command, or path metadata |
| `file` | File path, operation, language, diff hash, or diff byte counts |
| `command` | Shell command, exit code, or duration metadata |
| `mcp` | MCP server, tool, method, protocol, resource, or session metadata |
| `jsonrpc`, `rpc`, `network`, `server`, `error` | MCP client-span context projected from OpenTelemetry semantic conventions when available |
| `approval` | Approval requirement, decision, or reason |
| `handoff` | The session a handed-off session continues: source harness and session id |
| `share` | Auto-share request visibility |
| `policy` | Policy ID, name, decision, enforcement mode, or reason |
| `content` | Content inclusion, redaction, and truncation state |
| `gen_ai` | OpenTelemetry GenAI request, response, usage, message, tool, retrieval, evaluation, provider, and workflow metadata |
| `destination` | Output destination state, such as Wazuh localfile validation |
| `health` | Component health status |
| `user_agent` | Browser name and major version for browser extension events, such as `Microsoft Edge` or `Brave`. See [Chromium browsers](/runtimes/browser-extension-chromium#which-browser-an-event-came-from) |
| `vcs` | Commit id, branch, and remote URL (credentials removed) of a commit linked to the session, with how many of its files the session wrote. See [`beacon git`](/cli/git#runtime-log-events) |
| `model`, `repository`, `branch`, `message`, `raw`, `field_truncated` | Additional runtime context and truncation metadata |

## Related

<Columns cols={2}>
  <Card title="Unified telemetry schema" icon="code" href="/telemetry-schema/event-schema">
    Return to the schema overview.
  </Card>
  <Card title="Schema normalization" icon="arrows-rotate" href="/telemetry-schema/normalization">
    See how source fields map into the event contract.
  </Card>
  <Card title="Schema examples" icon="code" href="/telemetry-schema/examples">
    Inspect example events and content handling behavior.
  </Card>
</Columns>