usage/usage.go (package usage)
Source : sdks/go/usage/usage.go. Retour à l'index de la référence du SDK Go.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Classe Builder
Builder assemble un Usage Event.
Builder.At
At(t time.Time) *Builder
At remplace occurred_at.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
t | time.Time | oui | Heure de la consommation, enregistrée en UTC. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Build
Build() (eai.UsageEvent, error)
Build valide l'événement par rapport au contrat Usage Event v1.
Cet élément ne prend aucun paramètre.
Retour : (eai.UsageEvent, error). Un UsageEvent : le contrat Usage Event v1 (contracts/v1/usage-event.schema.json). L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error.
Builder.Estimated
Estimated(amount string, currency string) *Builder
Estimated définit le coût estimé (chaîne décimale).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
amount | string | oui | Montant décimal exact sous forme de chaîne, par exemple 0.0042. | |
currency | string | oui | Code de devise ISO 4217, par exemple EUR. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Execution
Execution(agentID string, sessionID string, runID string, taskID string) *Builder
Execution définit les identifiants d'agent, de session, d'exécution et de tâche.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
agentID | string | oui | Agent consommateur ; vide, agent_id reste nul. | |
sessionID | string | oui | Session de la consommation ; vide, session_id reste nul. | |
runID | string | oui | Exécution consommatrice ; vide, run_id est omis. | |
taskID | string | oui | Tâche de la consommation ; vide, task_id reste nul. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.ID
ID(id string) *Builder
ID remplace l'identifiant de l'événement.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | string | oui | Identifiant d'événement utilisé à la place du ue-<aléatoire> généré. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Label
Label(k string, v string) *Builder
Label ajoute un label.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
k | string | oui | Nom du label. | |
v | string | oui | Valeur du label, jusqu'à 256 caractères. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Lang
Lang(l string) *Builder
Lang choisit la langue des messages de validation (en, fr).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
l | string | oui | Langue des messages de Build, en ou fr. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Measured
Measured(amount string, currency string) *Builder
Measured définit le coût mesuré et marque l'événement comme mesuré.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
amount | string | oui | Montant décimal exact sous forme de chaîne, par exemple 0.0042. | |
currency | string | oui | Code de devise ISO 4217, par exemple EUR. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Model
Model(provider string, modelID string, deploymentID string, region string) *Builder
Model définit le fournisseur, le modèle, le déploiement et la région.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
provider | string | oui | Fournisseur qui a servi l'appel ; exigé par le contrat. | |
modelID | string | oui | Identifiant du modèle qui a servi l'appel. | |
deploymentID | string | oui | Déploiement du modèle ; vide, deployment_id est omis. | |
region | string | oui | Région de traitement, par exemple eu-west-1. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Pricing
Pricing(priceCardID string, version string, currency string, effectiveAt time.Time) *Builder
Pricing définit le prix applicable au moment de l'appel.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
priceCardID | string | oui | Grille tarifaire utilisée ; vide, price_card_id est omis. | |
version | string | oui | Version de la tarification (pricing_version). | |
currency | string | oui | Devise ISO 4217 de la grille tarifaire. | |
effectiveAt | time.Time | oui | Heure à partir de laquelle le prix s'applique, enregistrée en UTC. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Project
Project(projectID string, environment string) *Builder
Project définit project_id et environment.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
projectID | string | oui | Projet de la consommation ; vide, project_id est omis. | |
environment | string | oui | Environnement de la consommation ; vide, environment est omis. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.TokenTotals
TokenTotals(input int64, output int64, cachedInput int64, reasoning int64) (*Builder, error)
TokenTotals suit la règle FinOps des jetons : input inclut déjà les jetons en cache, output inclut déjà le raisonnement (totaux du fournisseur, les sous-comptes ne s'ajoutent jamais par-dessus). Renvoie une erreur quand un sous-compte dépasse son total.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
input | int64 | oui | Total des jetons d'entrée donné par le fournisseur, jetons en cache compris. | |
output | int64 | oui | Total des jetons de sortie donné par le fournisseur, jetons de raisonnement compris. | |
cachedInput | int64 | oui | Jetons d'entrée en cache, compris dans input ; écrits dans cached_input_tokens s'ils sont positifs. | |
reasoning | int64 | oui | Jetons de raisonnement, compris dans output. |
Retour : (*Builder, error). Un Builder : il assemble un Usage Event. L'error est renseignée quand un sous-compte dépasse son total, nil en cas de succès.
Erreurs levées : error.
Builder.Tokens
Tokens(input int64, output int64, reasoning int64) *Builder
Tokens définit les jetons d'entrée, de sortie et de raisonnement (les valeurs nulles sont omises).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
input | int64 | oui | Jetons d'entrée, écrits dans input_tokens s'ils sont positifs. | |
output | int64 | oui | Jetons de sortie, écrits dans output_tokens s'ils sont positifs. | |
reasoning | int64 | oui | Jetons de raisonnement, écrits dans reasoning_tokens s'ils sont positifs. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Trace
Trace(requestID string, providerRequestID string, traceID string) *Builder
Trace définit les identifiants de requête, de requête du fournisseur et de trace.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
requestID | string | oui | Identifiant de requête de la plateforme ; vide, il est omis. | |
providerRequestID | string | oui | Identifiant de requête donné par le fournisseur ; vide, il est omis. | |
traceID | string | oui | Identifiant de trace ; vide, il est omis. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Builder.Unit
Unit(name string, value float64) *Builder
Unit définit un compteur d'unités (input_tokens, output_tokens, reasoning_tokens, requests, duration_ms...).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
name | string | oui | Nom de l'unité, l'une de celles du contrat Usage Event. | |
value | float64 | oui | Quantité consommée ; elle remplace une valeur précédente de la même unité. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
Modèle Options
Options configure un Emitter.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
BatchSize | int | oui | Hôtes traités en même temps, de 1 à 100, 1 par défaut. |
FlushInterval | time.Duration | oui | 2 s par défaut. |
QueueSize | int | oui | Événements en mémoire tampon, 10000 par défaut. |
OnError | func(err error, events []eai.UsageEvent) | oui | OnError reçoit les lots qui ont échoué après les nouvelles tentatives du client. |
Classe Emitter
Emitter envoie les événements en arrière-plan. Il peut être utilisé par plusieurs goroutines en même temps.
Emitter.Close
Close(ctx context.Context) error
Close cesse d'accepter des événements, vide la file et arrête la boucle (à appeler à l'arrêt).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. |
Retour : error. Erreur de l'appel (une erreur typée du SDK), nil en cas de succès.
Erreurs levées : error.
Emitter.Emit
Emit(ev eai.UsageEvent) error
Emit met un événement en file sans bloquer.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ev | eai.UsageEvent | oui | Événement à envoyer, en général issu de Builder.Build ; il est abandonné avec ErrQueueFull quand la file est pleine. |
Retour : error. Erreur de l'appel (une erreur typée du SDK), nil en cas de succès.
Erreurs levées : error.
Emitter.Flush
Flush(ctx context.Context) error
Flush envoie tout de suite tous les événements en file et renvoie la première erreur.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. |
Retour : error. Erreur de l'appel (une erreur typée du SDK), nil en cas de succès.
Erreurs levées : error.
Emitter.Sent
Sent() int64
Sent renvoie combien d'événements ont été acceptés par le serveur.
Cet élément ne prend aucun paramètre.
Retour : int64. Nombre d'événements des lots acceptés par le serveur depuis le démarrage.
Fonctions
NewEvent
NewEvent(tenantID string, usageType string, source string) *Builder
NewEvent commence un événement pour un tenant, un type d'usage (llm, embeddings, tool...) et une source (gateway, runtime, tool_gateway...). L'identifiant de l'événement et occurred_at sont générés.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
tenantID | string | oui | Tenant auquel la consommation est imputée. | |
usageType | string | oui | Nature de la consommation, par exemple llm, embeddings ou tool. | |
source | string | oui | Composant émetteur, par exemple gateway, runtime ou tool_gateway. |
Retour : *Builder. Un Builder : il assemble un Usage Event.
NewEmitter
NewEmitter(client *eai.Client, opts Options) *Emitter
NewEmitter démarre la boucle d'arrière-plan.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
client | *eai.Client | oui | Client parent. | |
opts | Options | oui | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : *Emitter. Un Emitter : il envoie les événements en arrière-plan et peut être utilisé par plusieurs goroutines en même temps.