Skip to content

AgentFrameworkMetricsOptions

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

AgentFrameworkMetricsOptions Class

Configuration options for the agent framework's OpenTelemetry metrics and tracing.

public sealed class AgentFrameworkMetricsOptions

Inheritance System.Object 🡒 AgentFrameworkMetricsOptions

Remarks

Consumers that have existing dashboards keyed to a specific meter name (e.g., "BrandGhost.Agents") can set MeterName to match, avoiding a dashboard migration when adopting Needlr's IAgentMetrics.

Configure via the syringe:

.UsingAgentFramework(af => af
    .ConfigureMetrics(o => o.MeterName = "MyApp.Agents"))

Properties

AgentFrameworkMetricsOptions.ActivitySourceName Property

The name used for the System.Diagnostics.ActivitySource that emits distributed tracing spans. Defaults to MeterName when null.

public string? ActivitySourceName { get; set; }

Property Value

System.String

AgentFrameworkMetricsOptions.ChatCompletionActivityMode Property

Controls how Needlr's diagnostics middleware creates System.Diagnostics.Activity spans for chat completion calls.

public NexusLabs.Needlr.AgentFramework.Diagnostics.ChatCompletionActivityMode ChatCompletionActivityMode { get; set; }

Property Value

ChatCompletionActivityMode

Remarks

When MEAI's UseOpenTelemetry() or MAF's WithOpenTelemetry() is also active, both Needlr and the upstream middleware create spans for the same chat completion call. Set this to EnrichParent to avoid duplicate spans — Needlr will add its tags (sequence number, char counts, agent name) to the existing parent gen_ai.* activity instead of creating a new one.

Tool call activities (agent.tool) are not affected by this setting — they are always created because neither MEAI nor MAF produces per-tool-call spans.

AgentFrameworkMetricsOptions.GenAiMeterName Property

The name used for the System.Diagnostics.Metrics.Meter that owns the gen_ai.client.token.usage histogram on which Needlr emits cache_read and reasoning measurements via IGenAiTokenMetrics. Defaults to "Experimental.Microsoft.Extensions.AI", matching MEAI 10.5.0's OpenTelemetryConsts.DefaultSourceName.

public string GenAiMeterName { get; set; }

Property Value

System.String

Remarks

MEAI's Microsoft.Extensions.AI.OpenTelemetryChatClient emits the same gen_ai.client.token.usage histogram for input and output token types under a meter named by its sourceName constructor parameter (default "Experimental.Microsoft.Extensions.AI"). For the OpenTelemetry SDK to aggregate Needlr's cache_read / reasoning measurements into the same metric stream as MEAI's input / output measurements, the meter names MUST match. If the host configures MEAI with a custom sourceName (e.g. UseOpenTelemetry(sourceName: "MyApp.GenAI")), set this property to the same value:

.UsingAgentFramework(af => af
    .ConfigureMetrics(o => o.GenAiMeterName = "MyApp.GenAI"))

This property is independent of MeterName — that property scopes Needlr-shape agent metrics (agent.run.*, agent.tool.*, etc.) which have no upstream cohabitation requirement, while this property scopes the OTel gen_ai semantic-convention histogram that Needlr shares with MEAI.

AgentFrameworkMetricsOptions.MeterName Property

The name used for the System.Diagnostics.Metrics.Meter that emits counters and histograms. Defaults to "NexusLabs.Needlr.AgentFramework".

public string MeterName { get; set; }

Property Value

System.String