# Script Variables Reference
Kelora exposes several built-in variables to Rhai scripts. Their availability depends on which stage is executing (per-event filters/execs, span hooks, begin/end hooks, etc.). Use this page whenever you need to know which data is in scope.
## Stage Overview
| `--filter`, `--exec`, `--exec-file` | `line`, `e`, `meta`, `conf` | Per-event context. `e` is writable; the others are read-only. |
| `--filter` / `--exec` with `--window` | `line`, `e`, `meta`, `conf`, `window` | Adds the sliding `window` array (current event at index `0`; read-only). |
| `--begin` | `conf` | Map to seed configuration before events arrive. Read-only. |
| `--end` | `metrics`, `conf` | Inspect final tracker totals in `metrics`; both bindings are read-only. |
| `--span-close` | `span`, `metrics`, `conf` | Summarises the closed span with per-span data (`span`) and cumulative totals (`metrics`). All read-only. |
> Reading a variable that does not exist in the current stage raises a Rhai error. Variables listed here are populated with meaningful data (individual fields inside maps may still be `()`). Other globals such as `line`/`e` exist behind the scenes for compatibility but start empty in stages where they are not useful.
## Common Variables
### `line`
- Type: `String`
- Snapshot of the text the parser captured for the current record. Structured formats strip trailing newlines before storing it, `-f raw` preserves every byte (including terminators), and `--multiline` reflects the chunk assembled by the multiline stage. Present in every stage and read-only.
- You’ll also see the same text at `meta.line`; that copy travels with saved metadata (window snapshots, span hooks, cloned `meta` values) so the original record is still available later on.
### `e`
- Type: `Map`
- Event map during per-event stages. Mutating `e` inside `--exec` updates the emitted event; setting a field to `()` removes it; assigning `e = ()` clears the entire event. Writable.
### `meta`
- Type: `Map`
- Metadata derived from the pipeline and span system. Attempting to mutate `meta` fields has no effect; use event fields on `e` for custom annotations instead. Read-only.
| `line` | `String` | Same as the standalone `line` variable. |
| `line_num` | `Int` | 1-based line number when input comes from files. |
| `filename` | `String` | Source filename, if known. |
| `span_status` | `String` | `"included"`, `"late"`, `"unassigned"`, or `"filtered"` when spans are enabled. Missing otherwise. |
| `span_id` | `String` or `()` | Span identifier for the current event. |
| `span_start` / `span_end` | `DateTime` or `()` | Span bounds for the current event. |
### `conf`
- Type: `Map`
- Configuration produced by `--begin` and CLI options; the map is frozen so mutation attempts are ignored. Read-only.
## Span Hooks (`--span-close`)
### `span`
- Type: `Span` (custom Rhai type)
- Binding available only in `--span-close`. Read-only.
| `span.id` | `String` | Unique span identifier (`#0`, `#1`, ... for count spans; `2024-01-15T10:00:00Z/5m` for time spans). |
| `span.start` / `span.end` | `DateTime` or `()` | Span boundary timestamps (time spans only). |
| `span.size` | `Int` | Number of events that survived filters and entered the span. |
| `span.events` | `Array<Map>` | Copy of each included event, with helper fields (`line`, `line_num`, `filename`, `span_status`, `span_id`, `span_start`, `span_end`). Read-only. |
| `span.metrics` | `Map` | Per-span deltas computed from `track_*()` calls since the span opened; zero-delta keys are omitted. Read-only.
> `--span-close` runs without a "current event", so `e` and `meta` are empty. Inspect `span.events` when you need per-event details from inside the close hook.
### `metrics` vs `span.metrics`
- `span.metrics`: Only the delta accumulated while the span was open. After the hook runs, Kelora resets the baseline for the next span; mutations are discarded. Read-only.
- `metrics`: The global tracker map used across the entire run (the same map exposed to `--end`). Values persist between spans and reflect cumulative totals; update via `track_*()` calls, not direct assignment. Read-only.
## Windowed Scripts
- `window`: Present when using `--window` features. It is an array of event maps representing the sliding window, with `window[0]` being the current event followed by prior events retained by the window manager. Read-only.
## Begin / End Hooks
- `--begin`: Runs before any event is parsed. `e` and `meta` start empty; use this stage for initialization and configuration population (`conf`).
- `--end`: Receives the final `metrics` map so you can report overall totals after processing completes.