Struct TelemetryConfig 

pub struct TelemetryConfig {
    pub enabled: bool,
    pub backend: TelemetryBackend,
    pub trace_dir: PathBuf,
    pub include_args: bool,
    pub otlp_endpoint: Option<String>,
    pub otlp_headers_vault_key: Option<String>,
    pub pyroscope_endpoint: Option<String>,
    pub service_name: String,
    pub sample_rate: f64,
    pub otel_filter: Option<String>,
    pub system_metrics_interval_secs: u64,
}

Profiling and distributed tracing configuration, nested under [telemetry] in TOML.

When enabled = true and the binary is compiled with --features profiling, agent turn phases and LLM provider calls are instrumented with tracing spans. Traces are exported according to the selected TelemetryBackend.

Enabling telemetry has zero overhead when the profiling feature is absent — all instrumentation points are compiled out via cfg_attr.

Example (TOML)

[telemetry]
enabled = true
backend = "local"
trace_dir = ".local/traces"
include_args = false
service_name = "my-zeph"
sample_rate = 0.1

Fields

enabled: bool

Enable tracing instrumentation. Default: false.

backend: TelemetryBackend

Backend to use for trace export. Default: local.

trace_dir: PathBuf

Directory for Chrome JSON trace files (used when backend = "local"). Default: ".local/traces".

include_args: bool

Include function arguments as span attributes in Chrome JSON traces.

Default: false. Keep disabled in production — span field values are visible to all subscriber layers including OTLP. LLM prompts, tool outputs, and user messages may appear as span attributes if enabled.

Note: this flag controls the Chrome JSON trace layer only, not OTLP span attributes.

otlp_endpoint: Option<String>

OTLP gRPC endpoint URL (used when backend = "otlp"). Default: "http://localhost:4317" when unset.

otlp_headers_vault_key: Option<String>

Vault key for OTLP authentication headers (e.g. ZEPH_OTLP_HEADERS). When set, the value is resolved from the age vault at startup and passed as Authorization or custom headers to the collector.

pyroscope_endpoint: Option<String>

Pyroscope server URL (used when backend = "pyroscope").

service_name: String

Service name reported in trace metadata. Default: "zeph-agent".

sample_rate: f64

Fraction of traces to sample. 1.0 = record all, 0.1 = record 10%. Applies only to the otlp backend; the local backend always records all spans. Default: 1.0.

Warning

sample_rate controls the fraction of completed traces sent to the OTLP collector, but the sampler runs after span creation. A low sample_rate reduces collector storage but provides no protection against CPU or RAM spikes caused by high span creation rates. Use otel_filter (an EnvFilter applied before spans are created) to prevent the OTLP feedback loop.

otel_filter: Option<String>

Optional base filter directive for the OTLP tracing layer.

Accepts the same syntax as RUST_LOG / EnvFilter (e.g. "info", "debug,myapp=trace"). When unset, defaults to "info".

Hardcoded transport exclusions

The following exclusions are always appended after the user-supplied value, regardless of what is set here:

tonic=warn,tower=warn,hyper=warn,h2=warn,opentelemetry=warn,rmcp=warn,sqlx=warn,want=warn

EnvFilter uses last-directive-wins semantics, so these appended directives take precedence over any conflicting directive in this field. For example, setting otel_filter = "tonic=debug" will be silently overridden to tonic=warn because the hardcoded exclusion appears later in the filter string. This is intentional: allowing transport crates to emit debug spans would cause the OTLP exporter to capture its own network activity, creating a feedback loop.

Note on sample_rate

sample_rate controls the fraction of traces sent to the OTLP collector, but the sampler runs after span creation. Setting sample_rate < 1.0 reduces Jaeger storage but provides no protection against CPU or RAM spikes caused by high span creation rate. Only this otel_filter (an EnvFilter applied upstream of span creation) prevents the feedback loop.

system_metrics_interval_secs: u64

Interval in seconds between system-metrics snapshots (Phase 3). Default: 5.

Trait Implementations

impl Clone for TelemetryConfig

fn clone(&self) -> TelemetryConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TelemetryConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for TelemetryConfig

fn default() -> TelemetryConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for TelemetryConfig

fn deserialize<__D>( __deserializer: __D, ) -> Result<TelemetryConfig, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for TelemetryConfig

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.