.NET API
TraconObservabilityOptions
Tracon.Core.dllDefines telemetry collection and persistence options.
public sealed class TraconObservabilityOptions- Inheritance
- object ← TraconObservabilityOptions
- Inherited Members
- object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()
Remarks
Section titled “Remarks”Tracon does not take over the pipeline: the consumer’s OTLP exporter continues to run. These options only control what Tracon writes to its own span store.
Constructors
Section titled “Constructors”TraconObservabilityOptions()
Section titled “ TraconObservabilityOptions()”public TraconObservabilityOptions()Properties
Section titled “Properties”AlwaysPersistFailures
Section titled “ AlwaysPersistFailures”Gets or sets whether failed run spans are persisted regardless of sampling ratio.
public bool AlwaysPersistFailures { get; set; }Property Value
Section titled “Property Value”EnableJobQueueDepthGauge
Section titled “ EnableJobQueueDepthGauge”Gets or sets whether the tracon.job.queue.depth observable
gauge publishes measurements.
public bool EnableJobQueueDepthGauge { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Disabled by default under the no-surprises rule, for the same
reason as TraconObservabilityOptions.EnableQuotaUsageGauge: the gauge reads the database.
The tracon.job.executions counter and the
tracon.job.duration histogram are not affected by this setting —
they cost no extra query and are always written.
When enabled, the depth is refreshed in the background the same way as the quota gauges: at startup, then every TraconObservabilityOptions.JobQueueDepthRefreshInterval. A scrape never waits for the database, and the first scrape after startup can be empty. The setting is read at startup: turning the gauge on takes effect at the next start.
EnableQuotaUsageGauge
Section titled “ EnableQuotaUsageGauge”Gets or sets whether the tracon.quota.usage and
tracon.quota.limit observable gauges are enabled.
public bool EnableQuotaUsageGauge { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Disabled by default under the no-surprises rule because the gauge reads the database. Unlike the cost counter, this consumes additional resources and must be explicitly requested.
When enabled, a background service reads the samples at startup and then every TraconObservabilityOptions.QuotaUsageRefreshInterval; a metrics collection only reads the last result and never waits for the database. The first collection after startup can therefore be empty. The setting is read at startup: turning the gauge on takes effect at the next start.
Enabled
Section titled “ Enabled”Gets or sets whether span and metric creation is enabled. When disabled,
no Activity starts and no measurement is recorded.
public bool Enabled { get; set; }Property Value
Section titled “Property Value”IncludeAgentVersionTag
Section titled “ IncludeAgentVersionTag”Gets or sets whether the tracon.agent.version tag is added to
spans and the tracon.runs and tracon.run.duration metrics.
public bool IncludeAgentVersionTag { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Defaults to true. A version number creates dozens of time series per agent over time, which is acceptable cardinality. Deployments that change versions very frequently can disable it.
IncludeTenantTag
Section titled “ IncludeTenantTag”Gets or sets whether the tracon.tenant.id tag is added to the run, cost, judge, response-cache,
audit-write-failure, run-recording-failure and job metrics.
public bool IncludeTenantTag { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Disabled by default. A tag per tenant multiplies every series of those metrics by the number of tenants, and a metric backend bills and slows down by series. Turn it on when the number of tenants is small and bounded and a dashboard or an alert has to split a metric by tenant.
The setting leaves two things alone, because neither multiplies series: spans always carry
tracon.tenant.id, and so do the tracon.quota.usage and tracon.quota.limit gauges
(a quota is a per-tenant fact; a gauge without the tenant says nothing). The metrics read the value from
the options at every measurement.
JobQueueDepthRefreshInterval
Section titled “ JobQueueDepthRefreshInterval”Gets or sets how often the queue-depth gauge’s background refresh reads the database. A reported depth can be up to one interval old.
public TimeSpan JobQueueDepthRefreshInterval { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Must be from one millisecond to about 49.7 days while TraconObservabilityOptions.EnableJobQueueDepthGauge is on; startup validation rejects any other value. The value is read when the host starts; a later change takes effect at the next start.
MaxJobLaneCardinality
Section titled “ MaxJobLaneCardinality”Gets or sets how many distinct job lanes may each get a metric series of
their own before further lanes are folded into a single other series.
public int MaxJobLaneCardinality { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”A lane name is chosen by the consumer (JobLanes) and its count is unbounded, so it is the one tag value Tracon does not control. This limit is a guard, not a design constraint: an installation with more than 64 meaningful lanes is an operator error rather than a use case. Lanes keep the name they were first seen under for the life of the process; the set never shrinks.
MaxSpansPerRun
Section titled “ MaxSpansPerRun”Gets or sets the largest span count held in memory for one run. Excess spans are dropped and a warning is logged.
public int MaxSpansPerRun { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”The sampling decision is made when a run finishes, when success or failure is known. Spans remain in memory until then. This limit bounds memory use by the concurrent run count.
PersistSpans
Section titled “ PersistSpans”Gets or sets whether spans are written to ITraceStore. When disabled, spans are still created and sent to the consumer exporter, but are not written to Tracon’s own store.
public bool PersistSpans { get; set; }Property Value
Section titled “Property Value”QuotaUsageRefreshInterval
Section titled “ QuotaUsageRefreshInterval”Gets or sets how often the quota gauges’ background refresh reads the database. A reported value can be up to one interval old.
public TimeSpan QuotaUsageRefreshInterval { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Must be from one millisecond to about 49.7 days while TraconObservabilityOptions.EnableQuotaUsageGauge is on; startup validation rejects any other value. The value is read when the host starts; a later change takes effect at the next start.
RecordSensitiveData
Section titled “ RecordSensitiveData”Gets or sets whether request and response text is written to spans. Disabled by default because this content can contain personal data.
public bool RecordSensitiveData { get; set; }Property Value
Section titled “Property Value”SuccessSampleRatio
Section titled “ SuccessSampleRatio”Gets or sets the fraction from 0 to 1 of successful run spans to persist. Defaults to 0.1, or one tenth.
public double SuccessSampleRatio { get; set; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Persisting every span bottlenecks the database at high volume. Failed runs are valuable for debugging and are separately protected by TraconObservabilityOptions.AlwaysPersistFailures.