usage/usage.go (package usage)
Source: sdks/go/usage/usage.go. Back to the Go SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class Builder
Builder assembles a Usage Event.
Builder.At
At(t time.Time) *Builder
At overrides occurred_at.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
t | time.Time | yes | Time of the consumption, stored in UTC. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Build
Build() (eai.UsageEvent, error)
Build validates the event against the Usage Event v1 contract.
This element takes no parameter.
Returns: (eai.UsageEvent, error). A UsageEvent: UsageEvent is the Usage Event v1 contract (contracts/v1/usage-event.schema.json). The error is a typed error of the SDK, nil on success.
Raises: error.
Builder.Estimated
Estimated(amount string, currency string) *Builder
Estimated sets the estimated cost (decimal string).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
amount | string | yes | Exact decimal amount as a string, for example 0.0042. | |
currency | string | yes | ISO 4217 currency code, for example EUR. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Execution
Execution(agentID string, sessionID string, runID string, taskID string) *Builder
Execution sets agent, session, run and task ids.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
agentID | string | yes | Agent that consumed; empty leaves agent_id null. | |
sessionID | string | yes | Session of the consumption; empty leaves session_id null. | |
runID | string | yes | Run that consumed; empty omits run_id. | |
taskID | string | yes | Task of the consumption; empty leaves task_id null. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.ID
ID(id string) *Builder
ID overrides the event id.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | string | yes | Event identifier used instead of the generated ue-<random> one. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Label
Label(k string, v string) *Builder
Label adds a label.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
k | string | yes | Name of the label. | |
v | string | yes | Value of the label, up to 256 characters. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Lang
Lang(l string) *Builder
Lang selects the language of validation messages (en, fr).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
l | string | yes | Language of the Build messages, en or fr. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Measured
Measured(amount string, currency string) *Builder
Measured sets the measured cost and marks the event measured.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
amount | string | yes | Exact decimal amount as a string, for example 0.0042. | |
currency | string | yes | ISO 4217 currency code, for example EUR. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Model
Model(provider string, modelID string, deploymentID string, region string) *Builder
Model sets provider, model, deployment and region.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
provider | string | yes | Provider that served the call; required by the contract. | |
modelID | string | yes | Identifier of the model that served the call. | |
deploymentID | string | yes | Deployment of the model; empty omits deployment_id. | |
region | string | yes | Processing region, for example eu-west-1. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Pricing
Pricing(priceCardID string, version string, currency string, effectiveAt time.Time) *Builder
Pricing sets the price applicable at call time.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
priceCardID | string | yes | Price card used; empty omits price_card_id. | |
version | string | yes | Version of the pricing (pricing_version). | |
currency | string | yes | ISO 4217 currency of the price card. | |
effectiveAt | time.Time | yes | Time from which the price applies, stored in UTC. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Project
Project(projectID string, environment string) *Builder
Project sets project_id and environment.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
projectID | string | yes | Project of the consumption; empty omits project_id. | |
environment | string | yes | Environment of the consumption; empty omits environment. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.TokenTotals
TokenTotals(input int64, output int64, cachedInput int64, reasoning int64) (*Builder, error)
TokenTotals follows the FinOps token rule: input already includes cached, output already includes reasoning (provider totals, the sub counts are never added on top). It returns an error when a sub count exceeds its total.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
input | int64 | yes | Total input tokens reported by the provider, cached ones included. | |
output | int64 | yes | Total output tokens reported by the provider, reasoning ones included. | |
cachedInput | int64 | yes | Cached input tokens, part of input; written as cached_input_tokens when positive. | |
reasoning | int64 | yes | Reasoning tokens, part of output. |
Returns: (*Builder, error). A Builder: Builder assembles a Usage Event. The error is a typed error of the SDK, nil on success.
Raises: error.
Builder.Tokens
Tokens(input int64, output int64, reasoning int64) *Builder
Tokens sets input, output and reasoning tokens (zero values are omitted).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
input | int64 | yes | Input tokens, written as input_tokens when positive. | |
output | int64 | yes | Output tokens, written as output_tokens when positive. | |
reasoning | int64 | yes | Reasoning tokens, written as reasoning_tokens when positive. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Trace
Trace(requestID string, providerRequestID string, traceID string) *Builder
Trace sets request, provider request and trace ids.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
requestID | string | yes | Platform request identifier; empty omits it. | |
providerRequestID | string | yes | Request identifier given by the provider; empty omits it. | |
traceID | string | yes | Trace identifier; empty omits it. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Builder.Unit
Unit(name string, value float64) *Builder
Unit sets one unit counter (input_tokens, output_tokens, reasoning_tokens, requests, duration_ms...).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | string | yes | Name of the unit, one of those of the Usage Event contract. | |
value | float64 | yes | Consumed quantity; it replaces a previous value of the same unit. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
Model Options
Options configures an Emitter.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
BatchSize | int | yes | events per request, default 100 |
FlushInterval | time.Duration | yes | default 2s |
QueueSize | int | yes | buffered events, default 10000 |
OnError | func(err error, events []eai.UsageEvent) | yes | OnError receives batches that failed after the client retries. |
Class Emitter
Emitter sends events in the background. It is safe for concurrent use.
Emitter.Close
Close(ctx context.Context) error
Close stops accepting events, flushes the queue and stops the loop (call it on shutdown).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. |
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error.
Emitter.Emit
Emit(ev eai.UsageEvent) error
Emit queues an event without blocking.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ev | eai.UsageEvent | yes | Event to send, usually from Builder.Build; it is dropped with ErrQueueFull when the queue is full. |
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error.
Emitter.Flush
Flush(ctx context.Context) error
Flush sends every queued event now and returns the first error.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. |
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error.
Emitter.Sent
Sent() int64
Sent returns how many events were accepted by the server.
This element takes no parameter.
Returns: int64. Number of events of the batches the server accepted since the start.
Functions
NewEvent
NewEvent(tenantID string, usageType string, source string) *Builder
NewEvent starts an event for a tenant, usage type (llm, embeddings, tool...) and source (gateway, runtime, tool_gateway...). The event id and occurred_at are generated.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
tenantID | string | yes | Tenant the consumption is charged to. | |
usageType | string | yes | Kind of consumption, for example llm, embeddings or tool. | |
source | string | yes | Emitting component, for example gateway, runtime or tool_gateway. |
Returns: *Builder. A Builder: Builder assembles a Usage Event.
NewEmitter
NewEmitter(client *eai.Client, opts Options) *Emitter
NewEmitter starts the background loop.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
client | *eai.Client | yes | Parent client. | |
opts | Options | yes | Per call options (query, idempotency key, traceparent, headers). |
Returns: *Emitter. A Emitter: Emitter sends events in the background. It is safe for concurrent use.