telemetry

type FlightRecorder struct {
	// contains filtered or unexported fields
}

type Metrics struct {
	// contains filtered or unexported fields
}

type OTLPConfig struct {
	// Endpoint is the collector address, e.g. "localhost:4317" for gRPC or a
	// URL/host for HTTP. An empty Endpoint disables tracing: Setup installs
	// nothing and returns a no-op shutdown.
	Endpoint string
	// Protocol selects the transport: "grpc" (default) or "http". Any other
	// value is rejected by Setup.
	Protocol string
	// Insecure skips TLS when dialing the collector (development only).
	Insecure bool
	// ServiceName sets the resource service.name attribute. Defaults to
	// "mecatl" when empty.
	ServiceName string
	// Headers are sent with every export request (e.g. auth headers).
	Headers map[string]string
	// Timeout bounds a single export request. Zero uses the exporter default.
	Timeout time.Duration
	// SampleRatio is the parent-based head-sampling ratio in [0,1]. Values <= 0
	// select always-on sampling (the default); values >= 1 also sample every
	// trace. Non-root spans follow their parent's sampling decision.
	SampleRatio float64
	// Version sets the resource service.version attribute when non-empty.
	Version string
	// InstallationID sets the optional mecatl.installation.id resource attribute.
	InstallationID string

	// --- OTLP metrics push (optional; the prometheus reader stays always on) ---
	// MetricsEndpoint is the collector address for an OTLP METRICS push reader
	// (a PeriodicReader over an otlpmetricgrpc/otlpmetrichttp exporter). An empty
	// MetricsEndpoint installs NO periodic reader — the scrape-only path is
	// byte-identical. When set, the periodic reader joins the prometheus reader
	// on the SAME MeterProvider so /metrics AND the push both export the domain
	// instruments.
	MetricsEndpoint string
	// MetricsProtocol selects the metrics transport: "grpc" (default) or "http".
	// Any other value is rejected by Setup.
	MetricsProtocol string
	// MetricsInsecure skips TLS when dialing the metrics collector (dev only).
	MetricsInsecure bool
	// MetricsHeaders are sent with every metrics export request.
	MetricsHeaders map[string]string
	// MetricsTimeout bounds a single metrics export request. Zero uses the
	// exporter default.
	MetricsTimeout time.Duration
	// MetricsPushInterval is the PeriodicReader export cadence. Zero uses the
	// SDK default (60s). A short-lived caller (mecatequi) should set a small
	// interval AND call Shutdown to force a final flush before exit.
	MetricsPushInterval time.Duration
}

type Providers struct {
	// Tracer is the TracerProvider (a no-op provider when tracing is disabled).
	// It is also installed globally via otel.SetTracerProvider, so
	// NewTracing(otel.GetTracerProvider()) picks it up.
	Tracer trace.TracerProvider
	// Meter is the MeterProvider feeding the domain instruments. Pass it to
	// NewMetrics. It is always a real SDK provider (metrics are always on, even
	// when OTLP tracing is disabled) so /metrics has data to serve.
	Meter metric.MeterProvider
	// Registry is the prometheus registry the metrics exporter registers on.
	// Serve it via MetricsHandler at /metrics.
	Registry *prometheus.Registry
	// Shutdown flushes and stops BOTH providers. Always non-nil.
	Shutdown func(context.Context) error
}

type RoleMetrics struct {
	// contains filtered or unexported fields
}

type RuntimeSnapshot struct {
	// Goroutines is the live goroutine count from /sched/goroutines, falling back
	// to runtime.NumGoroutine() when the sample is unavailable.
	Goroutines int `json:"goroutines"`
	// NumCPU is the number of logical CPUs usable by the process.
	NumCPU int `json:"num_cpu"`
	// GOMAXPROCS is the current GOMAXPROCS setting.
	GOMAXPROCS int `json:"gomaxprocs"`

	// HeapAllocsTotalBytes is the CUMULATIVE number of bytes ever allocated to
	// the heap since process start (/gc/heap/allocs) — a monotonic counter that
	// reads 100+ GB on a long-lived process. It is NOT the live heap; live
	// heap-object memory is HeapObjectBytes (heap_object_bytes). Renamed from
	// heap_alloc_bytes, which collided with the LIVE-gauge meaning of Go
	// MemStats.HeapAlloc.
	HeapAllocsTotalBytes uint64 `json:"heap_allocs_total_bytes"`
	// HeapObjects is the count of live-or-unswept heap objects
	// (/gc/heap/objects), not a cumulative allocation count.
	HeapObjects uint64 `json:"heap_objects"`
	// TotalMemoryBytes is all memory mapped by the runtime (/memory/classes/total).
	TotalMemoryBytes uint64 `json:"total_memory_bytes"`
	// HeapObjectBytes is live heap-object memory (/memory/classes/heap/objects).
	HeapObjectBytes uint64 `json:"heap_object_bytes"`

	// GCPauseCount is the number of GC pauses observed (sum of the pause
	// histogram counts). Legitimately 0 before the first GC — see Available.
	GCPauseCount uint64 `json:"gc_pause_count"`
	// GCPauseP99UpperBoundNs is the histogram BUCKET UPPER BOUND containing the
	// ~p99 rank of the GC pause distribution, in nanoseconds, derived from the
	// /gc/pauses histogram. It is a representative bucket bound, NOT an exact
	// quantile — the field name says so deliberately so a Phase-2 consumer does
	// not over-trust the precision. Legitimately 0 before the first GC.
	GCPauseP99UpperBoundNs uint64 `json:"gc_pause_p99_upper_bound_ns"`

	// RSSBytes is the process resident set size in bytes, or 0 when it could not
	// be read (non-Linux, or /proc unavailable). See process_rss_linux.go.
	RSSBytes uint64 `json:"rss_bytes"`

	// UptimeSeconds is the wall-clock age of the process in seconds.
	UptimeSeconds float64 `json:"uptime_seconds"`

	// Available is the set of curated runtime/metrics sample names that were
	// actually present (and thus read) for this snapshot. It makes metric
	// presence EXPLICIT: a name absent here was not published by this toolchain,
	// whereas a name present here was read even if its value happens to be zero.
	// Phase-2 consumers should test membership here rather than inferring absence
	// from a zero field. The runtime counters (Goroutines/NumCPU/GOMAXPROCS/
	// UptimeSeconds) and RSSBytes are always populated and are NOT listed here —
	// Available tracks only the runtime/metrics-derived fields.
	Available []string `json:"available"`
}

type SlowTurn struct {
	// TurnIndex is the 0-based turn index within its run (Event.Turn).
	TurnIndex int
	// DurationMs is the turn's model-call wall-clock duration in milliseconds.
	DurationMs int64
	// TTFTMs is the time-to-first-token in milliseconds (0 if not measured).
	TTFTMs int64
	// InterTokenMaxMs is the worst inter-token gap in milliseconds (0 if not measured).
	InterTokenMaxMs int64
	// EndedAt is the wall-clock time the turn ended.
	EndedAt time.Time
	// Role is the BOUNDED engine role family that produced the turn (one of the
	// Role* constants — "main", "subagent", "member", …). It is a closed enum,
	// never a def/member name or session id, so redaction-by-shape still holds.
	Role string
}

type SlowTurnBuffer struct {
	// contains filtered or unexported fields
}

type Tracing struct {
	// contains filtered or unexported fields
}