use std::{borrow::Cow, collections::BTreeMap, convert::Infallible, fmt as std_fmt, sync::Mutex};
use serde::{Deserialize, Deserializer, Serialize};
use thiserror::Error;
use time::format_description::well_known::Rfc3339;
use tracing_subscriber::{
EnvFilter,
fmt::{
self,
format::Writer,
time::{FormatTime, OffsetTime, UtcTime},
},
layer::SubscriberExt,
util::SubscriberInitExt,
};
use crate::result::{ClassifyError, ErrorKind};
const RUST_LOG_ENV: &str = "RUST_LOG";
const MAX_TRACE_CONTEXT_VALUE_LENGTH: usize = 128;
pub mod metric_names {
pub const HTTP_SERVER_REQUESTS_TOTAL: &str = "http_server_requests_total";
pub const HTTP_SERVER_REQUEST_DURATION_SECONDS: &str = "http_server_request_duration_seconds";
pub const HTTP_SERVER_ERRORS_TOTAL: &str = "http_server_errors_total";
pub const RATE_LIMIT_DECISIONS_TOTAL: &str = "rate_limit_decisions_total";
pub const IDEMPOTENCY_REQUESTS_TOTAL: &str = "idempotency_requests_total";
pub const WORKER_TICKS_TOTAL: &str = "worker_ticks_total";
pub const WORKER_TICK_DURATION_SECONDS: &str = "worker_tick_duration_seconds";
pub const WORKER_PROCESSED_TOTAL: &str = "worker_processed_total";
pub const WORKER_LEASE_DECISIONS_TOTAL: &str = "worker_lease_decisions_total";
pub const SERVICE_HEALTH: &str = "service_health";
}
pub mod metric_labels {
pub const METHOD: &str = "method";
pub const ROUTE: &str = "route";
pub const STATUS: &str = "status";
pub const ERROR: &str = "error";
pub const OUTCOME: &str = "outcome";
pub const WORKER: &str = "worker";
pub const COMPONENT: &str = "component";
}
pub mod metric_outcomes {
pub const SUCCESS: &str = "success";
pub const FAILURE: &str = "failure";
pub const ALLOWED: &str = "allowed";
pub const DENIED: &str = "denied";
pub const RESERVED: &str = "reserved";
pub const PROCESSING: &str = "processing";
pub const REPLAY: &str = "replay";
pub const CONFLICT: &str = "conflict";
pub const ACQUIRED: &str = "acquired";
pub const BUSY: &str = "busy";
pub const RENEWED: &str = "renewed";
pub const LOST: &str = "lost";
pub const RELEASED: &str = "released";
}
pub mod trace_fields {
pub const EVENT_NAME: &str = "event_name";
pub const EVENT_KIND: &str = "event_kind";
pub const REQUEST_ID: &str = "request_id";
pub const TRACE_ID: &str = "trace_id";
pub const SPAN_ID: &str = "span_id";
pub const ACTOR_ID: &str = "actor_id";
pub const SUBJECT_ID: &str = "subject_id";
pub const SUBJECT_KIND: &str = "subject_kind";
pub const USER_ID: &str = "user_id";
pub const CLIENT_ID: &str = "client_id";
pub const SOURCE_IP: &str = "source_ip";
pub const METHOD: &str = "method";
pub const ROUTE: &str = "route";
pub const PATH: &str = "path";
pub const OPERATION: &str = "operation";
pub const OUTCOME: &str = "outcome";
pub const REASON_CODE: &str = "reason_code";
pub const ERROR_KIND: &str = "error_kind";
pub const ERROR_CODE: &str = "error_code";
pub const WORKER: &str = "worker";
pub const JOB: &str = "job";
pub const RETRY_AFTER_MS: &str = "retry_after_ms";
pub const LATENCY_MS: &str = "latency_ms";
}
pub mod event_names {
pub const HTTP_REQUEST: &str = "http.request";
pub const WORKER_TICK: &str = "worker.tick";
pub const WORKER_BATCH: &str = "worker.batch";
pub const SECURITY_DECISION: &str = "security.decision";
pub const AUDIT_EVENT: &str = "audit.event";
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[non_exhaustive]
pub struct TraceFieldName(String);
impl TraceFieldName {
pub fn new(value: impl Into<String>) -> Result<Self, ObservabilityError> {
let value = value.into().trim().to_owned();
validate_trace_field_name(&value)?;
Ok(Self(value))
}
pub fn try_new(value: impl Into<String>) -> Result<Self, ObservabilityError> {
Self::new(value)
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn into_string(self) -> String {
self.0
}
}
impl std_fmt::Display for TraceFieldName {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter.write_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for TraceFieldName {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
Self::new(String::deserialize(deserializer)?).map_err(serde::de::Error::custom)
}
}
#[derive(Clone, Default, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub struct TraceFields(Vec<(TraceFieldName, String)>);
impl std_fmt::Debug for TraceFields {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("TraceFields")
.field("field_count", &self.0.len())
.finish_non_exhaustive()
}
}
impl TraceFields {
pub fn new(
fields: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
) -> Result<Self, ObservabilityError> {
let mut normalized = BTreeMap::<TraceFieldName, String>::new();
for (key, value) in fields {
let value = value.into();
let key = TraceFieldName::try_new(key)?;
if !value.trim().is_empty() {
normalized.insert(key, value);
}
}
Ok(Self(normalized.into_iter().collect()))
}
#[must_use]
pub fn from_lossy(
fields: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
) -> Self {
let mut normalized = BTreeMap::<TraceFieldName, String>::new();
for (key, value) in fields {
let value = value.into();
if !value.trim().is_empty()
&& let Ok(key) = TraceFieldName::try_new(key)
{
normalized.insert(key, value);
}
}
Self(normalized.into_iter().collect())
}
pub fn single(
key: impl Into<String>,
value: impl Into<String>,
) -> Result<Self, ObservabilityError> {
Self::new([(key, value)])
}
#[must_use]
pub fn with(mut self, key: &'static str, value: impl Into<String>) -> Self {
let value = value.into();
if !value.trim().is_empty()
&& let Ok(key) = TraceFieldName::try_new(key)
{
self.0.push((key, value));
}
Self::from_valid_fields(self.0)
}
pub fn try_with(
mut self,
key: impl Into<String>,
value: impl Into<String>,
) -> Result<Self, ObservabilityError> {
let value = value.into();
let key = TraceFieldName::try_new(key)?;
if !value.trim().is_empty() {
self.0.push((key, value));
}
Ok(Self::from_valid_fields(self.0))
}
#[must_use]
pub fn request_id(self, value: impl Into<String>) -> Self {
self.with(trace_fields::REQUEST_ID, value)
}
#[must_use]
pub fn trace_id(self, value: impl Into<String>) -> Self {
self.with(trace_fields::TRACE_ID, value)
}
#[must_use]
pub fn actor_id(self, value: impl Into<String>) -> Self {
self.with(trace_fields::ACTOR_ID, value)
}
#[must_use]
pub fn user_id(self, value: impl Into<String>) -> Self {
self.with(trace_fields::USER_ID, value)
}
#[must_use]
pub fn client_id(self, value: impl Into<String>) -> Self {
self.with(trace_fields::CLIENT_ID, value)
}
#[must_use]
pub fn source_ip(self, value: impl Into<String>) -> Self {
self.with(trace_fields::SOURCE_IP, value)
}
#[must_use]
pub fn operation(self, value: impl Into<String>) -> Self {
self.with(trace_fields::OPERATION, value)
}
#[must_use]
pub fn outcome(self, value: impl Into<String>) -> Self {
self.with(trace_fields::OUTCOME, value)
}
#[must_use]
pub fn reason_code(self, value: impl Into<String>) -> Self {
self.with(trace_fields::REASON_CODE, value)
}
#[must_use]
pub fn subject_id(self, value: impl Into<String>) -> Self {
self.with(trace_fields::SUBJECT_ID, value)
}
#[must_use]
pub fn subject_kind(self, value: impl Into<String>) -> Self {
self.with(trace_fields::SUBJECT_KIND, value)
}
#[must_use]
pub fn method(self, value: impl Into<String>) -> Self {
self.with(trace_fields::METHOD, value)
}
#[must_use]
pub fn route(self, value: impl Into<String>) -> Self {
self.with(trace_fields::ROUTE, value)
}
#[must_use]
pub fn path(self, value: impl Into<String>) -> Self {
self.with(trace_fields::PATH, value)
}
#[must_use]
pub fn error_kind(self, value: impl Into<String>) -> Self {
self.with(trace_fields::ERROR_KIND, value)
}
#[must_use]
pub fn error_code(self, value: impl Into<String>) -> Self {
self.with(trace_fields::ERROR_CODE, value)
}
#[must_use]
pub fn worker(self, value: impl Into<String>) -> Self {
self.with(trace_fields::WORKER, value)
}
#[must_use]
pub fn job(self, value: impl Into<String>) -> Self {
self.with(trace_fields::JOB, value)
}
#[must_use]
pub fn latency_ms(self, value: impl Into<String>) -> Self {
self.with(trace_fields::LATENCY_MS, value)
}
#[must_use]
pub fn get(&self, key: &str) -> Option<&str> {
self.0
.iter()
.find(|(name, _)| name.as_str() == key)
.map(|(_, value)| value.as_str())
}
#[must_use]
pub fn as_slice(&self) -> &[(TraceFieldName, String)] {
&self.0
}
#[must_use]
pub fn to_btree_map(&self) -> BTreeMap<String, String> {
self.0
.iter()
.map(|(name, value)| (name.as_str().to_owned(), value.clone()))
.collect()
}
#[must_use]
pub fn into_vec(self) -> Vec<(String, String)> {
self.0
.into_iter()
.map(|(name, value)| (name.into_string(), value))
.collect()
}
fn from_valid_fields(fields: impl IntoIterator<Item = (TraceFieldName, String)>) -> Self {
let mut normalized = BTreeMap::<TraceFieldName, String>::new();
for (key, value) in fields {
if !value.trim().is_empty() {
normalized.insert(key, value);
}
}
Self(normalized.into_iter().collect())
}
}
impl<'de> Deserialize<'de> for TraceFields {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let fields = Vec::<(TraceFieldName, String)>::deserialize(deserializer)?;
Ok(Self::from_valid_fields(fields))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum EventKind {
Http,
Worker,
Audit,
Security,
Domain,
}
impl EventKind {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Http => "http",
Self::Worker => "worker",
Self::Audit => "audit",
Self::Security => "security",
Self::Domain => "domain",
}
}
}
impl std_fmt::Display for EventKind {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter.write_str(self.as_str())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum EventOutcome {
Success,
Failure,
Denied,
Skipped,
Retry,
}
impl EventOutcome {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Success => metric_outcomes::SUCCESS,
Self::Failure => metric_outcomes::FAILURE,
Self::Denied => metric_outcomes::DENIED,
Self::Skipped => "skipped",
Self::Retry => "retry",
}
}
}
impl std_fmt::Display for EventOutcome {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter.write_str(self.as_str())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub struct StructuredEvent {
name: String,
kind: EventKind,
fields: TraceFields,
}
impl<'de> Deserialize<'de> for StructuredEvent {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct StructuredEventWire {
name: String,
kind: EventKind,
#[serde(default)]
fields: TraceFields,
}
let wire = StructuredEventWire::deserialize(deserializer)?;
Ok(Self::new(wire.name, wire.kind)
.map_err(serde::de::Error::custom)?
.with_fields(wire.fields))
}
}
impl StructuredEvent {
pub fn new(name: impl Into<String>, kind: EventKind) -> Result<Self, ObservabilityError> {
let name = name.into().trim().to_owned();
validate_event_name(&name)?;
Ok(Self::from_valid_parts(name, kind))
}
pub fn try_new(name: impl Into<String>, kind: EventKind) -> Result<Self, ObservabilityError> {
Self::new(name, kind)
}
fn from_valid_parts(name: String, kind: EventKind) -> Self {
Self {
name,
kind,
fields: TraceFields::default(),
}
}
pub fn builder(
name: impl Into<String>,
kind: EventKind,
) -> Result<StructuredEventBuilder, ObservabilityError> {
StructuredEventBuilder::new(name, kind)
}
#[must_use]
pub fn http_request() -> StructuredEventBuilder {
StructuredEventBuilder::from_valid_event(Self::from_valid_parts(
event_names::HTTP_REQUEST.to_owned(),
EventKind::Http,
))
}
#[must_use]
pub fn worker_tick(worker: impl Into<String>) -> StructuredEventBuilder {
StructuredEventBuilder::from_valid_event(Self::from_valid_parts(
event_names::WORKER_TICK.to_owned(),
EventKind::Worker,
))
.worker(worker)
}
#[must_use]
pub fn security_decision() -> StructuredEventBuilder {
StructuredEventBuilder::from_valid_event(Self::from_valid_parts(
event_names::SECURITY_DECISION.to_owned(),
EventKind::Security,
))
}
#[must_use]
pub fn audit_event() -> StructuredEventBuilder {
StructuredEventBuilder::from_valid_event(Self::from_valid_parts(
event_names::AUDIT_EVENT.to_owned(),
EventKind::Audit,
))
}
#[must_use]
pub fn with_fields(mut self, fields: TraceFields) -> Self {
self.fields = fields;
self
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub const fn kind(&self) -> EventKind {
self.kind
}
#[must_use]
pub const fn fields(&self) -> &TraceFields {
&self.fields
}
#[must_use]
pub fn trace_fields(&self) -> TraceFields {
self.fields
.clone()
.with(trace_fields::EVENT_NAME, self.name.clone())
.with(trace_fields::EVENT_KIND, self.kind.as_str())
}
#[must_use]
pub fn into_trace_fields(self) -> TraceFields {
self.fields
.with(trace_fields::EVENT_NAME, self.name)
.with(trace_fields::EVENT_KIND, self.kind.as_str())
}
#[must_use]
pub fn to_btree_map(&self) -> BTreeMap<String, String> {
self.trace_fields().to_btree_map()
}
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct StructuredEventBuilder {
event: StructuredEvent,
}
impl StructuredEventBuilder {
pub fn new(name: impl Into<String>, kind: EventKind) -> Result<Self, ObservabilityError> {
Ok(Self {
event: StructuredEvent::new(name, kind)?,
})
}
fn from_valid_event(event: StructuredEvent) -> Self {
Self { event }
}
#[must_use]
pub fn field(mut self, key: &'static str, value: impl Into<String>) -> Self {
self.event.fields = self.event.fields.with(key, value);
self
}
pub fn try_field(
mut self,
key: impl Into<String>,
value: impl Into<String>,
) -> Result<Self, ObservabilityError> {
self.event.fields = self.event.fields.try_with(key, value)?;
Ok(self)
}
#[must_use]
pub fn fields(mut self, fields: TraceFields) -> Self {
let current = std::mem::take(&mut self.event.fields).into_vec();
self.event.fields = TraceFields::from_lossy(current.into_iter().chain(fields.into_vec()));
self
}
#[must_use]
pub fn outcome(self, outcome: EventOutcome) -> Self {
self.field(trace_fields::OUTCOME, outcome.as_str())
}
#[must_use]
pub fn request_id(self, value: impl Into<String>) -> Self {
self.field(trace_fields::REQUEST_ID, value)
}
#[must_use]
pub fn actor_id(self, value: impl Into<String>) -> Self {
self.field(trace_fields::ACTOR_ID, value)
}
#[must_use]
pub fn subject_id(self, value: impl Into<String>) -> Self {
self.field(trace_fields::SUBJECT_ID, value)
}
#[must_use]
pub fn subject_kind(self, value: impl Into<String>) -> Self {
self.field(trace_fields::SUBJECT_KIND, value)
}
#[must_use]
pub fn user_id(self, value: impl Into<String>) -> Self {
self.field(trace_fields::USER_ID, value)
}
#[must_use]
pub fn client_id(self, value: impl Into<String>) -> Self {
self.field(trace_fields::CLIENT_ID, value)
}
#[must_use]
pub fn source_ip(self, value: impl Into<String>) -> Self {
self.field(trace_fields::SOURCE_IP, value)
}
#[must_use]
pub fn operation(self, value: impl Into<String>) -> Self {
self.field(trace_fields::OPERATION, value)
}
#[must_use]
pub fn reason_code(self, value: impl Into<String>) -> Self {
self.field(trace_fields::REASON_CODE, value)
}
#[must_use]
pub fn method(self, value: impl Into<String>) -> Self {
self.field(trace_fields::METHOD, value)
}
#[must_use]
pub fn route(self, value: impl Into<String>) -> Self {
self.field(trace_fields::ROUTE, value)
}
#[must_use]
pub fn path(self, value: impl Into<String>) -> Self {
self.field(trace_fields::PATH, value)
}
#[must_use]
pub fn error_kind(self, value: impl Into<String>) -> Self {
self.field(trace_fields::ERROR_KIND, value)
}
#[must_use]
pub fn error_code(self, value: impl Into<String>) -> Self {
self.field(trace_fields::ERROR_CODE, value)
}
#[must_use]
pub fn worker(self, value: impl Into<String>) -> Self {
self.field(trace_fields::WORKER, value)
}
#[must_use]
pub fn job(self, value: impl Into<String>) -> Self {
self.field(trace_fields::JOB, value)
}
#[must_use]
pub fn latency_ms(self, value: impl Into<String>) -> Self {
self.field(trace_fields::LATENCY_MS, value)
}
#[must_use]
pub fn build(self) -> StructuredEvent {
self.event
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct TracingConfig {
service_name: String,
json: bool,
env_filter: Option<String>,
time_zone: LogTimeZone,
}
impl TracingConfig {
#[must_use]
pub fn new(service_name: impl Into<String>) -> Self {
Self {
service_name: service_name.into().trim().to_owned(),
json: false,
env_filter: None,
time_zone: LogTimeZone::Utc,
}
}
pub fn try_new(service_name: impl Into<String>) -> Result<Self, ObservabilityError> {
let config = Self::new(service_name);
config.validate()?;
Ok(config)
}
#[must_use]
pub fn with_json(mut self, json: bool) -> Self {
self.json = json;
self
}
#[must_use]
pub fn with_env_filter(mut self, env_filter: impl Into<String>) -> Self {
self.env_filter = Some(env_filter.into().trim().to_owned());
self
}
#[must_use]
pub const fn with_time_zone(mut self, time_zone: LogTimeZone) -> Self {
self.time_zone = time_zone;
self
}
#[must_use]
pub fn service_name(&self) -> &str {
&self.service_name
}
#[must_use]
pub const fn json(&self) -> bool {
self.json
}
#[must_use]
pub fn env_filter(&self) -> Option<&str> {
self.env_filter.as_deref()
}
#[must_use]
pub const fn time_zone(&self) -> LogTimeZone {
self.time_zone
}
pub fn validate(&self) -> Result<(), ObservabilityError> {
validate_service_name(&self.service_name)
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum LogTimeZone {
#[default]
Utc,
Local,
}
impl LogTimeZone {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Utc => "utc",
Self::Local => "local",
}
}
}
#[derive(Debug, Clone)]
enum Rfc3339Timer {
Utc(UtcTime<Rfc3339>),
Local(OffsetTime<Rfc3339>),
}
impl Rfc3339Timer {
fn new(time_zone: LogTimeZone) -> Result<Self, ObservabilityError> {
match time_zone {
LogTimeZone::Utc => Ok(Self::Utc(UtcTime::rfc_3339())),
LogTimeZone::Local => Ok(Self::Local(
OffsetTime::local_rfc_3339().map_err(ObservabilityError::LocalTimeOffset)?,
)),
}
}
}
impl FormatTime for Rfc3339Timer {
fn format_time(&self, writer: &mut Writer<'_>) -> std_fmt::Result {
match self {
Self::Utc(timer) => timer.format_time(writer),
Self::Local(timer) => timer.format_time(writer),
}
}
}
#[derive(Error)]
#[non_exhaustive]
pub enum ObservabilityError {
#[error(
"tracing service name must be non-empty and contain only ASCII letters, digits, '-', '_', '.', or ':'"
)]
InvalidServiceName,
#[error("tracing env filter is invalid")]
InvalidFilter(#[from] tracing_subscriber::filter::ParseError),
#[error("tracing subscriber initialization failed")]
Init(#[from] tracing_subscriber::util::TryInitError),
#[error("local log timestamp offset could not be determined")]
LocalTimeOffset(#[source] time::error::IndeterminateOffset),
#[error("trace field name is invalid")]
InvalidTraceFieldName,
#[error("event name is invalid")]
InvalidEventName,
#[error("health resource name is invalid")]
InvalidHealthName,
}
impl std_fmt::Debug for ObservabilityError {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("ObservabilityError")
.field("code", &self.error_code())
.finish_non_exhaustive()
}
}
impl ClassifyError for ObservabilityError {
fn error_kind(&self) -> ErrorKind {
match self {
Self::InvalidServiceName
| Self::InvalidFilter(_)
| Self::InvalidTraceFieldName
| Self::InvalidEventName
| Self::InvalidHealthName => ErrorKind::Validation,
Self::LocalTimeOffset(_) => ErrorKind::Unavailable,
Self::Init(_) => ErrorKind::Conflict,
}
}
fn error_code(&self) -> Cow<'static, str> {
Cow::Borrowed(match self {
Self::InvalidServiceName => "tracing_service_name_invalid",
Self::InvalidFilter(_) => "tracing_filter_invalid",
Self::Init(_) => "tracing_subscriber_init_failed",
Self::LocalTimeOffset(_) => "tracing_local_time_offset_unavailable",
Self::InvalidTraceFieldName => "trace_field_name_invalid",
Self::InvalidEventName => "event_name_invalid",
Self::InvalidHealthName => "health_name_invalid",
})
}
}
pub fn init(service_name: &str, json: bool) -> Result<(), ObservabilityError> {
try_init(&TracingConfig::new(service_name).with_json(json))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum HealthState {
Serving,
Degraded,
Unavailable,
}
impl HealthState {
#[must_use]
pub const fn healthy(self) -> bool {
matches!(self, Self::Serving)
}
}
#[derive(Clone, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub struct HealthCheck {
name: String,
state: HealthState,
message: Option<String>,
}
impl std_fmt::Debug for HealthCheck {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("HealthCheck")
.field("name", &self.name)
.field("state", &self.state)
.field("message", &self.message.as_ref().map(|_| "[REDACTED]"))
.finish()
}
}
impl HealthCheck {
pub fn new(name: impl Into<String>, state: HealthState) -> Result<Self, ObservabilityError> {
let name = normalize_health_name(name)?;
Ok(Self {
name,
state,
message: None,
})
}
pub fn serving(name: impl Into<String>) -> Result<Self, ObservabilityError> {
Self::new(name, HealthState::Serving)
}
#[must_use]
pub fn new_lossy(name: impl Into<String>, state: HealthState) -> Self {
Self {
name: normalize_health_name(name).unwrap_or_else(|_| "component".to_owned()),
state,
message: None,
}
}
#[must_use]
pub fn serving_lossy(name: impl Into<String>) -> Self {
Self::new_lossy(name, HealthState::Serving)
}
pub fn unavailable(
name: impl Into<String>,
message: impl Into<String>,
) -> Result<Self, ObservabilityError> {
Ok(Self::new(name, HealthState::Unavailable)?.with_message(message))
}
#[must_use]
pub fn with_message(mut self, message: impl Into<String>) -> Self {
let message = message.into();
if !message.trim().is_empty() {
self.message = Some(message);
}
self
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub const fn state(&self) -> HealthState {
self.state
}
#[must_use]
pub fn message(&self) -> Option<&str> {
self.message.as_deref()
}
}
impl<'de> Deserialize<'de> for HealthCheck {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct HealthCheckWire {
name: String,
state: HealthState,
message: Option<String>,
}
let wire = HealthCheckWire::deserialize(deserializer)?;
let mut check = Self::new(wire.name, wire.state).map_err(serde::de::Error::custom)?;
if let Some(message) = wire.message {
check = check.with_message(message);
}
Ok(check)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub struct HealthReport {
service: String,
state: HealthState,
checks: Vec<HealthCheck>,
}
impl HealthReport {
pub fn new(
service: impl Into<String>,
checks: Vec<HealthCheck>,
) -> Result<Self, ObservabilityError> {
let service = normalize_health_name(service)?;
let state = aggregate_health(&checks);
Ok(Self {
service,
state,
checks,
})
}
pub fn serving(service: impl Into<String>) -> Result<Self, ObservabilityError> {
Self::new(service, Vec::new())
}
#[must_use]
pub fn new_lossy(service: impl Into<String>, checks: Vec<HealthCheck>) -> Self {
let state = aggregate_health(&checks);
Self {
service: normalize_health_name(service).unwrap_or_else(|_| "service".to_owned()),
state,
checks,
}
}
#[must_use]
pub fn serving_lossy(service: impl Into<String>) -> Self {
Self::new_lossy(service, Vec::new())
}
#[must_use]
pub fn service(&self) -> &str {
&self.service
}
#[must_use]
pub const fn state(&self) -> HealthState {
self.state
}
#[must_use]
pub fn checks(&self) -> &[HealthCheck] {
&self.checks
}
}
impl<'de> Deserialize<'de> for HealthReport {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct HealthReportWire {
service: String,
#[serde(rename = "state")]
#[serde(default)]
_state: Option<HealthState>,
#[serde(default)]
checks: Vec<HealthCheck>,
}
let wire = HealthReportWire::deserialize(deserializer)?;
Self::new(wire.service, wire.checks).map_err(serde::de::Error::custom)
}
}
fn aggregate_health(checks: &[HealthCheck]) -> HealthState {
if checks
.iter()
.any(|check| check.state == HealthState::Unavailable)
{
HealthState::Unavailable
} else if checks
.iter()
.any(|check| check.state == HealthState::Degraded)
{
HealthState::Degraded
} else {
HealthState::Serving
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum MetricKind {
Counter,
Gauge,
Histogram,
}
#[derive(Clone, PartialEq, Serialize)]
#[non_exhaustive]
pub struct MetricSample {
name: String,
kind: MetricKind,
value: f64,
labels: Vec<(String, String)>,
#[serde(skip_serializing_if = "Option::is_none")]
count: Option<u64>,
}
impl std_fmt::Debug for MetricSample {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("MetricSample")
.field("name", &self.name)
.field("kind", &self.kind)
.field("value", &self.value)
.field("label_count", &self.labels.len())
.field("count", &self.count)
.finish()
}
}
impl MetricSample {
pub fn new(
name: impl Into<String>,
kind: MetricKind,
value: f64,
) -> Result<Self, MetricsError> {
validate_metric_value(value)?;
let name = normalize_metric_name(name)?;
Ok(Self::from_valid_parts(name, kind, value))
}
fn from_valid_parts(name: String, kind: MetricKind, value: f64) -> Self {
Self {
name,
kind,
value,
labels: Vec::new(),
count: None,
}
}
pub fn counter(name: impl Into<String>, value: u64) -> Result<Self, MetricsError> {
let name = normalize_metric_name(name)?;
Ok(Self::from_valid_parts(
name,
MetricKind::Counter,
value as f64,
))
}
pub fn gauge(name: impl Into<String>, value: f64) -> Result<Self, MetricsError> {
Self::new(name, MetricKind::Gauge, value)
}
pub fn histogram(name: impl Into<String>, count: u64, sum: f64) -> Result<Self, MetricsError> {
Ok(Self::new(name, MetricKind::Histogram, sum)?.with_count(count))
}
#[must_use]
pub fn with_label(mut self, key: &'static str, value: impl Into<String>) -> Self {
self.labels = MetricLabels::from_lossy(
self.labels
.into_iter()
.chain([(key.to_owned(), value.into())]),
)
.into_vec();
self
}
pub fn try_with_label(
mut self,
key: impl Into<String>,
value: impl Into<String>,
) -> Result<Self, MetricsError> {
self.labels.push((key.into(), value.into()));
self.labels = MetricLabels::new(self.labels)?.into_vec();
Ok(self)
}
#[must_use]
pub fn with_labels(mut self, labels: MetricLabels) -> Self {
self.labels = labels.into_vec();
self
}
#[must_use]
pub const fn with_count(mut self, count: u64) -> Self {
self.count = Some(count);
self
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub const fn kind(&self) -> MetricKind {
self.kind
}
#[must_use]
pub const fn value(&self) -> f64 {
self.value
}
#[must_use]
pub const fn count(&self) -> Option<u64> {
self.count
}
#[must_use]
pub fn labels(&self) -> &[(String, String)] {
&self.labels
}
}
impl<'de> Deserialize<'de> for MetricSample {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct MetricSampleWire {
name: String,
kind: MetricKind,
value: f64,
#[serde(default)]
labels: MetricLabels,
#[serde(default)]
count: Option<u64>,
}
let wire = MetricSampleWire::deserialize(deserializer)?;
let mut sample =
Self::new(wire.name, wire.kind, wire.value).map_err(serde::de::Error::custom)?;
sample = sample.with_labels(wire.labels);
if let Some(count) = wire.count {
sample = sample.with_count(count);
}
Ok(sample)
}
}
#[derive(Clone, Default, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[non_exhaustive]
pub struct MetricLabels(Vec<(String, String)>);
impl std_fmt::Debug for MetricLabels {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("MetricLabels")
.field("label_count", &self.0.len())
.finish_non_exhaustive()
}
}
impl MetricLabels {
pub fn new(
labels: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
) -> Result<Self, MetricsError> {
let mut normalized = BTreeMap::<String, String>::new();
for (key, value) in labels {
let key = normalize_metric_name(key)?;
normalized.insert(key, value.into());
}
Ok(Self(normalized.into_iter().collect()))
}
#[must_use]
pub fn from_lossy(
labels: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
) -> Self {
let mut normalized = BTreeMap::<String, String>::new();
for (key, value) in labels {
if let Ok(key) = normalize_metric_name(key) {
normalized.insert(key, value.into());
}
}
Self(normalized.into_iter().collect())
}
pub fn single(key: impl Into<String>, value: impl Into<String>) -> Result<Self, MetricsError> {
Self::new([(key, value)])
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.0.is_empty()
}
#[must_use]
pub fn as_slice(&self) -> &[(String, String)] {
&self.0
}
#[must_use]
pub fn get(&self, key: &str) -> Option<&str> {
let key = normalize_metric_name(key).ok()?;
self.0
.iter()
.find(|(name, _)| name == &key)
.map(|(_, value)| value.as_str())
}
#[must_use]
pub fn to_btree_map(&self) -> BTreeMap<String, String> {
self.0.iter().cloned().collect()
}
#[must_use]
pub fn into_vec(self) -> Vec<(String, String)> {
self.0
}
}
impl<'de> Deserialize<'de> for MetricLabels {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
Self::new(Vec::<(String, String)>::deserialize(deserializer)?)
.map_err(serde::de::Error::custom)
}
}
#[derive(Clone, Default, PartialEq, Serialize)]
#[non_exhaustive]
pub struct MetricsSnapshot {
samples: Vec<MetricSample>,
}
impl std_fmt::Debug for MetricsSnapshot {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("MetricsSnapshot")
.field("sample_count", &self.samples.len())
.finish_non_exhaustive()
}
}
impl MetricsSnapshot {
#[must_use]
pub fn new(samples: Vec<MetricSample>) -> Self {
Self { samples }
}
pub fn push(&mut self, sample: MetricSample) {
self.samples.push(sample);
}
#[must_use]
pub fn samples(&self) -> &[MetricSample] {
&self.samples
}
}
impl<'de> Deserialize<'de> for MetricsSnapshot {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
Ok(Self::new(Vec::<MetricSample>::deserialize(deserializer)?))
}
}
pub trait MetricRecorder: Send + Sync + 'static {
fn increment_counter(
&self,
name: &str,
value: u64,
labels: MetricLabels,
) -> Result<(), MetricsError>;
fn set_gauge(&self, name: &str, value: f64, labels: MetricLabels) -> Result<(), MetricsError>;
fn observe_histogram(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError>;
fn snapshot(&self) -> Result<MetricsSnapshot, MetricsError>;
}
#[derive(Default)]
#[non_exhaustive]
pub struct MetricRegistry {
values: Mutex<BTreeMap<MetricIdentity, MetricAggregate>>,
}
impl std_fmt::Debug for MetricRegistry {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("MetricRegistry")
.field(
"metric_count",
&self.values.try_lock().ok().map(|values| values.len()),
)
.finish_non_exhaustive()
}
}
impl MetricRegistry {
#[must_use]
pub fn new() -> Self {
Self::default()
}
pub fn increment_counter(
&self,
name: &str,
value: u64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
MetricRecorder::increment_counter(self, name, value, labels)
}
pub fn set_gauge(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
MetricRecorder::set_gauge(self, name, value, labels)
}
pub fn observe_histogram(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
MetricRecorder::observe_histogram(self, name, value, labels)
}
pub fn snapshot(&self) -> Result<MetricsSnapshot, MetricsError> {
MetricRecorder::snapshot(self)
}
}
impl MetricRecorder for MetricRegistry {
fn increment_counter(
&self,
name: &str,
value: u64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
let identity = MetricIdentity::new(name, MetricKind::Counter, labels)?;
let mut values = self.values.lock().map_err(|_| MetricsError::LockPoisoned)?;
match values.entry(identity) {
std::collections::btree_map::Entry::Occupied(mut entry) => {
let aggregate = entry.get_mut();
aggregate.value = finite_metric_sum(aggregate.value, value as f64)?;
}
std::collections::btree_map::Entry::Vacant(entry) => {
entry.insert(MetricAggregate {
value: value as f64,
count: None,
});
}
}
Ok(())
}
fn set_gauge(&self, name: &str, value: f64, labels: MetricLabels) -> Result<(), MetricsError> {
validate_metric_value(value)?;
let identity = MetricIdentity::new(name, MetricKind::Gauge, labels)?;
let mut values = self.values.lock().map_err(|_| MetricsError::LockPoisoned)?;
values.insert(identity, MetricAggregate { value, count: None });
Ok(())
}
fn observe_histogram(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
validate_metric_value(value)?;
let identity = MetricIdentity::new(name, MetricKind::Histogram, labels)?;
let mut values = self.values.lock().map_err(|_| MetricsError::LockPoisoned)?;
match values.entry(identity) {
std::collections::btree_map::Entry::Occupied(mut entry) => {
let aggregate = entry.get_mut();
aggregate.value = finite_metric_sum(aggregate.value, value)?;
aggregate.count = Some(aggregate.count.map_or(1, |count| count.saturating_add(1)));
}
std::collections::btree_map::Entry::Vacant(entry) => {
entry.insert(MetricAggregate {
value,
count: Some(1),
});
}
}
Ok(())
}
fn snapshot(&self) -> Result<MetricsSnapshot, MetricsError> {
let values = self.values.lock().map_err(|_| MetricsError::LockPoisoned)?;
let samples = values
.iter()
.map(|(identity, aggregate)| {
let mut sample =
MetricSample::new(identity.name.clone(), identity.kind, aggregate.value)?
.with_labels(identity.labels.clone());
if let Some(count) = aggregate.count {
sample = sample.with_count(count);
}
Ok(sample)
})
.collect::<Result<_, MetricsError>>()?;
Ok(MetricsSnapshot::new(samples))
}
}
fn finite_metric_sum(left: f64, right: f64) -> Result<f64, MetricsError> {
let sum = left + right;
validate_metric_value(sum)?;
Ok(sum)
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct MetricIdentity {
name: String,
kind: MetricKind,
labels: MetricLabels,
}
impl MetricIdentity {
fn new(
name: impl Into<String>,
kind: MetricKind,
labels: MetricLabels,
) -> Result<Self, MetricsError> {
Ok(Self {
name: normalize_metric_name(name)?,
kind,
labels,
})
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
struct MetricAggregate {
value: f64,
count: Option<u64>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum MetricsError {
#[error("metrics registry lock is poisoned")]
LockPoisoned,
#[error("metric name must not be empty")]
InvalidName,
#[error("metric value must be finite")]
InvalidValue,
}
impl ClassifyError for MetricsError {
fn error_kind(&self) -> ErrorKind {
match self {
Self::LockPoisoned => ErrorKind::Unavailable,
Self::InvalidName | Self::InvalidValue => ErrorKind::Validation,
}
}
fn error_code(&self) -> Cow<'static, str> {
Cow::Borrowed(match self {
Self::LockPoisoned => "metrics_registry_unavailable",
Self::InvalidName => "metric_name_invalid",
Self::InvalidValue => "metric_value_invalid",
})
}
}
#[must_use]
pub fn encode_openmetrics(snapshot: &MetricsSnapshot) -> String {
let mut output = String::new();
let mut emitted_types = BTreeMap::<String, MetricKind>::new();
for sample in snapshot.samples() {
let name = sample.name();
if let std::collections::btree_map::Entry::Vacant(entry) =
emitted_types.entry(name.to_owned())
{
entry.insert(sample.kind());
output.push_str("# TYPE ");
output.push_str(name);
output.push(' ');
output.push_str(openmetrics_kind(sample.kind()));
output.push('\n');
}
match (sample.kind(), sample.count()) {
(MetricKind::Histogram, Some(count)) => {
output.push_str(name);
output.push_str("_sum");
output.push_str(&encode_labels(sample.labels()));
output.push(' ');
output.push_str(&format_float(sample.value()));
output.push('\n');
output.push_str(name);
output.push_str("_count");
output.push_str(&encode_labels(sample.labels()));
output.push(' ');
output.push_str(&count.to_string());
output.push('\n');
}
_ => {
output.push_str(name);
output.push_str(&encode_labels(sample.labels()));
output.push(' ');
output.push_str(&format_float(sample.value()));
output.push('\n');
}
}
}
output.push_str("# EOF\n");
output
}
#[derive(Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct MetricsExport {
content_type: String,
body: String,
}
impl std_fmt::Debug for MetricsExport {
fn fmt(&self, formatter: &mut std_fmt::Formatter<'_>) -> std_fmt::Result {
formatter
.debug_struct("MetricsExport")
.field("content_type", &self.content_type)
.field("body_bytes", &self.body.len())
.finish()
}
}
impl MetricsExport {
#[must_use]
pub fn new(content_type: impl Into<String>, body: impl Into<String>) -> Self {
Self {
content_type: content_type.into(),
body: body.into(),
}
}
#[must_use]
pub fn content_type(&self) -> &str {
&self.content_type
}
#[must_use]
pub fn body(&self) -> &str {
&self.body
}
#[must_use]
pub fn into_body(self) -> String {
self.body
}
}
pub trait MetricsExporter {
type Error;
fn export(&self, snapshot: &MetricsSnapshot) -> Result<MetricsExport, Self::Error>;
}
#[derive(Debug, Clone, Copy, Default)]
#[non_exhaustive]
pub struct OpenMetricsExporter;
impl OpenMetricsExporter {
pub const CONTENT_TYPE: &'static str =
"application/openmetrics-text; version=1.0.0; charset=utf-8";
}
impl MetricsExporter for OpenMetricsExporter {
type Error = Infallible;
fn export(&self, snapshot: &MetricsSnapshot) -> Result<MetricsExport, Self::Error> {
Ok(MetricsExport::new(
Self::CONTENT_TYPE,
encode_openmetrics(snapshot),
))
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub struct TraceContext {
trace_id: Option<String>,
span_id: Option<String>,
request_id: Option<String>,
}
impl TraceContext {
#[must_use]
pub fn new(
trace_id: Option<String>,
span_id: Option<String>,
request_id: Option<String>,
) -> Self {
Self {
trace_id: normalize_trace_context_value(trace_id),
span_id: normalize_trace_context_value(span_id),
request_id: normalize_trace_context_value(request_id),
}
}
#[must_use]
pub fn trace_id(&self) -> Option<&str> {
self.trace_id.as_deref()
}
#[must_use]
pub fn span_id(&self) -> Option<&str> {
self.span_id.as_deref()
}
#[must_use]
pub fn request_id(&self) -> Option<&str> {
self.request_id.as_deref()
}
#[must_use]
pub const fn is_empty(&self) -> bool {
self.trace_id.is_none() && self.span_id.is_none() && self.request_id.is_none()
}
}
impl<'de> Deserialize<'de> for TraceContext {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct TraceContextWire {
#[serde(default)]
trace_id: Option<String>,
#[serde(default)]
span_id: Option<String>,
#[serde(default)]
request_id: Option<String>,
}
let wire = TraceContextWire::deserialize(deserializer)?;
Ok(Self::new(wire.trace_id, wire.span_id, wire.request_id))
}
}
pub fn try_init(config: &TracingConfig) -> Result<(), ObservabilityError> {
config.validate()?;
let env_filter = env_filter(config)?;
let timer = Rfc3339Timer::new(config.time_zone)?;
if config.json {
tracing_subscriber::registry()
.with(env_filter)
.with(fmt::layer().with_timer(timer).json())
.try_init()?;
} else {
tracing_subscriber::registry()
.with(env_filter)
.with(fmt::layer().with_timer(timer))
.try_init()?;
}
Ok(())
}
fn env_filter(config: &TracingConfig) -> Result<EnvFilter, ObservabilityError> {
env_filter_from(config, std::env::var(RUST_LOG_ENV).ok())
}
fn env_filter_from(
config: &TracingConfig,
env_value: Option<String>,
) -> Result<EnvFilter, ObservabilityError> {
config.validate()?;
if let Some(value) = env_value
.as_deref()
.map(str::trim)
.filter(|value| !value.is_empty())
{
return Ok(EnvFilter::try_new(value)?);
}
if let Some(value) = config
.env_filter
.as_deref()
.map(str::trim)
.filter(|value| !value.is_empty())
{
return Ok(EnvFilter::try_new(value)?);
}
Ok(EnvFilter::try_new("info,tower_http=info")?)
}
fn validate_service_name(value: &str) -> Result<(), ObservabilityError> {
if value.is_empty()
|| !value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b':'))
{
return Err(ObservabilityError::InvalidServiceName);
}
Ok(())
}
fn validate_trace_field_name(value: &str) -> Result<(), ObservabilityError> {
if value.is_empty()
|| !value
.bytes()
.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_')
{
return Err(ObservabilityError::InvalidTraceFieldName);
}
Ok(())
}
fn validate_event_name(value: &str) -> Result<(), ObservabilityError> {
if value.is_empty()
|| !value.bytes().all(|byte| {
byte.is_ascii_lowercase()
|| byte.is_ascii_digit()
|| matches!(byte, b'-' | b'_' | b'.' | b':')
})
{
return Err(ObservabilityError::InvalidEventName);
}
Ok(())
}
fn normalize_trace_context_value(value: Option<String>) -> Option<String> {
let value = value?.trim().to_owned();
if value.is_empty()
|| value.len() > MAX_TRACE_CONTEXT_VALUE_LENGTH
|| !value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b':'))
{
return None;
}
Some(value)
}
fn normalize_health_name(value: impl Into<String>) -> Result<String, ObservabilityError> {
let value = value.into().trim().to_owned();
if value.is_empty()
|| !value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b':'))
{
return Err(ObservabilityError::InvalidHealthName);
}
Ok(value)
}
fn normalize_metric_name(value: impl Into<String>) -> Result<String, MetricsError> {
let value = value.into();
let value = value.trim();
if value.is_empty() {
return Err(MetricsError::InvalidName);
}
let mut normalized = String::with_capacity(value.len().max(1));
for byte in value.bytes() {
if byte.is_ascii_alphanumeric() || byte == b':' || byte == b'_' {
normalized.push(char::from(byte));
} else {
normalized.push('_');
}
}
if normalized.as_bytes().first().is_none_or(u8::is_ascii_digit) {
normalized.insert(0, '_');
}
Ok(normalized)
}
fn validate_metric_value(value: f64) -> Result<(), MetricsError> {
if value.is_finite() {
Ok(())
} else {
Err(MetricsError::InvalidValue)
}
}
fn openmetrics_kind(kind: MetricKind) -> &'static str {
match kind {
MetricKind::Counter => "counter",
MetricKind::Gauge => "gauge",
MetricKind::Histogram => "histogram",
}
}
fn encode_labels(labels: &[(String, String)]) -> String {
if labels.is_empty() {
return String::new();
}
let mut output = String::from("{");
for (index, (key, value)) in labels.iter().enumerate() {
if index > 0 {
output.push(',');
}
output.push_str(key);
output.push_str("=\"");
output.push_str(&escape_label_value(value));
output.push('"');
}
output.push('}');
output
}
fn escape_label_value(value: &str) -> String {
let mut escaped = String::with_capacity(value.len());
for character in value.chars() {
match character {
'\\' => escaped.push_str("\\\\"),
'"' => escaped.push_str("\\\""),
'\n' => escaped.push_str("\\n"),
_ => escaped.push(character),
}
}
escaped
}
fn format_float(value: f64) -> String {
if value.is_finite() {
value.to_string()
} else {
"0".to_owned()
}
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::{
EventKind, EventOutcome, HealthCheck, HealthReport, HealthState, LogTimeZone, MetricKind,
MetricLabels, MetricRegistry, MetricSample, MetricsError, MetricsExporter, MetricsSnapshot,
ObservabilityError, OpenMetricsExporter, StructuredEvent, TraceContext, TraceFieldName,
TraceFields, TracingConfig, encode_openmetrics, env_filter_from, event_names,
metric_outcomes, trace_fields,
};
use crate::result::{ClassifyError, ErrorKind};
#[test]
fn builds_default_filter_from_service_name() {
let filter = env_filter_from(&TracingConfig::new("example_service"), None)
.expect("filter should be valid");
assert_eq!(filter.to_string(), "tower_http=info,info");
}
#[test]
fn rejects_invalid_service_name() {
let result = env_filter_from(&TracingConfig::new("bad service"), None);
assert!(matches!(
result,
Err(ObservabilityError::InvalidServiceName)
));
}
#[test]
fn observability_errors_have_stable_classification() {
let service_name = ObservabilityError::InvalidServiceName.error_descriptor();
let event_name = StructuredEvent::try_new("Bad Event", EventKind::Domain)
.expect_err("event name should be invalid")
.error_descriptor();
assert_eq!(service_name.kind(), ErrorKind::Validation);
assert_eq!(service_name.code().as_str(), "tracing_service_name_invalid");
assert_eq!(event_name.kind(), ErrorKind::Validation);
assert_eq!(event_name.code().as_str(), "event_name_invalid");
}
#[test]
fn env_filter_overrides_config_filter() {
let filter = env_filter_from(
&TracingConfig::new("example_service").with_env_filter("=bad"),
Some("example_service=debug".to_owned()),
)
.expect("environment filter should override config filter");
assert_eq!(filter.to_string(), "example_service=debug");
}
#[test]
fn tracing_config_defaults_to_utc_timestamps() {
let config = TracingConfig::new("example_service");
assert_eq!(config.time_zone(), LogTimeZone::Utc);
assert_eq!(
config.with_time_zone(LogTimeZone::Local).time_zone(),
LogTimeZone::Local
);
assert_eq!(LogTimeZone::Utc.as_str(), "utc");
assert_eq!(LogTimeZone::Local.as_str(), "local");
}
#[test]
fn rejects_invalid_explicit_filter_without_env_override() {
let result = env_filter_from(
&TracingConfig::new("example_service").with_env_filter("=bad"),
None,
);
let error = result.expect_err("invalid filter should fail");
assert!(matches!(&error, ObservabilityError::InvalidFilter(_)));
assert!(!format!("{error:?}").contains("=bad"));
}
#[test]
fn rejects_invalid_env_filter() {
let result = env_filter_from(
&TracingConfig::new("example_service"),
Some("=bad".to_owned()),
);
assert!(matches!(result, Err(ObservabilityError::InvalidFilter(_))));
}
#[test]
fn health_report_aggregates_checks() {
let report = HealthReport::new(
"example_service",
vec![
HealthCheck::serving("database").expect("health check should be valid"),
HealthCheck::unavailable("mail", "smtp unavailable")
.expect("health check should be valid"),
],
)
.expect("health report should be valid");
assert_eq!(report.state(), HealthState::Unavailable);
assert_eq!(report.checks().len(), 2);
assert!(HealthCheck::serving(" ").is_err());
assert!(HealthReport::serving("bad service").is_err());
assert!(!format!("{report:?}").contains("smtp unavailable"));
}
#[test]
fn health_deserialization_uses_same_validation_and_recomputes_state() {
assert!(
serde_json::from_value::<HealthCheck>(json!({
"name": "bad service",
"state": "serving"
}))
.is_err()
);
let report: HealthReport = serde_json::from_value(json!({
"service": "example_service",
"state": "serving",
"checks": [
{ "name": "database", "state": "unavailable", "message": "down" }
]
}))
.expect("valid health report should deserialize");
assert_eq!(report.state(), HealthState::Unavailable);
}
#[test]
fn trace_fields_keep_standard_names_and_drop_empty_values() {
let fields = TraceFields::default()
.request_id("req_01")
.request_id("req_02")
.actor_id("usr_01")
.route("/api/users")
.latency_ms("12")
.try_with("empty", " ")
.expect("trace field should be valid");
assert_eq!(fields.get(trace_fields::REQUEST_ID), Some("req_02"));
assert_eq!(fields.get(trace_fields::ACTOR_ID), Some("usr_01"));
assert_eq!(fields.get(trace_fields::ROUTE), Some("/api/users"));
assert_eq!(fields.get(trace_fields::LATENCY_MS), Some("12"));
assert_eq!(fields.get("empty"), None);
assert!(fields.clone().try_with("RequestId", "bad").is_err());
assert!(TraceFieldName::try_new("RequestId").is_err());
assert!(TraceFields::new([("RequestId", "bad")]).is_err());
assert_eq!(
TraceFields::from_lossy([("RequestId", "bad"), ("request_id", "req_01")])
.get(trace_fields::REQUEST_ID),
Some("req_01")
);
assert!(!format!("{fields:?}").contains("usr_01"));
assert!(!format!("{fields:?}").contains("/api/users"));
}
#[test]
fn trace_deserialization_uses_same_validation() {
assert!(serde_json::from_value::<TraceFieldName>(json!("RequestId")).is_err());
assert!(serde_json::from_value::<TraceFields>(json!([["RequestId", "bad"]])).is_err());
assert!(
serde_json::from_value::<StructuredEvent>(json!({
"name": "Bad Event",
"kind": "domain",
"fields": []
}))
.is_err()
);
let event: StructuredEvent = serde_json::from_value(json!({
"name": "user.created",
"kind": "domain",
"fields": [["request_id", "req_01"], ["request_id", "req_02"], ["trace_id", ""]]
}))
.expect("valid structured event should deserialize");
assert_eq!(event.name(), "user.created");
assert_eq!(event.fields().get(trace_fields::REQUEST_ID), Some("req_02"));
assert_eq!(event.fields().get(trace_fields::TRACE_ID), None);
}
#[test]
fn trace_context_normalizes_optional_ids() {
let context = TraceContext::new(
Some(" trace_01 ".to_owned()),
Some("bad/span".to_owned()),
Some("req_01".to_owned()),
);
assert_eq!(context.trace_id(), Some("trace_01"));
assert_eq!(context.span_id(), None);
assert_eq!(context.request_id(), Some("req_01"));
assert!(!context.is_empty());
let context: TraceContext = serde_json::from_value(json!({
"trace_id": "trace.01",
"span_id": "span 01",
"request_id": "req:01"
}))
.expect("trace context should deserialize");
assert_eq!(context.trace_id(), Some("trace.01"));
assert_eq!(context.span_id(), None);
assert_eq!(context.request_id(), Some("req:01"));
}
#[test]
fn structured_events_use_stable_names_and_fields() {
let event = StructuredEvent::http_request()
.request_id("req_01")
.method("GET")
.route("/health")
.outcome(EventOutcome::Success)
.build();
assert_eq!(event.name(), event_names::HTTP_REQUEST);
assert_eq!(event.kind(), EventKind::Http);
assert_eq!(event.fields().get(trace_fields::REQUEST_ID), Some("req_01"));
assert_eq!(
event.trace_fields().get(trace_fields::EVENT_NAME),
Some(event_names::HTTP_REQUEST)
);
assert_eq!(
event.fields().get(trace_fields::OUTCOME),
Some(metric_outcomes::SUCCESS)
);
assert_eq!(
event.to_btree_map().get(trace_fields::EVENT_KIND),
Some(&"http".to_owned())
);
assert!(StructuredEvent::try_new("Bad Event", EventKind::Domain).is_err());
assert!(StructuredEvent::builder("Bad Event", EventKind::Domain).is_err());
}
#[test]
fn metrics_snapshot_keeps_labels() {
let snapshot = MetricsSnapshot::new(vec![
MetricSample::counter("worker.ticks.total", 3)
.expect("metric sample should build")
.with_label("worker-name", "old")
.with_label("worker_name", "mail"),
]);
assert_eq!(snapshot.samples()[0].name(), "worker_ticks_total");
assert_eq!(snapshot.samples()[0].kind(), MetricKind::Counter);
assert_eq!(
snapshot.samples()[0].labels()[0],
("worker_name".into(), "mail".into())
);
assert_eq!(
MetricLabels::new([("worker-name", "old"), ("worker_name", "mail")])
.expect("metric labels should build")
.get("worker-name"),
Some("mail")
);
assert_eq!(
MetricLabels::new([("z", "1"), ("a", "2")])
.expect("metric labels should build")
.to_btree_map()
.keys()
.cloned()
.collect::<Vec<_>>(),
vec!["a".to_owned(), "z".to_owned()]
);
assert!(MetricLabels::new([(" ", "bad")]).is_err());
assert!(MetricLabels::from_lossy([(" ", "bad")]).is_empty());
let labels = MetricLabels::single("account", "private-account-id")
.expect("metric labels should build");
assert!(!format!("{labels:?}").contains("private-account-id"));
let private_label = "private-snapshot-label";
let snapshot = MetricsSnapshot::new(vec![
MetricSample::counter("private_total", 1)
.expect("metric sample should build")
.with_label("account", private_label),
]);
assert!(!format!("{snapshot:?}").contains(private_label));
}
#[test]
fn metrics_deserialization_uses_same_validation() {
assert!(serde_json::from_value::<MetricLabels>(json!([[" ", "bad"]])).is_err());
assert!(
serde_json::from_value::<MetricSample>(json!({
"name": " ",
"kind": "counter",
"value": 1.0,
"labels": []
}))
.is_err()
);
let sample: MetricSample = serde_json::from_value(json!({
"name": "worker.ticks.total",
"kind": "counter",
"value": 1.0,
"labels": [["worker-name", "old"], ["worker_name", "mail"]]
}))
.expect("valid metric sample should deserialize");
assert_eq!(sample.name(), "worker_ticks_total");
assert_eq!(
sample.labels(),
[("worker_name".to_owned(), "mail".to_owned())]
);
let snapshot: MetricsSnapshot = serde_json::from_value(json!([
{
"name": "http.requests.total",
"kind": "counter",
"value": 2.0,
"labels": [["method", "GET"]]
}
]))
.expect("valid metrics snapshot should deserialize");
assert_eq!(snapshot.samples().len(), 1);
}
#[test]
fn metrics_registry_rejects_non_finite_values() {
let registry = MetricRegistry::new();
assert!(matches!(
registry.set_gauge("memory", f64::NAN, MetricLabels::default()),
Err(MetricsError::InvalidValue)
));
assert!(matches!(
registry.observe_histogram("latency", f64::INFINITY, MetricLabels::default()),
Err(MetricsError::InvalidValue)
));
assert!(matches!(
MetricSample::gauge("temperature", f64::NAN),
Err(MetricsError::InvalidValue)
));
assert!(matches!(
registry.increment_counter(" ", 1, MetricLabels::default()),
Err(MetricsError::InvalidName)
));
}
#[test]
fn metrics_registry_rejects_aggregate_overflow_without_poisoning_snapshot() {
let registry = MetricRegistry::new();
registry
.observe_histogram("latency", f64::MAX, MetricLabels::default())
.expect("first finite observation should be accepted");
assert!(matches!(
registry.observe_histogram("latency", f64::MAX, MetricLabels::default()),
Err(MetricsError::InvalidValue)
));
let snapshot = registry
.snapshot()
.expect("rejected overflow must not poison the registry");
assert_eq!(snapshot.samples().len(), 1);
assert_eq!(snapshot.samples()[0].value(), f64::MAX);
assert_eq!(snapshot.samples()[0].count(), Some(1));
}
#[test]
fn metrics_errors_have_stable_classification() {
let descriptor = MetricsError::InvalidValue.error_descriptor();
assert_eq!(descriptor.kind(), ErrorKind::Validation);
assert_eq!(descriptor.code().as_str(), "metric_value_invalid");
let descriptor = MetricsError::InvalidName.error_descriptor();
assert_eq!(descriptor.kind(), ErrorKind::Validation);
assert_eq!(descriptor.code().as_str(), "metric_name_invalid");
}
#[test]
fn metrics_registry_accumulates_and_encodes_openmetrics() {
let registry = MetricRegistry::new();
registry
.increment_counter(
"http.requests.total",
2,
MetricLabels::new([("method", "GET"), ("status", "200")])
.expect("metric labels should build"),
)
.expect("counter should update");
registry
.observe_histogram(
"http.request.duration.seconds",
0.25,
MetricLabels::single("route", "/health").expect("metric label should build"),
)
.expect("histogram should update");
let encoded = encode_openmetrics(®istry.snapshot().expect("snapshot should build"));
assert!(encoded.contains("# TYPE http_requests_total counter"));
assert_eq!(
encoded
.matches("# TYPE http_requests_total counter")
.count(),
1
);
assert!(encoded.contains("method=\"GET\""));
assert!(encoded.contains("http_request_duration_seconds_sum"));
assert!(encoded.contains("http_request_duration_seconds_count"));
}
#[test]
fn openmetrics_exporter_returns_content_type_and_body() {
let snapshot = MetricsSnapshot::new(vec![
MetricSample::counter("jobs_total", 2).expect("metric sample should build"),
]);
let export = OpenMetricsExporter
.export(&snapshot)
.expect("OpenMetrics export cannot fail");
assert_eq!(export.content_type(), OpenMetricsExporter::CONTENT_TYPE);
assert!(export.body().contains("jobs_total 2"));
assert!(!format!("{export:?}").contains("jobs_total 2"));
}
}