NexusLabs.Needlr.AgentFramework.Diagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics Namespace

Classes
AgentFrameworkMetricsOptions	Configuration options for the agent framework's OpenTelemetry metrics and tracing.
AgentRunDiagnosticsBuilder	Thread-safe accumulator for diagnostics captured during a single agent run. Both Needlr's built-in diagnostics middleware and consumer-provided middleware use this class to record tool calls, chat completions, and message counts as an agent executes.
AgentRunDiagnosticsTimelineExtensions	Extensions for producing ordered timeline views of an IAgentRunDiagnostics.
AgentRunDiagnosticsTranscriptExtensions	Extensions for rendering an IAgentRunDiagnostics as a human-readable markdown transcript.
ChatCompletionCollectorHolder	DI-registered singleton that holds the IChatCompletionCollector instance. The diagnostics middleware sets the real collector during factory construction; consumers resolve this to access it. Unlike a static holder, each DI container has its own instance, making it testable and thread-safe across containers.
ChatCompletionDiagnostics	Diagnostics for a single LLM chat completion call within an agent run.
DiagnosticsCharCounter	Computes character counts of chat messages, responses, tool arguments, and tool results for diagnostics capture. Character counts are a direct programmatic measure of payload size — distinct from the LLM-provider-reported TokenUsage — and are useful for detecting chat-reducer drift, prompt bloat, and unexpectedly large tool responses during evaluation.
DiagnosticsTimelineEntry	A single entry in an agent run's ordered timeline of chat completions and tool calls.
TokenUsage	Token usage breakdown for a single LLM call or aggregate across an agent run.
ToolCallCollectorHolder	DI-registered singleton that holds the IToolCallCollector instance. The diagnostics middleware sets the real collector during factory construction; consumers resolve this to access it. Unlike a static holder, each DI container has its own instance, making it testable and thread-safe across containers.
ToolCallDiagnostics	Diagnostics for a single tool/function invocation within an agent run.
WorkflowRunOptions	Options for running a workflow with diagnostics and progress reporting. Consolidates the parameters for RunWithDiagnosticsAsync into a single record to avoid excessive parameter counts.

Interfaces
IAgentDiagnosticsAccessor	Provides access to the diagnostics captured during the most recent agent run in the current async flow. Uses the mutable-holder System.Threading.AsyncLocal<> pattern so that writes from child async flows (inside middleware) are visible to the parent scope.
IAgentDiagnosticsWriter	Write-side interface for storing diagnostics captured by middleware. Separated from IAgentDiagnosticsAccessor (the read-side) so that middleware can resolve this from DI without casting to a concrete type.
IAgentMetrics	Records agent execution metrics for observability. The default implementation emits System.Diagnostics.Metrics.Meter counters/histograms and System.Diagnostics.ActivitySource activities compatible with OpenTelemetry.
IAgentRunDiagnostics	Immutable view of diagnostics captured during a single agent run, including token usage, per-call timing, tool call details, and success/failure state.
IAgentStageResult	Result of a single agent stage within a multi-agent pipeline or group chat workflow, combining the response text with the captured diagnostics for that stage.
IChatCompletionCollector	Provides access to per-LLM-call completion diagnostics captured by the chat client middleware. Used by pipeline run extensions to correlate LLM call timing with agent turns.
IPipelineRunResult	Aggregated result of a multi-agent pipeline run, providing per-stage diagnostics alongside the response text from each agent.
IToolCallCollector	Provides access to per-tool-call diagnostics captured by the function-calling middleware. Used by pipeline run extensions to prevent silent tool call data loss when AsyncLocal diagnostics builders don't propagate across workflow infrastructure.
IToolMetricsAccessor	Allows tools to attach custom domain-specific metrics during execution. Metrics are collected by the diagnostics function-calling middleware and included in CustomMetrics.

Enums
DiagnosticsTimelineEntryKind	Identifies the kind of event a DiagnosticsTimelineEntry represents.