TraconMetrics

Namespace Tracon · Assembly Tracon.Core.dll

Metrics emitted by Tracon. Consumers collect them with AddMeter(TraconDiagnostics.MeterName).

public sealed class TraconMetrics : IDisposable

Inheritance

object ← TraconMetrics

Implements

IDisposable

Inherited Members

object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

Instruments are set up via IMeterFactory, which allows them to be isolated in tests. When the factory is not registered, a Metrics.Meter is created directly - the library does not force the consumer to call AddMetrics.

Durations are in seconds. The OpenTelemetry semantic convention mandates seconds for histogram durations; writing milliseconds would break ready-made dashboards.

Constructors

TraconMetrics(IMeterFactory?, IOptionsMonitor<TraconOptions>?)

Creates a new metric set.

public TraconMetrics(IMeterFactory? meterFactory = null, IOptionsMonitor<TraconOptions>? options = null)

Parameters

meterFactory IMeterFactory?

Meter factory. When null, a new Metrics.Meter instance is created and owned by this object.

options IOptionsMonitor<TraconOptions>?

The root options type that TraconOptions.Observability — which carries TraconObservabilityOptions.MaxJobLaneCardinality — hangs off. When null, that setting’s own default is used. The nested type is never injected standalone: it is not registered with services.Configure<TraconObservabilityOptions> anywhere.

Properties

AgentSourceFailures

Agent-source failure counter. Tags: source, operation.

public Counter<long> AgentSourceFailures { get; }

Property Value

Counter<long>

JobDuration

Job-attempt duration. Tags: lane, kind, status.

public Histogram<double> JobDuration { get; }

Property Value

Histogram<double>

Remarks

One measurement covers ONE attempt. A job that fails twice and then succeeds records a single measurement, for its last attempt — the earlier attempts ended in a retry, which is not a terminal status.

JobExecutions

Finished-job counter. Tags: lane, kind, status, tenant.

public Counter<long> JobExecutions { get; }

Property Value

Counter<long>

Remarks

Only a TERMINAL status is counted. A lease renewal or a release for retry is not an outcome, and counting it would turn this instrument’s meaning from “how many jobs finished” into “how many things happened”.

JudgeCost

Judge cost counter. Tags: judge, model, tenant, currency.

public Counter<double> JudgeCost { get; }

Property Value

Counter<double>

JudgeScore

Judge score histogram. Tags: judge, agent, tenant.

public Histogram<double> JudgeScore { get; }

Property Value

Histogram<double>

ModelCacheLookups

Response-cache lookup counter. Tags: provider, tenant, result (hit/miss).

public Counter<long> ModelCacheLookups { get; }

Property Value

Counter<long>

RunCost

Cost counter. Tags: agent, model, tenant, currency.

public Counter<double> RunCost { get; }

Property Value

Counter<double>

RunDuration

Run duration. Tags: agent, status.

public Histogram<double> RunDuration { get; }

Property Value

Histogram<double>

Runs

Run counter. Tags: agent, status, tenant.

public Counter<long> Runs { get; }

Property Value

Counter<long>

Tokens

Token counter. Tags: agent, model, direction.

public Counter<long> Tokens { get; }

Property Value

Counter<long>

ToolDuration

Tool call duration. Tags: tool.

public Histogram<double> ToolDuration { get; }

Property Value

Histogram<double>

ToolInvocations

Tool call counter. Tags: tool, status.

public Counter<long> ToolInvocations { get; }

Property Value

Counter<long>

Methods

Dispose()

public void Dispose()

RecordAgentSourceFailure(string, string)

Records an agent-source failure or contract violation.

public void RecordAgentSourceFailure(string sourceName, string operation)

Parameters

sourceName string

The source name.

operation string

The operation: list, resolve, or consistency.

RecordCost(string, string?, string, decimal, string)

Records a run’s own cost (when a price is defined).

public void RecordCost(string agentName, string? modelId, string tenantId, decimal cost, string currency)

Parameters

agentName string

Agent name.

modelId string?

Model used. When null, "unknown" is written.

tenantId string

Tenant identifier.

cost decimal

The run’s own cost (input + output). not the tree total.

currency string

Currency.

RecordJob(string, string, JobStatus, string?, TimeSpan)

Records a background job that reached a terminal status.

public void RecordJob(string lane, string handlerKey, JobStatus status, string? tenantId, TimeSpan duration)

Parameters

lane string

The job’s lane (JobRecord.Lane). Guarded against runaway cardinality: see TraconObservabilityOptions.MaxJobLaneCardinality.

handlerKey string

The job’s handler key (JobRecord.HandlerKey).

status JobStatus

The terminal status: JobStatus.Completed, JobStatus.Failed, or JobStatus.Cancelled.

tenantId string?

The tenant the job belongs to. "unknown" is written when null.

duration TimeSpan

How long THIS attempt took, measured on a monotonic clock. It is not the job’s total time across every attempt.

RecordJudgeCost(string, string?, string, decimal, string)

Records a judge call’s own cost.

public void RecordJudgeCost(string judgeName, string? modelId, string tenantId, decimal cost, string currency)

Parameters

judgeName string

The judge’s name (IRunJudge.Name).

modelId string?

The judge’s model. When null, "unknown" is written.

tenantId string

Tenant identifier.

cost decimal

The judge’s own cost (input + output).

currency string

Currency.

RecordJudgeScore(string, string, string, double)

Records the score given by a judge.

public void RecordJudgeScore(string judgeName, string agentName, string tenantId, double score)

Parameters

judgeName string

The judge’s name (IRunJudge.Name).

agentName string

Name of the scored agent.

tenantId string

Tenant identifier.

score double

Score, 0-100.

RecordModelCacheLookup(string, string, bool)

Records a response-cache lookup.

public void RecordModelCacheLookup(string provider, string tenantId, bool hit)

Parameters

provider string

Model provider name.

tenantId string

Tenant identifier.

hit bool

Whether the lookup found a cached response.

RecordRun(string, RunStatus, string, string?, TimeSpan, RunUsage?, int?)

Records the result of a run.

public void RecordRun(string agentName, RunStatus status, string tenantId, string? modelId, TimeSpan duration, RunUsage? usage, int? agentVersion = null)

Parameters

agentName string

Agent name.

status RunStatus

Final status.

tenantId string

Tenant identifier.

modelId string?

Model used.

duration TimeSpan

Run duration.

usage RunUsage?

Token usage.

agentVersion int?

The measured definition version. When null, no tag is added - either it is unknown, or the caller is already passing null because TraconObservabilityOptions.IncludeAgentVersionTag is disabled.

RecordToolInvocation(string, bool, TimeSpan?)

Records the result of a tool call.

public void RecordToolInvocation(string toolName, bool succeeded, TimeSpan? duration)

Parameters

toolName string

Tool name.

succeeded bool

Whether the call completed successfully.

duration TimeSpan?

Call duration. null when unknown.