IGenAiTokenMetrics
NexusLabs.Needlr.AgentFramework¶
NexusLabs.Needlr.AgentFramework.Diagnostics¶
IGenAiTokenMetrics Interface¶
Records measurements on the OpenTelemetry gen_ai.client.token.usage histogram
for token-type categories that Microsoft.Extensions.AI.OpenTelemetryChatClient
does not emit itself (today: cache_read and reasoning).
Remarks¶
MEAI's Microsoft.Extensions.AI.OpenTelemetryChatClient emits the
gen_ai.client.token.usage histogram per the OpenTelemetry GenAI semantic
conventions, but only for gen_ai.token.type = "input" and "output".
Implementations of this interface emit additional measurements on the same histogram
for token-type categories that exist in Microsoft.Extensions.AI.UsageDetails
(Microsoft.Extensions.AI.UsageDetails.CachedInputTokenCount,
Microsoft.Extensions.AI.UsageDetails.ReasoningTokenCount) but are not
part of the OTel semantic-convention gen_ai.token.type enum today.
Implementations MUST never emit input or output — those are MEAI's
responsibility and duplicate emission would silently double recorded values.
Implementations MUST skip emission when the token count is zero or negative — zero samples are not meaningful and pathological negative counts must not be recorded.
For the two writers (Needlr's middleware and MEAI's Microsoft.Extensions.AI.OpenTelemetryChatClient)
to aggregate into a single OpenTelemetry MetricStreamIdentity, the implementation's
underlying System.Diagnostics.Metrics.Meter name MUST match the sourceName
passed to MEAI's Microsoft.Extensions.AI.OpenTelemetryChatClient constructor.
Configure via GenAiMeterName.
Methods¶
IGenAiTokenMetrics.RecordTokenUsage(string, long, GenAiTokenUsageTags) Method¶
Records a single sample on the gen_ai.client.token.usage histogram with
the supplied tokenType as the gen_ai.token.type tag value
and the supplied tags attached as additional measurement tags.
void RecordTokenUsage(string tokenType, long tokenCount, NexusLabs.Needlr.AgentFramework.Diagnostics.GenAiTokenUsageTags tags);
Parameters¶
tokenType System.String
Value for the gen_ai.token.type tag (e.g. "cache_read", "reasoning").
Must not be null or empty.
tokenCount System.Int64
The number of tokens to record. Implementations MUST skip emission when this is less than or equal to zero.
tags GenAiTokenUsageTags
Additional metric tags. Tags whose values are null are omitted from the recorded measurement.