use std::fmt;
use std::io::{IsTerminal, Write};
use std::time::Duration;
use oxtel_prometheus::{PrometheusExporter, PrometheusServer};
use oxtel_sdk::logs::{LocalFormat, LocalLayer, LoggerProvider, LoggerProviderBuilder};
use oxtel_sdk::metrics::{MeterProvider, MeterProviderBuilder, MetricsRecorder};
use oxtel_sdk::resource::Detector;
use oxtel_sdk::trace::{Sampler, TracerProvider, TracerProviderBuilder};
use oxtel_sdk::{KeyValue, Resource};
use tracing::Dispatch;
use tracing_core::LevelFilter;
use tracing_subscriber::filter::Targets;
use tracing_subscriber::layer::{Filter, Layer, SubscriberExt};
use tracing_subscriber::registry::Registry;
use crate::config::{EnvConfig, Local, LocalEnv, LogOutput};
use crate::filter::LogFilter;
use crate::guard::Guard;
use crate::plan::{Plan, Proc, Programmed, Reader};
use crate::summary::{Dest, Kind, Summary};
type BoxedLayer = Box<dyn Layer<Registry> + Send + Sync>;
type Hook<B> = Box<dyn FnOnce(B) -> B>;
#[must_use = "a builder does nothing until `install` or `build`"]
pub struct Builder {
default_service_name: Option<String>,
attributes: Vec<KeyValue>,
detectors: Vec<Box<dyn Detector>>,
resource: Option<Resource>,
sampler: Option<Sampler>,
traces_filter: Option<String>,
logs_filter: Option<String>,
layers: Vec<BoxedLayer>,
trace_hooks: Vec<Hook<TracerProviderBuilder>>,
log_hooks: Vec<Hook<LoggerProviderBuilder>>,
metric_hooks: Vec<Hook<MeterProviderBuilder>>,
env_exporters: bool,
pull_metrics: bool,
sdk_metrics: bool,
shutdown_timeout: Duration,
local: Local,
local_output: LogOutput,
local_filter: Option<String>,
local_writer: Option<Box<dyn Write + Send>>,
#[cfg(feature = "mappings")]
mappings: Vec<std::sync::Arc<dyn oxtel_sdk::trace::EventMapping>>,
#[cfg(feature = "mappings")]
built_in_mappings: bool,
}
impl Default for Builder {
fn default() -> Self {
Builder {
default_service_name: None,
attributes: Vec::new(),
detectors: Vec::new(),
resource: None,
sampler: None,
traces_filter: None,
logs_filter: None,
layers: Vec::new(),
trace_hooks: Vec::new(),
log_hooks: Vec::new(),
metric_hooks: Vec::new(),
env_exporters: true,
pull_metrics: false,
sdk_metrics: false,
shutdown_timeout: Duration::from_secs(5),
local: Local::Auto,
local_output: LogOutput::Stderr,
local_filter: None,
local_writer: None,
#[cfg(feature = "mappings")]
mappings: Vec::new(),
#[cfg(feature = "mappings")]
built_in_mappings: true,
}
}
}
impl Builder {
pub fn with_default_service_name(mut self, name: impl Into<String>) -> Self {
self.default_service_name = Some(name.into());
self
}
pub fn with_resource_attribute(mut self, attribute: KeyValue) -> Self {
self.attributes.push(attribute);
self
}
pub fn with_resource_detector(mut self, detector: impl Detector + 'static) -> Self {
self.detectors.push(Box::new(detector));
self
}
pub fn with_resource(mut self, resource: Resource) -> Self {
self.resource = Some(resource);
self
}
pub fn with_sampler(mut self, sampler: Sampler) -> Self {
self.sampler = Some(sampler);
self
}
pub fn with_traces_filter(mut self, directives: impl Into<String>) -> Self {
self.traces_filter = Some(directives.into());
self
}
pub fn with_logs_filter(mut self, directives: impl Into<String>) -> Self {
self.logs_filter = Some(directives.into());
self
}
pub fn with_layer(mut self, layer: impl Layer<Registry> + Send + Sync) -> Self {
self.layers.push(layer.boxed());
self
}
pub fn with_traces(
mut self,
hook: impl FnOnce(TracerProviderBuilder) -> TracerProviderBuilder + 'static,
) -> Self {
self.trace_hooks.push(Box::new(hook));
self
}
pub fn with_logs(
mut self,
hook: impl FnOnce(LoggerProviderBuilder) -> LoggerProviderBuilder + 'static,
) -> Self {
self.log_hooks.push(Box::new(hook));
self
}
pub fn with_metrics(
mut self,
hook: impl FnOnce(MeterProviderBuilder) -> MeterProviderBuilder + 'static,
) -> Self {
self.metric_hooks.push(Box::new(hook));
self
}
#[cfg(feature = "mappings")]
pub fn with_mapping(mut self, mapping: impl oxtel_sdk::trace::EventMapping) -> Self {
self.mappings.push(std::sync::Arc::new(mapping));
self
}
#[cfg(feature = "mappings")]
pub fn without_mappings(mut self) -> Self {
self.built_in_mappings = false;
self
}
pub fn without_env_exporters(mut self) -> Self {
self.env_exporters = false;
self
}
pub fn with_pull_metrics(mut self) -> Self {
self.pull_metrics = true;
self
}
pub fn with_sdk_metrics(mut self, enabled: bool) -> Self {
self.sdk_metrics = enabled;
self
}
pub fn with_local_logs(mut self, format: LocalFormat) -> Self {
self.local = Local::Format(format);
self
}
pub fn without_local_logs(mut self) -> Self {
self.local = Local::Off;
self
}
pub fn with_local_logs_output(mut self, output: LogOutput) -> Self {
self.local_output = output;
self
}
pub fn with_local_logs_filter(mut self, directives: impl Into<String>) -> Self {
self.local_filter = Some(directives.into());
self
}
pub fn with_local_logs_writer(mut self, out: impl Write + Send + 'static) -> Self {
self.local_writer = Some(Box::new(out));
self
}
pub fn with_shutdown_timeout(mut self, timeout: Duration) -> Self {
self.shutdown_timeout = timeout;
self
}
pub fn install(self) -> Result<Guard, Error> {
self.build()?.install()
}
pub fn build(self) -> Result<Telemetry, Error> {
oxtel_sdk::sdk_metrics::set_enabled(self.sdk_metrics);
let programmed = Programmed {
default_service_name: self.default_service_name,
attributes: self.attributes,
detectors: self.detectors,
resource: self.resource,
sampler: self.sampler,
};
let config_file = std::env::var("OTEL_CONFIG_FILE")
.ok()
.filter(|p| !p.trim().is_empty());
let plan = match config_file.as_deref() {
#[cfg(feature = "config")]
Some(path) => {
let parsed = oxtel_config::from_file(path.trim())
.map_err(|e| Error::Config(e.to_string()))?;
let (local, local_warnings) = EnvConfig::local_from_env();
let mut plan = Plan::from_config(parsed, programmed, local);
plan.warnings.extend(local_warnings);
plan
}
#[cfg(not(feature = "config"))]
Some(_) => {
let mut plan =
Plan::from_env(EnvConfig::from_env(), self.env_exporters, programmed);
plan.warnings.push(
"OTEL_CONFIG_FILE needs oxtel's `config` feature; using the environment".into(),
);
plan
}
None => Plan::from_env(EnvConfig::from_env(), self.env_exporters, programmed),
};
let Plan {
disabled,
resource,
trace_context,
sampler,
span_limits,
log_limits,
span_processors,
log_processors,
readers,
exemplar_filter,
cardinality_limit,
local: env_local,
mut warnings,
} = plan;
let local_out = local_output(env_local, self.local, self.local_output, self.local_writer);
let mut summary = Summary {
#[cfg(feature = "config")]
config_file: config_file.map(|p| p.trim().to_string()),
local: local_out.as_ref().map(|(format, _, place)| {
let format = match format {
LocalFormat::Text => "text",
LocalFormat::Json => "JSON",
LocalFormat::Ecs => "ECS JSON",
};
format!("{place}, as {format}")
}),
disabled,
..Summary::default()
};
let local = |events: Targets, spans: Targets| {
local_out.map(|(format, out, _)| {
LocalLayer::new(format)
.with_resource(&resource)
.with_writer(out)
.with_filter(LogFilter { events, spans })
.boxed()
})
};
let local_directives = directives(
"local logs",
self.local_filter.or_else(|| self.logs_filter.clone()),
&mut warnings,
);
if disabled {
let log_level = log_level(&[&local_directives], &self.layers);
let mut layers: Vec<BoxedLayer> = Vec::new();
layers.extend(local(local_directives.clone(), local_directives));
layers.extend(self.layers);
return Ok(Telemetry {
dispatch: Dispatch::new(tracing_subscriber::registry().with(layers)),
recorder: None,
guard: Guard {
traces: None,
logs: None,
metrics: None,
prometheus: None,
timeout: self.shutdown_timeout,
summary: summary.line(),
},
warnings,
trace_context: false,
log_level,
});
}
let traces_directives = directives("traces", self.traces_filter, &mut warnings);
let logs_directives = directives("logs", self.logs_filter, &mut warnings);
let log_level = log_level(
&[&local_directives, &logs_directives, &traces_directives],
&self.layers,
);
#[cfg(feature = "mappings")]
let mappings = {
let mut mappings = self.mappings;
if self.built_in_mappings && mappings_from_env(&mut warnings) {
mappings.extend(crate::mappings::built_in());
}
mappings
};
#[allow(unused_mut)]
let mut trace_layer_directives = traces_directives.clone();
#[cfg(feature = "mappings")]
for mapping in &mappings {
for &(target, level) in mapping.targets() {
if !traces_directives.iter().any(|(t, _)| t == target) {
trace_layer_directives = trace_layer_directives.with_target(target, level);
}
}
}
let dests = |procs: &[Proc], kind, hooks: bool| {
let mut dests: Vec<Dest> = procs.iter().map(|p| Dest::of_proc(p, kind)).collect();
if hooks {
dests.push(Dest::Program);
}
dests
};
summary.traces = dests(&span_processors, Kind::Traces, !self.trace_hooks.is_empty());
summary.logs = dests(&log_processors, Kind::Logs, !self.log_hooks.is_empty());
summary.metrics = readers
.iter()
.filter_map(|r| match r {
Reader::Periodic(sink, _) => Some(Dest::of_sink(sink, Kind::Metrics)),
Reader::Prometheus { .. } => None,
})
.collect();
if !self.metric_hooks.is_empty() || self.pull_metrics {
summary.metrics.push(Dest::Program);
}
let logs = (!log_processors.is_empty() || !self.log_hooks.is_empty()).then(|| {
let mut b = LoggerProvider::builder().with_resource(resource.clone());
if let Some(limits) = log_limits {
b = b.with_limits(limits);
}
for p in log_processors {
b = match p {
Proc::Batch(sink, config) => b.with_batch_exporter_config(sink, config),
Proc::Simple(sink) => b.with_simple_exporter(sink),
};
}
for hook in self.log_hooks {
b = hook(b);
}
b.build()
});
let spans_go_somewhere = !span_processors.is_empty() || !self.trace_hooks.is_empty();
let mut b = TracerProvider::builder()
.with_resource(resource.clone())
.with_span_events(logs.is_none() && spans_go_somewhere);
if let Some(sampler) = sampler {
b = b.with_sampler(sampler);
}
if let Some(limits) = span_limits {
b = b.with_span_limits(limits);
}
for p in span_processors {
b = match p {
Proc::Batch(sink, config) => b.with_batch_exporter_config(sink, config),
Proc::Simple(sink) => b.with_simple_exporter(sink),
};
}
#[cfg(feature = "mappings")]
for mapping in mappings {
b = b.with_event_mapping(mapping);
}
for hook in self.trace_hooks {
b = hook(b);
}
let traces = b.build();
let mut prometheus = None;
let metrics = (!readers.is_empty() || !self.metric_hooks.is_empty() || self.pull_metrics)
.then(|| {
let mut b = MeterProvider::builder().with_resource(resource.clone());
if let Some(filter) = exemplar_filter {
b = b.with_exemplar_filter(filter);
}
if let Some(limit) = cardinality_limit {
b = b.with_cardinality_limit(limit);
}
let mut pull = Vec::new();
for reader in readers {
match reader {
Reader::Periodic(sink, config) => {
b = b.with_periodic_exporter_config(sink, config);
}
Reader::Prometheus { addr, options } => pull.push((addr, options)),
}
}
for hook in self.metric_hooks {
b = hook(b);
}
let meters = b.build();
if let Some((addr, options)) = pull.into_iter().next() {
let exporter = PrometheusExporter::new(meters.clone(), resource.clone())
.with_options(options);
match PrometheusServer::serve(addr.as_str(), exporter) {
Ok(server) => prometheus = Some(server),
Err(e) => warnings
.push(format!("couldn't serve Prometheus metrics on {addr}: {e}")),
}
}
meters
});
if let Some(server) = &prometheus {
summary.metrics.push(Dest::Prometheus(server.local_addr()));
}
let grpc_port = [&summary.traces, &summary.metrics, &summary.logs]
.into_iter()
.flatten()
.find(|d| d.uses_the_grpc_port());
if let Some(Dest::Exporter(destination)) = grpc_port {
warnings.push(format!(
"{destination} uses port 4317, where collectors take OTLP over gRPC, which oxtel \
doesn't speak yet; OTLP over HTTP is usually on port 4318"
));
}
let mut layers: Vec<BoxedLayer> =
vec![traces.layer().with_filter(trace_layer_directives).boxed()];
if let Some(logs) = &logs {
layers.push(
logs.layer()
.with_filter(LogFilter {
events: logs_directives,
spans: traces_directives.clone(),
})
.boxed(),
);
}
layers.extend(local(local_directives, traces_directives));
layers.extend(self.layers);
Ok(Telemetry {
dispatch: Dispatch::new(tracing_subscriber::registry().with(layers)),
recorder: metrics.as_ref().map(MeterProvider::recorder),
guard: Guard {
traces: Some(traces),
logs,
metrics,
prometheus,
timeout: self.shutdown_timeout,
summary: summary.line(),
},
warnings,
trace_context,
log_level,
})
}
}
fn local_output(
env: LocalEnv,
programmed: Local,
output: LogOutput,
writer: Option<Box<dyn Write + Send>>,
) -> Option<(LocalFormat, Box<dyn Write + Send>, &'static str)> {
type Out = (Box<dyn Write + Send>, bool, &'static str);
let stream = |output| -> Out {
match output {
LogOutput::Stderr => (
Box::new(std::io::stderr()),
std::io::stderr().is_terminal(),
"standard error",
),
LogOutput::Stdout => (
Box::new(std::io::stdout()),
std::io::stdout().is_terminal(),
"standard output",
),
}
};
let (out, terminal, place) = match (env.output, writer) {
(Some(output), _) => stream(output),
(None, Some(writer)) => (writer, false, "the program's writer"),
(None, None) => stream(output),
};
let format = match env.format.unwrap_or(programmed) {
Local::Off => return None,
Local::Format(format) => format,
Local::Auto if terminal => LocalFormat::Text,
Local::Auto => LocalFormat::Json,
};
Some((format, out, place))
}
fn directives(signal: &str, explicit: Option<String>, warnings: &mut Vec<String>) -> Targets {
let source = explicit
.or_else(|| std::env::var("RUST_LOG").ok())
.filter(|d| !d.trim().is_empty())
.unwrap_or_else(|| "info".into());
source.parse().unwrap_or_else(|e| {
warnings.push(format!(
"the {signal} filter {source:?} doesn't parse ({e}); using `info`"
));
"info".parse().expect("`info` parses")
})
}
#[cfg_attr(not(feature = "log"), allow(dead_code))]
fn log_level(directives: &[&Targets], layers: &[BoxedLayer]) -> LevelFilter {
let from_directives = directives
.iter()
.filter_map(|t| <Targets as Filter<Registry>>::max_level_hint(t));
let from_layers = layers
.iter()
.map(|l| l.max_level_hint().unwrap_or(LevelFilter::TRACE));
from_directives
.chain(from_layers)
.max()
.unwrap_or(LevelFilter::OFF)
}
#[cfg(feature = "mappings")]
fn mappings_from_env(warnings: &mut Vec<String>) -> bool {
match std::env::var("OXTEL_MAPPINGS") {
Err(_) => true,
Ok(value) => match value.trim().to_ascii_lowercase().as_str() {
"" | "all" => true,
"none" => false,
other => {
warnings.push(format!(
"OXTEL_MAPPINGS={other:?} isn't `all` or `none`; using `all`"
));
true
}
},
}
}
pub struct Telemetry {
dispatch: Dispatch,
recorder: Option<MetricsRecorder>,
guard: Guard,
warnings: Vec<String>,
trace_context: bool,
#[cfg_attr(not(feature = "log"), allow(dead_code))]
log_level: LevelFilter,
}
impl Telemetry {
pub fn dispatch(&self) -> &Dispatch {
&self.dispatch
}
pub fn recorder(&self) -> Option<&MetricsRecorder> {
self.recorder.as_ref()
}
pub fn guard(&self) -> &Guard {
&self.guard
}
pub fn summary(&self) -> &str {
self.guard.summary()
}
pub fn warnings(&self) -> &[String] {
&self.warnings
}
pub fn into_guard(self) -> Guard {
self.guard
}
pub fn install(self) -> Result<Guard, Error> {
tracing::dispatcher::set_global_default(self.dispatch)
.map_err(|_| Error::SubscriberAlreadySet)?;
if let Some(recorder) = self.recorder {
metrics::set_global_recorder(recorder).map_err(|_| Error::RecorderAlreadySet)?;
}
#[cfg(feature = "log")]
{
let level = match self.log_level.into_level() {
Some(tracing::Level::TRACE) => tracing_log::log::LevelFilter::Trace,
Some(tracing::Level::DEBUG) => tracing_log::log::LevelFilter::Debug,
Some(tracing::Level::INFO) => tracing_log::log::LevelFilter::Info,
Some(tracing::Level::WARN) => tracing_log::log::LevelFilter::Warn,
Some(tracing::Level::ERROR) => tracing_log::log::LevelFilter::Error,
None => tracing_log::log::LevelFilter::Off,
};
if tracing_log::LogTracer::builder()
.with_max_level(level)
.init()
.is_err()
{
tracing::warn!(
target: "oxtel",
"another `log` logger is installed; records from the `log` crate won't reach oxtel"
);
}
}
crate::propagation::set_trace_context(self.trace_context);
tracing::info!(target: "oxtel", "{}", self.guard.summary());
for warning in &self.warnings {
tracing::warn!(target: "oxtel", "{warning}");
}
Ok(self.guard)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Error {
SubscriberAlreadySet,
RecorderAlreadySet,
Config(String),
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Error::SubscriberAlreadySet => {
f.write_str("a global tracing subscriber is already installed")
}
Error::RecorderAlreadySet => {
f.write_str("a global metrics recorder is already installed")
}
Error::Config(e) => f.write_str(e),
}
}
}
impl std::error::Error for Error {}
#[cfg(test)]
mod tests {
use super::*;
fn targets(directives: &str) -> Targets {
directives.parse().unwrap()
}
#[test]
fn the_log_bridge_forwards_what_the_directives_ask_for() {
let info = targets("info");
let mixed = targets("warn,my_app=debug");
assert_eq!(log_level(&[&info], &[]), LevelFilter::INFO);
assert_eq!(log_level(&[&info, &mixed], &[]), LevelFilter::DEBUG);
let layer: BoxedLayer = tracing_subscriber::fmt::layer().boxed();
assert_eq!(log_level(&[&info], &[layer]), LevelFilter::TRACE);
}
#[cfg(feature = "mappings")]
#[test]
fn mappings_open_their_targets_to_the_trace_layer_only() {
let traces = targets("info");
let level = log_level(&[&traces], &[]);
let opened = traces
.clone()
.with_target("sqlx::query", tracing::Level::DEBUG);
assert_eq!(level, LevelFilter::INFO);
assert_eq!(
<Targets as Filter<Registry>>::max_level_hint(&opened),
Some(LevelFilter::DEBUG)
);
}
}