Runtime Events

Since: 1.1.0 · Feature ID: F-EXP-01

Gavio runtime events are the public export surface for request execution. They reuse the Inspector event envelope, so the Inspector, JSONL exporters, OpenTelemetry span exporters, tests, and integration recipes all share one event stream.

The default export mode is metadata-only. Runtime exporters remove content-bearing fields before writing events:

• messages
• content
• diff

Python

from gavio import Gateway, JsonlRuntimeExporter

gw = (
    Gateway.builder()
    .dev_mode(True)
    .exporter(JsonlRuntimeExporter("runtime-events.jsonl"))
    .build()
)

JavaScript

import { Gateway, jsonlRuntimeExporter } from 'gavio'

const gw = new Gateway({
  devMode: true,
  exporters: [jsonlRuntimeExporter({ path: 'runtime-events.jsonl' })],
})

Java

Gateway gateway = Gateway.builder()
    .devMode(true)
    .exporter(new JsonlRuntimeExporter(Path.of("runtime-events.jsonl")))
    .build();

Adding an exporter enables metadata-mode events and does not start the Inspector HTTP server unless inspection is configured separately.

OpenTelemetry

Observability + OTel (v1.3.0, F-OBS-07) maps runtime events into OpenTelemetry-style span JSON without adding mandatory OTel dependencies.

Python

from gavio import Gateway, OtelSpanExporter

gw = Gateway.builder().exporter(
    OtelSpanExporter("otel-spans.jsonl", service_name="checkout-api")
).build()

TypeScript

import { Gateway, otelSpanExporter } from 'gavio'

const gw = new Gateway({
  exporters: [otelSpanExporter({
    path: 'otel-spans.jsonl',
    serviceName: 'checkout-api',
  })],
})

Java

Gateway gateway = Gateway.builder()
    .exporter(new OtelSpanExporter(Path.of("otel-spans.jsonl"), "checkout-api"))
    .build();

Python can also convert existing runtime-event JSONL:

gavio events convert --from runtime-events.jsonl --to otel-json --service-name checkout-api

Event Types

Type	Purpose
trace.start	Request started
interceptor.before.*	Pre-call interceptor lifecycle
provider.call.*	Provider attempt lifecycle
interceptor.after.*	Post-call interceptor lifecycle
governance.event	Budget, drift, or policy signal
trace.error	Request failed
trace.end	Request completed

The emitted shape is covered by spec/GavioOtelSpan.schema.json and the shared test-vectors/otel/spans.json vectors.