Documentation
¶
Overview ¶
Package observability exports bounded execution metadata. Its event types deliberately have no prompt, response, task label, user identity, or raw error fields. Export configuration is separate from inference identity.
Index ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Endpoint string
PublicKey string
SecretKey string
Timeout time.Duration
Release string
}
Config explicitly opts in to metadata export. Endpoint is the full traces URL ending in /api/public/otel/v1/traces, including any self-hosted path prefix. HTTPS is required except for a literal loopback HTTP address. Keys are sent only as HTTP Basic authentication; neither keys nor endpoint enter spans. Timeout defaults to two seconds and may be shortened, but not exceed five.
type Execution ¶
type Execution struct {
StartedAt, EndedAt time.Time
Fingerprint, Provider, Model string
Outcome Outcome
Reused, Durable bool
ContextBytes, TotalContextBytes int
SelectedContext, OmittedContext int
ThisRunUsage, OriginalUsage, AvoidedUsage Usage
CostUSD, AvoidedCostUSD *float64
Generation *Generation
// PhaseMS contains only the fixed internal phases accepted by the exporter.
// It is metadata; it does not create additional spans or expose task labels.
PhaseMS map[string]float64
}
Execution describes one Runner invocation. Reuse exports a root span with zero new usage and no generation child. Original and avoided usage remain metadata, never new billable generation usage. Costs are explicit configured estimates; they do not establish provider invoice savings. Fingerprint is an optional SHA-256 digest, not a task name or revision.
func FromInference ¶ added in v0.10.0
FromInference maps one invocation to content-free execution metadata and validates it before export. It never sends anything or infers human acceptance. Historical generation timing/cache observations do not become fresh spans on reuse. Missing usage remains unknown; configured dollar costs are estimates.
type Exporter ¶
Exporter is optional. A caller must treat errors as telemetry failures and must never retry inference or change the durable generation result for them.
type Generation ¶
type Generation struct {
RuntimeCache *RuntimeCache
StartedAt, EndedAt time.Time
Model string
Outcome Outcome
KnownUsage bool
Usage Usage
CostUSD *float64
// Optional streaming-only client observations. FirstTokenMS is relative to
// the generation start; OutputMS is first-to-last nonempty content chunk.
// These never stand for server compute time or per-token throughput.
FirstTokenMS, OutputMS *float64
TimingBasis string
}
Generation exists only when a provider Generate call was attempted. An uncertain call has KnownUsage=false; missing billing is not reported as zero. The interval measures the whole provider call. First content arrival is available only through explicit streaming measurements below. Model must be a model identifier, never a provider URL or user input.
type Langfuse ¶
type Langfuse struct {
// contains filtered or unexported fields
}
Langfuse is a small OTLP/HTTP JSON exporter with no global telemetry state, environment discovery, background queue, proxy, redirects, or export retries. Its deliberately narrow schema uses the official OTLP JSON mapping, including hexadecimal IDs, numeric enums, and string-encoded 64-bit integers.
func NewLangfuse ¶
NewLangfuse validates configuration before any network access. Constructing an exporter does not create a project, probe the endpoint, or modify a client.
func (*Langfuse) Export ¶
Export sends at most one request after validating the allowlisted metadata. No transport or server response text is included in its errors. Acknowledged export confirms endpoint acceptance, not visibility in a Langfuse dashboard.
func (*Langfuse) Score ¶
Score attaches an explicitly supplied numeric quality value to the root observation using Langfuse's current batch Scores API. It performs no model evaluation and sends no comments, outputs, or identity fields. Acknowledgement means asynchronous API acceptance; the score may not be visible immediately. A caller must only score a Receipt from a successfully acknowledged export.
type Outcome ¶
type Outcome string
Outcome is an allowlisted, content-free execution classification.
const ( Complete Outcome = "complete" Reused Outcome = "reused" Pending Outcome = "pending" BudgetBlocked Outcome = "budget_blocked" Incomplete Outcome = "incomplete" LimitExceeded Outcome = "limit_exceeded" Uncertain Outcome = "uncertain" NotDurable Outcome = "not_durable" Failed Outcome = "error" )
type Receipt ¶
type Receipt struct {
TraceID string `json:"trace_id"`
RootSpanID string `json:"root_span_id"`
GenerationSpanID string `json:"generation_span_id,omitempty"`
}
Receipt correlates exported spans without retaining their content. IDs are returned even on HTTP failure so callers can investigate an ambiguous export; only a nil error indicates that this endpoint acknowledged all spans.
type RuntimeCache ¶ added in v0.5.0
type RuntimeCache struct {
Profile string
CachedTokens, DeviceTokens, HostTokens, StorageTokens *int64
}
RuntimeCache is compute reuse only, separate from billable usage buckets. Nil counters are unreported. The exporter accepts only controlled profiles.
type Usage ¶
type Usage struct {
InputTokens int64
UncachedInputTokens int64
CacheReadTokens int64
CacheWriteTokens int64
OutputTokens int64
ReasoningTokens int64
}
Usage uses Questlock's inclusive input and output totals. Input is partitioned into uncached, cache-read, and cache-write tokens. Reasoning is a subset of output. Exporters must convert these into non-overlapping backend buckets.
Source Files