use std::collections::BTreeMap;
use serde::Serialize;
use thiserror::Error;
use crate::{DataError, ErrorEnvelope, redaction::redact_urls_in_text};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Default)]
pub struct OperationContext {
#[serde(skip_serializing_if = "Option::is_none")]
system: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
component: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
operation: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
request_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
job_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
correlation_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
trace_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
span_id: Option<String>,
}
impl OperationContext {
#[must_use]
pub fn builder() -> OperationContextBuilder {
OperationContextBuilder::default()
}
#[must_use]
pub fn system(&self) -> Option<&str> {
self.system.as_deref()
}
#[must_use]
pub fn component(&self) -> Option<&str> {
self.component.as_deref()
}
#[must_use]
pub fn operation(&self) -> Option<&str> {
self.operation.as_deref()
}
#[must_use]
pub fn request_id(&self) -> Option<&str> {
self.request_id.as_deref()
}
#[must_use]
pub fn job_id(&self) -> Option<&str> {
self.job_id.as_deref()
}
#[must_use]
pub fn correlation_id(&self) -> Option<&str> {
self.correlation_id.as_deref()
}
#[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 to_map(&self) -> BTreeMap<&'static str, &str> {
let mut fields = BTreeMap::new();
Self::insert_present(&mut fields, "system", self.system());
Self::insert_present(&mut fields, "component", self.component());
Self::insert_present(&mut fields, "operation", self.operation());
Self::insert_present(&mut fields, "request_id", self.request_id());
Self::insert_present(&mut fields, "job_id", self.job_id());
Self::insert_present(&mut fields, "correlation_id", self.correlation_id());
Self::insert_present(&mut fields, "trace_id", self.trace_id());
Self::insert_present(&mut fields, "span_id", self.span_id());
fields
}
#[must_use]
pub fn index_fields(&self) -> BTreeMap<&'static str, &str> {
let mut fields = BTreeMap::new();
Self::insert_present(&mut fields, "system", self.system());
Self::insert_present(&mut fields, "component", self.component());
Self::insert_present(&mut fields, "operation", self.operation());
fields
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.to_map().is_empty()
}
pub(crate) fn with_trace_id_from_carrier(mut self, trace_id: String) -> Self {
self.trace_id = Some(trace_id);
self
}
fn insert_present<'a>(
fields: &mut BTreeMap<&'static str, &'a str>,
name: &'static str,
value: Option<&'a str>,
) {
if let Some(value) = value {
fields.insert(name, value);
}
}
}
#[derive(Debug, Clone, Default)]
pub struct OperationContextBuilder {
system: Option<String>,
component: Option<String>,
operation: Option<String>,
request_id: Option<String>,
job_id: Option<String>,
correlation_id: Option<String>,
trace_id: Option<String>,
span_id: Option<String>,
}
impl OperationContextBuilder {
#[must_use]
pub fn system(mut self, value: impl Into<String>) -> Self {
self.system = Some(value.into());
self
}
#[must_use]
pub fn component(mut self, value: impl Into<String>) -> Self {
self.component = Some(value.into());
self
}
#[must_use]
pub fn operation(mut self, value: impl Into<String>) -> Self {
self.operation = Some(value.into());
self
}
#[must_use]
pub fn request_id(mut self, value: impl Into<String>) -> Self {
self.request_id = Some(value.into());
self
}
#[must_use]
pub fn job_id(mut self, value: impl Into<String>) -> Self {
self.job_id = Some(value.into());
self
}
#[must_use]
pub fn correlation_id(mut self, value: impl Into<String>) -> Self {
self.correlation_id = Some(value.into());
self
}
#[must_use]
pub fn trace_id(mut self, value: impl Into<String>) -> Self {
self.trace_id = Some(value.into());
self
}
#[must_use]
pub fn span_id(mut self, value: impl Into<String>) -> Self {
self.span_id = Some(value.into());
self
}
pub fn build(self) -> Result<OperationContext, InvalidOperationContext> {
Ok(OperationContext {
system: sanitize("system", self.system)?,
component: sanitize("component", self.component)?,
operation: sanitize("operation", self.operation)?,
request_id: sanitize("request_id", self.request_id)?,
job_id: sanitize("job_id", self.job_id)?,
correlation_id: sanitize("correlation_id", self.correlation_id)?,
trace_id: sanitize("trace_id", self.trace_id)?,
span_id: sanitize("span_id", self.span_id)?,
})
}
}
fn sanitize(
field: &'static str,
value: Option<String>,
) -> Result<Option<String>, InvalidOperationContext> {
value
.map(|value| {
if value.trim().is_empty() {
return Err(InvalidOperationContext::EmptyField(field));
}
Ok(redact_urls_in_text(&value, false))
})
.transpose()
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum InvalidOperationContext {
#[error("{0} must not be empty")]
EmptyField(&'static str),
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct ObservabilityEvent {
event: &'static str,
exception: ErrorEnvelope,
#[serde(skip_serializing_if = "Option::is_none")]
operation: Option<OperationContext>,
}
impl ObservabilityEvent {
#[must_use]
pub fn new(exception: ErrorEnvelope, operation: Option<OperationContext>) -> Self {
let operation = operation.filter(|context| !context.is_empty());
Self {
event: "exception",
exception,
operation,
}
}
#[must_use]
pub fn from_data_error(error: &DataError, operation: Option<OperationContext>) -> Self {
Self::new(error.to_envelope(), operation)
}
#[must_use]
pub const fn event(&self) -> &'static str {
self.event
}
#[must_use]
pub const fn exception(&self) -> &ErrorEnvelope {
&self.exception
}
#[must_use]
pub const fn operation(&self) -> Option<&OperationContext> {
self.operation.as_ref()
}
pub fn to_json(&self) -> Result<String, serde_json::Error> {
serde_json::to_string(self)
}
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::{InvalidOperationContext, ObservabilityEvent, OperationContext};
use crate::DataError;
#[test]
fn context_serializes_only_present_fields() {
let context = OperationContext::builder()
.system("payments")
.component("worker")
.operation("settle_invoice")
.request_id("req-42")
.build()
.expect("context should be valid");
assert_eq!(context.to_map().len(), 4);
assert_eq!(context.system(), Some("payments"));
assert_eq!(context.request_id(), Some("req-42"));
assert_eq!(context.trace_id(), None);
}
#[test]
fn index_fields_exclude_high_cardinality_identifiers() {
let context = OperationContext::builder()
.system("payments")
.component("worker")
.operation("settle_invoice")
.request_id("req-42")
.correlation_id("corr-99")
.build()
.expect("context should be valid");
let indexed = context.index_fields();
assert_eq!(indexed.len(), 3);
assert_eq!(indexed["system"], "payments");
assert!(!indexed.contains_key("request_id"));
assert!(!indexed.contains_key("correlation_id"));
}
#[test]
fn empty_identifiers_are_rejected() {
let result = OperationContext::builder().job_id(" ").build();
assert_eq!(result, Err(InvalidOperationContext::EmptyField("job_id")));
}
#[test]
fn url_shaped_identifiers_are_redacted() {
let context = OperationContext::builder()
.request_id("https://user:secret@example.com/request/123?token=SECRETVALUE")
.build()
.expect("context should be valid");
assert_eq!(
context.request_id(),
Some("https://***:***@example.com/***?token=***")
);
}
#[test]
fn event_keeps_operation_separate_from_exception() {
let error = DataError::new("validation_failed", "age must be positive")
.with_attribute("field", json!("age"));
let context = OperationContext::builder()
.system("feature-service")
.request_id("req-123")
.build()
.expect("context should be valid");
let event = ObservabilityEvent::from_data_error(&error, Some(context));
let value = serde_json::to_value(event).expect("event should serialize");
assert_eq!(value["event"], "exception");
assert_eq!(value["exception"]["type"], "validation_failed");
assert_eq!(value["operation"]["system"], "feature-service");
assert_eq!(value["operation"]["request_id"], "req-123");
assert!(value["exception"].get("operation").is_none());
}
#[test]
fn empty_context_is_omitted_from_event() {
let error = DataError::new("example", "failed");
let context = OperationContext::builder()
.build()
.expect("empty context is valid");
let event = ObservabilityEvent::from_data_error(&error, Some(context));
let value = serde_json::to_value(event).expect("event should serialize");
assert!(value.get("operation").is_none());
}
}