usage

package
v8.0.14 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 4, 2026 License: MIT Imports: 9 Imported by: 8

Documentation

Index

Constants

View Source
const AutoServiceTier = "auto"

AutoServiceTier is the OpenAI request semantics when service_tier is omitted. OpenAI HTTP handlers set it explicitly, without changing other providers' historical direct-SDK default.

View Source
const DefaultServiceTier = "default"

DefaultServiceTier is retained for direct SDK and non-OpenAI usage callers.

View Source
const TokenAccountingSchemaVersion = 2

TokenAccountingSchemaVersion identifies the canonical token accounting contract.

Variables

This section is empty.

Functions

func ExecutionRequestIDFromContext

func ExecutionRequestIDFromContext(ctx context.Context) string

ExecutionRequestIDFromContext retrieves the execution instance request ID from the context.

func GenerateEnabled

func GenerateEnabled(generate *bool) bool

GenerateEnabled reports whether generation is enabled for the record field. A nil value defaults to true so legacy callers that omit Generate keep the historical behavior.

func GenerateFlag

func GenerateFlag(generate bool) *bool

GenerateFlag returns a pointer suitable for Record.Generate.

func GenerateFromContext

func GenerateFromContext(ctx context.Context) bool

GenerateFromContext returns whether the client requested actual generation. Missing values default to true.

func PublishRecord

func PublishRecord(ctx context.Context, record Record)

PublishRecord publishes a record using the default manager.

func ReasoningEffortFromContext

func ReasoningEffortFromContext(ctx context.Context) string

ReasoningEffortFromContext returns the client-requested reasoning effort stored in ctx.

func RegisterNamedPlugin

func RegisterNamedPlugin(name string, plugin Plugin)

RegisterNamedPlugin registers or replaces a named plugin on the default manager.

func RegisterPlugin

func RegisterPlugin(plugin Plugin)

RegisterPlugin registers a plugin on the default manager.

func RequestedModelAliasFromContext

func RequestedModelAliasFromContext(ctx context.Context) string

RequestedModelAliasFromContext returns the client-requested model name stored in ctx.

func ServiceTierFromContext

func ServiceTierFromContext(ctx context.Context) string

ServiceTierFromContext returns the client-requested service tier stored in ctx.

func StartDefault

func StartDefault(ctx context.Context)

StartDefault starts the default manager's dispatcher.

func StopDefault

func StopDefault()

StopDefault stops the default manager's dispatcher.

func StreamDeliverySupported added in v8.0.14

func StreamDeliverySupported(ctx context.Context) bool

StreamDeliverySupported reports whether an active producer understands delivery.

func StreamDeliveryTracked added in v8.0.14

func StreamDeliveryTracked(ctx context.Context) bool

StreamDeliveryTracked reports whether a consumer will acknowledge delivery.

func StreamFromContext

func StreamFromContext(ctx context.Context) bool

StreamFromContext returns whether the request was executed in streaming mode. Missing values default to false.

func SupportStreamDelivery added in v8.0.14

func SupportStreamDelivery(ctx context.Context) func()

SupportStreamDelivery opts an active producer into early terminal cancellation. The producer must reconcile cancellation with WaitStreamDelivery.

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) string

TraceIDFromContext retrieves the parent inbound HTTP request ID from the context.

func WaitStreamDelivery added in v8.0.14

func WaitStreamDelivery(ctx context.Context) (error, bool)

WaitStreamDelivery waits for the consumer, not the upstream reader, to finish. Producers must close their output channel before waiting to avoid deadlocks.

func WithExecutionRequestID

func WithExecutionRequestID(ctx context.Context, requestID string) context.Context

WithExecutionRequestID attaches a specific execution instance request ID to the context.

func WithGenerate

func WithGenerate(ctx context.Context, generate bool) context.Context

WithGenerate stores whether the client requested actual generation for usage sinks. Missing context values default to true; only an explicit false disables generation.

func WithReasoningEffort

func WithReasoningEffort(ctx context.Context, effort string) context.Context

WithReasoningEffort stores the client-requested reasoning effort for usage sinks.

func WithRequestedModelAlias

func WithRequestedModelAlias(ctx context.Context, alias string) context.Context

WithRequestedModelAlias stores the client-requested model name for usage sinks.

func WithServiceTier

func WithServiceTier(ctx context.Context, tier string) context.Context

WithServiceTier stores the client-requested service tier for usage sinks.

func WithStream

func WithStream(ctx context.Context, stream bool) context.Context

WithStream stores whether the request was executed in streaming mode for usage sinks.

func WithStreamDelivery added in v8.0.14

func WithStreamDelivery(ctx context.Context) (context.Context, func(error))

WithStreamDelivery lets the HTTP consumer acknowledge delivery independently of request cancellation. The consumer must resolve the outcome on every exit.

func WithTraceID

func WithTraceID(ctx context.Context, traceID string) context.Context

WithTraceID attaches the parent inbound HTTP request ID to the context.

func WithoutStreamDelivery added in v8.0.14

func WithoutStreamDelivery(ctx context.Context) context.Context

WithoutStreamDelivery isolates an internal execution from its caller's HTTP acknowledgment. Internal consumers retain EOF-based accounting completion; cancellation and all unrelated context values remain inherited.

Types

type Detail

type Detail struct {
	InputTokens         int64
	OutputTokens        int64
	ReasoningTokens     int64
	CachedTokens        int64
	CacheReadTokens     int64
	CacheCreationTokens int64
	TotalTokens         int64
	TokenBreakdown      TokenBreakdown
	ResponseServiceTier string
}

Detail holds the token usage breakdown.

func EnsureTokenBreakdown

func EnsureTokenBreakdown(detail Detail) Detail

EnsureTokenBreakdown attaches a valid v2 breakdown to legacy or direct SDK usage details without guessing whether reasoning is already inside output.

func EnsureTokenBreakdownForProvider

func EnsureTokenBreakdownForProvider(detail Detail, provider, executorType string) Detail

EnsureTokenBreakdownForProvider attaches a valid v2 breakdown to legacy or direct SDK usage details using the known provider's token semantics. Unknown providers remain unclassified instead of guessing how their buckets overlap.

type Failure

type Failure struct {
	StatusCode int
	Body       string
}

Failure holds HTTP failure metadata for an upstream request attempt.

type Manager

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

Manager maintains a queue of usage records and delivers them to registered plugins.

func DefaultManager

func DefaultManager() *Manager

DefaultManager returns the global usage manager instance.

func NewManager

func NewManager(buffer int) *Manager

NewManager constructs a manager with a buffered queue.

func (*Manager) Publish

func (m *Manager) Publish(ctx context.Context, record Record)

Publish enqueues a usage record for processing. If no plugin is registered the record will be discarded downstream.

func (*Manager) Register

func (m *Manager) Register(plugin Plugin)

Register appends a plugin to the delivery list.

func (*Manager) RegisterNamed

func (m *Manager) RegisterNamed(name string, plugin Plugin)

RegisterNamed registers or replaces a plugin by name.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context)

Start launches the background dispatcher. Calling Start multiple times is safe.

func (*Manager) Stop

func (m *Manager) Stop()

Stop stops the dispatcher and drains the queue.

type Plugin

type Plugin interface {
	HandleUsage(ctx context.Context, record Record)
}

Plugin consumes usage records emitted by the proxy runtime.

type Record

type Record struct {
	// RequestID uniquely identifies this specific model execution instance (UUID v4).
	RequestID string
	// TraceID identifies the parent inbound HTTP request when available (8-character hex).
	TraceID  string
	Provider string
	// BaseURL stores the configured upstream base URL when available.
	BaseURL string
	// ExecutorType stores the concrete executor type that handled the request.
	ExecutorType    string
	Model           string
	Alias           string
	APIKey          string
	SessionID       string
	ParentSessionID string
	AuthID          string
	AuthIndex       string
	// AccessTokenSHA256 identifies the OAuth token version without exposing the token.
	AccessTokenSHA256 string
	AuthType          string
	Source            string
	// ReasoningEffort stores the translated upstream thinking level for request event logs.
	ReasoningEffort string
	// ServiceTier stores the client-requested service tier.
	ServiceTier string
	// RequestServiceTier is a deprecated input-only alias retained for existing
	// plugin callers. It is normalized into ServiceTier and never emitted.
	RequestServiceTier string
	// ResponseServiceTier stores the final tier reported by the upstream response.
	ResponseServiceTier string
	// ResponseModel stores the model name reported by the upstream response, empty when unknown.
	ResponseModel string
	// Generate reports whether the client requested actual generation.
	// nil or true means generation is enabled; only an explicit false disables generation.
	// Use GenerateFlag to set the value and GenerateEnabled to read it with the default.
	Generate *bool
	// Stream reports whether the request was executed in streaming mode.
	Stream      bool
	RequestedAt time.Time
	Latency     time.Duration
	TTFT        time.Duration
	Failed      bool
	Fail        Failure
	Detail      Detail
	// ResponseHeaders stores a snapshot of upstream response headers for usage sinks.
	ResponseHeaders http.Header
}

Record contains the usage statistics captured for a single provider request.

type TokenAccountingQuality

type TokenAccountingQuality string

TokenAccountingQuality describes how confidently a token total can be classified.

const (
	TokenAccountingQualityComplete     TokenAccountingQuality = "complete"
	TokenAccountingQualityInconsistent TokenAccountingQuality = "inconsistent"
	TokenAccountingQualityUnclassified TokenAccountingQuality = "unclassified"
)

type TokenBreakdown

type TokenBreakdown struct {
	SchemaVersion      int                    `json:"schema_version"`
	Quality            TokenAccountingQuality `json:"quality"`
	TotalTokens        int64                  `json:"total_tokens"`
	Input              TokenInputBreakdown    `json:"input"`
	Output             TokenOutputBreakdown   `json:"output"`
	UnclassifiedTokens int64                  `json:"unclassified_tokens"`
}

TokenBreakdown is the canonical, non-overlapping token accounting contract.

func NewIndependentTokenBreakdown

func NewIndependentTokenBreakdown(uncachedInput, cacheRead, cacheWrite, nonReasoningOutput, reasoning, total int64) TokenBreakdown

NewIndependentTokenBreakdown normalizes protocols where uncached input, cache reads, cache writes, non-reasoning output, and reasoning are separate.

func NewPartialSubsetTokenBreakdown

func NewPartialSubsetTokenBreakdown(inputTotal, cacheRead, cacheWrite, outputTotal, reasoning, total int64) TokenBreakdown

NewPartialSubsetTokenBreakdown preserves known subset buckets while assigning an authoritative remainder to the unclassified bucket.

func NewSeparateReasoningTokenBreakdown

func NewSeparateReasoningTokenBreakdown(inputTotal, cacheRead, cacheWrite, nonReasoningOutput, reasoning, total int64) TokenBreakdown

NewSeparateReasoningTokenBreakdown normalizes protocols where cache tokens are included in input totals while reasoning is separate from ordinary output.

func NewSubsetTokenBreakdown

func NewSubsetTokenBreakdown(inputTotal, cacheRead, cacheWrite, outputTotal, reasoning, total int64) TokenBreakdown

NewSubsetTokenBreakdown normalizes protocols where cache tokens are included in input totals and reasoning tokens are included in output totals.

func NewUnclassifiedTokenBreakdown

func NewUnclassifiedTokenBreakdown(total int64) TokenBreakdown

NewUnclassifiedTokenBreakdown preserves an authoritative total without guessing how an unknown protocol partitions it.

func (TokenBreakdown) Valid

func (b TokenBreakdown) Valid() bool

Valid reports whether the breakdown satisfies the v2 accounting invariants.

type TokenInputBreakdown

type TokenInputBreakdown struct {
	TotalTokens      int64 `json:"total_tokens"`
	UncachedTokens   int64 `json:"uncached_tokens"`
	CacheReadTokens  int64 `json:"cache_read_tokens"`
	CacheWriteTokens int64 `json:"cache_write_tokens"`
}

TokenInputBreakdown contains mutually exclusive input token buckets.

type TokenOutputBreakdown

type TokenOutputBreakdown struct {
	TotalTokens        int64 `json:"total_tokens"`
	NonReasoningTokens int64 `json:"non_reasoning_tokens"`
	ReasoningTokens    int64 `json:"reasoning_tokens"`
}

TokenOutputBreakdown contains mutually exclusive output token buckets.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL