# TailSamplingConfig

Optional configuration for histogram-based tail sampling. When provided, enables intelligent sampling based on trace duration percentiles calculated over sliding windows. Uses hierarchical trace signatures to group similar traces and applies configurable sampling rates based on performance tiers (fast, medium, slow, outliers).

**Type**: `object`

## Properties

- name: bootstrapThreshold (optional)
  type: integer
  description: Number of traces to sample during bootstrap period before applying percentile-based sampling rules. This allows the system to gather initial data on trace durations before applying more complex sampling logic. This number will be multiplied by the parallelism of the pipeline, so the bootstrap traces may be higher as the pipeline expands for new trace signatures.

- name: errorSamplingRate (optional)
  type: number
  description: Sampling rate for traces that contain errors or failures. Error traces are often the most important for debugging and should typically have high sampling rates. Applied before quantile-based sampling.

- name: incompleteSamplingRate (optional)
  type: number
  description: Sampling rate for incomplete/partial traces. Partial traces occur when some spans are missing, which can indicate data loss or system issues. Applied before quantile-based sampling.

- name: keyAttributePaths (optional)
  type: array of array of string
  description: Array of attribute paths to extract key attributes from spans for hierarchical signature generation. Each inner array represents a sequence of keys to search for in the attributes map. These attributes are used to group traces by their structural patterns.

- name: longRunningTraceSamplingRate (optional)
  type: number
  description: Sampling rate for traces force-emitted because they exceeded the configured maxSessionLength. Routed through a dedicated 'long_running' percentile bucket — distinct from the structural 'incomplete' bucket — so operators can monitor and tune separately.

- name: maxSessionLength (optional)
  type: string
  description: Upper bound on how long a single trace assembly session may accumulate spans in memory before being force-emitted. Protects against long-running traces that would otherwise hold spans in the assembly buffer indefinitely. When the cap is hit, the trace is classified as long-running and later spans form a new session. Must be strictly greater than maxTraceDelay.

- name: maxTraceDelay (optional)
  type: string
  description: The maximum time to wait for all spans of a trace to arrive before assembling the trace. This determines the size of the tumbling window used for trace assembly. Traces that span longer than this duration may be assembled as partial traces. Should be set based on the expected maximum trace duration in your system. Large values may lead to memory issues if traces are too long and will delay sending traces to the sink by that amount. The pipeline may also fail if configured too high.

- name: quantileSamplingTiers (optional)
  type: array of `QuantileSamplingTier`
  description: List of quantile sampling tiers for performance-based sampling. Each tier defines a percentile threshold, sampling rate, and label. Traces ABOVE each quantile get the corresponding sampling rate and are labeled with the tier's label. Evaluated in descending quantile order. A tier at quantile 0.0 is a catch-all that matches unconditionally, giving the fastest traces a baseline rate; without one, traces below the lowest configured quantile are dropped.