Documentation
¶
Overview ¶
Package telemetry wires amoxtli to OpenTelemetry. It exposes a shared tracer and meter under a single instrumentation scope, plus lazily-created metric instruments for the things worth watching in a RAG library: search latency, LLM cost (call count, latency, token usage) and image description volume (descriptions produced, cache hits, failures).
Instrumentation is always on but cheap: when the process has not installed a TracerProvider/MeterProvider, OpenTelemetry's global no-op providers are used and every span/measurement is discarded at near-zero cost. A consumer opts into real telemetry simply by installing the OTel SDK providers in their program; nothing in amoxtli needs to change.
Index ¶
Constants ¶
const ( // AttrOperation labels an LLM operation (chat_completion, embeddings, ...). AttrOperation = "amoxtli.llm.operation" // AttrTokenKind distinguishes prompt vs. completion tokens on the token // counter. AttrTokenKind = "amoxtli.llm.token_kind" // AttrQueryLength is the character length of a search query (queries // themselves are not recorded, to avoid leaking user content). AttrQueryLength = "amoxtli.search.query_length" // AttrResultCount is the number of results returned by a search. AttrResultCount = "amoxtli.search.result_count" // AttrVisionOutcome labels how an image description ended: "ok", // "error" or "rejected" (refused before any call, e.g. an oversized // image). AttrVisionOutcome = "amoxtli.vision.outcome" // AttrVisionCacheResult labels a description cache lookup: "hit" or // "miss". AttrVisionCacheResult = "amoxtli.vision.cache_result" )
Attribute keys used across amoxtli spans and metrics.
const ( VisionOutcomeOK = "ok" VisionOutcomeError = "error" VisionOutcomeRejected = "rejected" VisionCacheHit = "hit" VisionCacheMiss = "miss" )
Values of AttrVisionOutcome and AttrVisionCacheResult.
const ScopeName = "github.com/bornholm/amoxtli"
ScopeName is the instrumentation scope reported on every span and metric.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Instruments ¶
type Instruments struct {
// LLMCalls counts LLM calls, tagged by operation.
LLMCalls metric.Int64Counter
// LLMDuration is the LLM call latency in seconds, tagged by operation.
LLMDuration metric.Float64Histogram
// LLMTokens counts tokens consumed, tagged by operation and token kind.
LLMTokens metric.Int64Counter
// SearchDuration is the search latency in seconds.
SearchDuration metric.Float64Histogram
// SearchResults counts results returned across searches.
SearchResults metric.Int64Counter
// VisionDescriptions counts image descriptions produced, tagged by
// outcome.
VisionDescriptions metric.Int64Counter
// VisionDescriptionDuration is the image description latency in seconds.
VisionDescriptionDuration metric.Float64Histogram
// VisionCacheLookups counts description cache lookups, tagged by result
// (hit or miss).
VisionCacheLookups metric.Int64Counter
}
Instruments holds the metric instruments amoxtli records into. They are created once against the global meter; if instrument creation fails (which it should not with the no-op or a well-formed provider) the field is left nil and recording against it is silently skipped by the helpers below.
func Metrics ¶
func Metrics() *Instruments
Metrics returns the shared, lazily-initialised metric instruments. The first call builds them against the global meter; subsequent calls return the same set. It never returns nil.
Source Files