Documentation
¶
Overview ¶
Package telemetry owns the gateway's observability export vocabulary: the Prometheus metric names, their labels, and the mapping from a completed request's usage record onto them. Other seams record their existing measurements through this package; none of them names a metric itself.
Labels never carry a caller identity. A metric labeled by account or key would leak per-tenant activity to every scraper and grow without bound, so the label set stops at provider, model, protocol, operation, and outcome.
Index ¶
- Constants
- func AnnotateSpanTimings(ctx context.Context, overheadMS, ttftMS int64)
- func ContextWithTracing(ctx context.Context, t *Tracing) context.Context
- func StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func TracesConfigured() bool
- type Metrics
- type Tracing
Constants ¶
const ( SpanRequest = "starport.request" SpanRoutePlan = "starport.route_plan" SpanAttempt = "starport.attempt" SpanProviderCall = "starport.provider_call" )
Span names the tracer owns. Every span a request produces carries one of these; no other package names a span.
const ( AttrProvider = "starport.provider" AttrModel = "starport.model" AttrAttempt = "starport.attempt_number" AttrOverheadMS = "starport.overhead_ms" AttrTTFTMS = "starport.ttft_ms" )
Span attribute keys the tracer owns.
Variables ¶
This section is empty.
Functions ¶
func AnnotateSpanTimings ¶
AnnotateSpanTimings attaches the gateway-owned latency measurements to the span already on the context. A zero value carries no information, so only positive measurements land.
func ContextWithTracing ¶
ContextWithTracing carries the tracer into the request context, where the routing and execution seams start their spans without compositional wiring.
func StartSpan ¶
func StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
StartSpan starts a named span under the context's tracer. Without one, it returns the context unchanged and a span that records nothing.
func TracesConfigured ¶
func TracesConfigured() bool
TracesConfigured reports whether the standard OpenTelemetry environment names an OTLP endpoint. The exporter itself reads the same variables, so this answers only the on-or-off question.
Types ¶
type Metrics ¶
type Metrics struct {
// contains filtered or unexported fields
}
Metrics is the gateway's Prometheus surface. A nil *Metrics observes nothing and serves nothing, so every caller may hold one unconditionally.
func NewMetrics ¶
func NewMetrics() *Metrics
NewMetrics builds the metric vocabulary on its own registry. The gateway's scrape serves exactly what the gateway registered: no process collectors arrive by side effect, and two instances never collide in a shared default.
func (*Metrics) ObserveBudgetRefusal ¶
ObserveBudgetRefusal counts one pre-flight budget refusal. It stands apart from ObserveUsage because a refused request never reaches the proxy and writes no usage record.
func (*Metrics) ObserveUsage ¶
ObserveUsage maps one completed request's usage record onto the metric vocabulary. The record already carries every measurement the proxy and execution seams took, so this is the one call a request path makes.
func (*Metrics) ObserveUsageExportDrops ¶
ObserveUsageExportDrops counts records the export sink could not deliver. The counter carries no labels: a drop is a gap in the analytics copy, and which target dropped it is already fixed by configuration.
func (*Metrics) ObserveWebhookDeadLetters ¶
ObserveWebhookDeadLetters counts events the dispatcher could not deliver. Like the export counter, it carries no labels: the endpoint set is fixed by configuration.
type Tracing ¶
type Tracing struct {
// contains filtered or unexported fields
}
Tracing owns the tracer a deployment exports spans through. A nil *Tracing starts no spans, extracts nothing, and shuts down cleanly, so every caller may hold one unconditionally.
func NewTracing ¶
NewTracing builds a tracer that exports over OTLP HTTP. The exporter reads the standard OTEL_EXPORTER_OTLP_ENDPOINT variables itself; call this only when TracesConfigured reports true, so an unconfigured deployment never dials a default endpoint.
func NewTracingWithExporter ¶
func NewTracingWithExporter(exporter sdktrace.SpanExporter) *Tracing
NewTracingWithExporter builds a tracer on a synchronous exporter. Tests use it with an in-memory exporter to read finished spans deterministically.
Source Files