Documentation
¶
Overview ¶
Package observability holds mast's telemetry surface: the FIXED Prometheus metric registry, and env-gated OTel trace-export setup.
Design contract (docs/observability-design.md):
- Metric names live here and only here. Callers increment pre-declared families through typed methods; they cannot mint new metric names or labels. That is the cardinality-control point (open question #5: specialists/workloads emit events, not metrics).
- The session eventlog is the source of truth; these metrics are a real-time *view* derived from the same event stream the budget meter folds (pkg/budget.Meter.Observe) — Observe here is shaped the same way and is fed from the same loop.
- Session ID is never a metric label (cardinality). Correlation at session grain goes through logs and traces.
- Traces are ADK v2's own span tree; mast decorates, it does not re-invent (see otel.go).
Index ¶
- Constants
- func SetupOTel(ctx context.Context) (shutdown func(context.Context) error, enabled bool, err error)
- type Registry
- func (r *Registry) AddCost(workload string, usd float64)
- func (r *Registry) BudgetTrip(workload string)
- func (r *Registry) HITLPause(workload string)
- func (r *Registry) HITLResume(workload string)
- func (r *Registry) Handler() http.Handler
- func (r *Registry) Observe(ev *session.Event, workload string)
- func (r *Registry) Prime(workload string)
- func (r *Registry) TurnComplete(workload, outcome string)
Constants ¶
const ( OutcomeOK = "ok" OutcomeError = "error" OutcomeBudgetExceeded = "budget_exceeded" )
Turn outcomes for TurnComplete. A fixed vocabulary — free-form outcome strings would be a label-cardinality leak.
const ( TokenKindPrompt = "prompt" TokenKindCandidates = "candidates" )
Token kinds for the mast_tokens_total{kind} label.
Variables ¶
This section is empty.
Functions ¶
func SetupOTel ¶
SetupOTel installs the global OTLP trace exporter + W3C propagator when standard OTel env config asks for it (OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT). Endpoint, headers, protocol details, etc. are all read from the environment by the exporter — mast adds nothing beyond a service.name resource default.
mast does not open custom spans in v0.1: ADK v2's runner emits the unified span tree (session/turn/node/tool), and mast only decorates. This function only makes that tree leave the process.
Returns a shutdown func (flushes the batch exporter) and whether export was enabled. When the env vars are absent it is a no-op: shutdown is non-nil and trivially succeeds.
Types ¶
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is the fixed set of mast metric families. Construct one per process with New and expose it via Handler on the inject listener.
func New ¶
func New() *Registry
New constructs the registry with every base family pre-registered. The underlying prometheus.Registry is private: nothing outside this package can register additional collectors through it.
func (*Registry) AddCost ¶
AddCost accumulates spend (in USD) attributed to a workload. The amount comes from the budget meter — pricing stays in one place; this is only the export surface. Non-positive deltas are ignored.
func (*Registry) BudgetTrip ¶
BudgetTrip records a turn aborted on a budget ceiling.
func (*Registry) HITLPause ¶
HITLPause records a HITL interrupt explicitly, for callers that detect the pause outside the event stream. Callers already feeding events through Observe must not also call this for the same interrupt (Observe counts RequestedInput events itself).
func (*Registry) HITLResume ¶
HITLResume records an operator resume being fed into a session.
func (*Registry) Handler ¶
Handler returns the Prometheus scrape handler for this registry, suitable for mounting at /metrics on an existing mux.
func (*Registry) Observe ¶
Observe folds one runner event into the counters. Shaped like pkg/budget's Meter.Observe so both hooks sit side by side on the event-stream loop. Events without UsageMetadata contribute no model-call or token counts; nil events are ignored. Safe on a nil *Registry so callers can leave telemetry unwired.
func (*Registry) Prime ¶
Prime materializes every family's time series for the given workload at zero, so a scrape sees all base families from process start (before the first turn) and PromQL rate()/increase() have a defined origin. Call once at startup per served workload.
func (*Registry) TurnComplete ¶
TurnComplete records one finished turn with the given outcome (one of the Outcome* constants).
Source Files