use super::TracingLevel;
#[test]
fn the_level_vocabulary_round_trips() {
for level in TracingLevel::ALL {
assert_eq!(
TracingLevel::named(level.as_str()),
Some(level),
"{level} did not survive its own word"
);
}
}
#[test]
fn a_word_the_framework_does_not_ship_names_no_level() {
assert_eq!(TracingLevel::named("verbose"), None);
assert_eq!(
TracingLevel::named("Debug"),
None,
"the words are lowercase"
);
assert_eq!(TracingLevel::named(""), None);
}
#[test]
fn the_default_level_is_info() {
assert_eq!(TracingLevel::default(), TracingLevel::Info);
assert_eq!(
<Silent as crate::Declared>::TRACING,
TracingLevel::Info,
"the trait's default and the vocabulary's default are one fact"
);
}
struct Silent;
impl crate::Declared for Silent {
type Channels = crate::Unchanneled;
type Options = ();
type Mode = crate::Block;
type Pair = crate::Buffered;
type Wires<O> = crate::Downstream<O>;
type Attribution<O> = ();
const EFFECT: crate::Effect = crate::Effect::Pure;
}
#[cfg(feature = "tracing")]
mod saying {
use core::{
fmt,
sync::atomic::{AtomicU64, Ordering},
};
use std::sync::{Arc, Mutex};
use tracing::{
Event, Level, Metadata, Subscriber,
field::{Field, Visit},
span,
};
#[derive(Debug, Clone)]
pub(super) struct Said {
pub(super) name: String,
pub(super) level: Level,
declared: Vec<String>,
fields: Vec<(String, String)>,
}
impl Said {
pub(super) fn field(&self, field: &str) -> Option<&str> {
self
.fields
.iter()
.find(|(name, _)| name == field)
.map(|(_, value)| value.as_str())
}
pub(super) fn declares(&self, field: &str) -> bool {
self.declared.iter().any(|name| name == field)
}
}
#[derive(Debug, Default)]
pub(super) struct Heard {
spans: Vec<Said>,
events: Vec<Said>,
}
impl Heard {
pub(super) fn spans(&self, name: &str) -> Vec<Said> {
self
.spans
.iter()
.filter(|said| said.name == name)
.cloned()
.collect()
}
pub(super) fn span_names(&self) -> Vec<String> {
self.spans.iter().map(|said| said.name.clone()).collect()
}
pub(super) fn events_with(&self, field: &str) -> Vec<Said> {
self
.events
.iter()
.filter(|said| said.declares(field))
.cloned()
.collect()
}
pub(super) fn events(&self) -> usize {
self.events.len()
}
}
#[derive(Debug)]
pub(super) struct Capturing {
heard: Arc<Mutex<Heard>>,
next: AtomicU64,
}
impl Capturing {
pub(super) fn new() -> (Self, Arc<Mutex<Heard>>) {
let heard = Arc::new(Mutex::new(Heard::default()));
(
Self {
heard: Arc::clone(&heard),
next: AtomicU64::new(1),
},
heard,
)
}
}
impl Subscriber for Capturing {
fn enabled(&self, _metadata: &Metadata<'_>) -> bool {
true
}
fn new_span(&self, attrs: &span::Attributes<'_>) -> span::Id {
let mut fields = Fields::default();
attrs.record(&mut fields);
self
.heard
.lock()
.expect("the capture lock")
.spans
.push(said(attrs.metadata(), fields.0));
span::Id::from_u64(self.next.fetch_add(1, Ordering::Relaxed))
}
fn record(&self, _span: &span::Id, _values: &span::Record<'_>) {}
fn record_follows_from(&self, _span: &span::Id, _follows: &span::Id) {}
fn event(&self, event: &Event<'_>) {
let mut fields = Fields::default();
event.record(&mut fields);
self
.heard
.lock()
.expect("the capture lock")
.events
.push(said(event.metadata(), fields.0));
}
fn enter(&self, _span: &span::Id) {}
fn exit(&self, _span: &span::Id) {}
}
fn said(metadata: &Metadata<'_>, fields: Vec<(String, String)>) -> Said {
Said {
name: metadata.name().to_owned(),
level: *metadata.level(),
declared: metadata
.fields()
.iter()
.map(|field| field.name().to_owned())
.collect(),
fields,
}
}
#[derive(Debug, Default)]
struct Fields(Vec<(String, String)>);
impl Visit for Fields {
fn record_str(&mut self, field: &Field, value: &str) {
self.0.push((field.name().to_owned(), value.to_owned()));
}
fn record_u64(&mut self, field: &Field, value: u64) {
self.0.push((field.name().to_owned(), value.to_string()));
}
fn record_i64(&mut self, field: &Field, value: i64) {
self.0.push((field.name().to_owned(), value.to_string()));
}
fn record_bool(&mut self, field: &Field, value: bool) {
self.0.push((field.name().to_owned(), value.to_string()));
}
fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {
self.0.push((field.name().to_owned(), format!("{value:?}")));
}
}
}
#[cfg(feature = "tracing")]
mod live {
use crate::Context;
use core::time::Duration;
use crate::drive::Drives;
use std::{
io,
sync::{Arc, Mutex},
thread,
};
use jiff::SignedDuration;
use tracing::Level;
use super::{
TracingLevel,
saying::{Capturing, Heard},
};
use crate::{
Ack, AckMode, AckReceiver, Answers, Concern, Delivery, Effect, Emitter, Failure, Inbox, Item,
ItemId, Lifecycle, LifecycleTap, NodeName, Observation, Occupancy, Outbox, OverflowDecision,
Payload, PollUpstream, QueryArm, Resident, Schedule, Seats, ShedKey, Skip, SkipReason, Swept,
Taps, TracingTap, Wake, channel, door,
};
fn heard(body: impl FnOnce()) -> Arc<Mutex<Heard>> {
let (subscriber, heard) = Capturing::new();
tracing::subscriber::with_default(subscriber, body);
heard
}
struct Doubling;
impl crate::Operator for Doubling {
type Error = core::convert::Infallible;
type In = u64;
type Out = u64;
fn accept(
&mut self,
_ctx: &Context,
delivery: Delivery<Self::In>,
emitter: &mut Emitter<u64>,
) -> Result<(), Self::Error> {
for item in delivery.into_items() {
emitter.emit(item.into_value() * 2);
}
Ok(())
}
}
impl Seats<Doubling> for () {
type Error = core::convert::Infallible;
type Info = ();
async fn seat(
&mut self,
_operator: &mut Doubling,
_source: PollUpstream,
) -> Result<Swept<Self::Info>, Self::Error> {
Ok(Swept::Ran(()))
}
}
fn send(out: &Outbox<ItemId, u64>, keys: &[u64]) -> AckReceiver<ItemId> {
let (ack, answers) = crate::ack_channel();
let items = keys
.iter()
.map(|&key| Item::new(ItemId::new(key), key))
.collect();
out
.deliver(Delivery::new(Payload::Batch(items), ack))
.expect("the resident is listening");
answers
}
fn drain(inbox: &Inbox<ItemId, u64>) {
while let Some(wake) = inbox.park(Duration::from_millis(5)) {
let Wake::Delivered(delivery) = wake else {
continue;
};
let (payload, ack) = delivery.into_parts();
let released = payload.keys().copied().collect();
if let Some(ack) = ack {
ack.send(Ack::new(released, "consumer", Lifecycle::Persisted(())));
}
}
}
fn holding(feed: Outbox<ItemId, u64>) -> thread::JoinHandle<()> {
thread::spawn(move || {
thread::sleep(Duration::from_millis(60));
drop(feed);
})
}
#[test]
fn the_tap_says_every_arm_of_the_vocabulary() {
let tap = TracingTap::new();
let node = NodeName::new("clip");
let heard = heard(|| {
tap.observe(node, &Lifecycle::<u64>::Persisted(1).erase());
tap.observe(
node,
&Lifecycle::<u64>::Skipped(Skip::new(SkipReason::Filtered).about("clip-7")).erase(),
);
tap.observe(
node,
&Lifecycle::<u64>::Failed(Failure::new(io::Error::other("the store said no"))).erase(),
);
tap.observe(
node,
&Observation::Retrying {
attempt: 2,
after: Some(SignedDuration::from_secs(3)),
},
);
tap.observe(
node,
&Observation::Shed {
key: ShedKey::new("segment(clip-7, 2)"),
decision: OverflowDecision::DropOldest,
occupancy: Occupancy::bounded(8, 8),
},
);
tap.observe(
node,
&Observation::PolicyFailed {
concern: Concern::Overflow,
error: Box::new(io::Error::other("the advisor panicked")),
},
);
});
let heard = heard.lock().expect("the capture lock");
assert_eq!(heard.events(), 6, "one event per observation, and no more");
let stations = heard.events_with("station");
assert_eq!(stations.len(), 3, "the three shapes an arrival takes");
let persisted = &stations[0];
assert_eq!(persisted.level, Level::DEBUG);
assert_eq!(persisted.field("node"), Some("clip"));
assert_eq!(persisted.field("station"), Some("persisted"));
let skipped = &stations[1];
assert_eq!(skipped.level, Level::DEBUG);
assert_eq!(skipped.field("station"), Some("skipped"));
assert_eq!(skipped.field("reason"), Some("filtered"));
assert_eq!(skipped.field("content"), Some("clip-7"));
let failed = &stations[2];
assert_eq!(
failed.level,
Level::ERROR,
"a failure is an error and never a debug line"
);
assert_eq!(failed.field("station"), Some("failed"));
assert_eq!(failed.field("error"), Some("the store said no"));
let retrying = heard.events_with("attempt");
assert_eq!(retrying.len(), 1);
assert_eq!(retrying[0].level, Level::WARN);
assert_eq!(retrying[0].field("attempt"), Some("2"));
assert_eq!(retrying[0].field("after"), Some("PT3S"));
let shed = heard.events_with("decision");
assert_eq!(shed.len(), 1);
assert_eq!(shed[0].level, Level::WARN);
assert_eq!(
shed[0].field("key"),
Some("segment(clip-7, 2)"),
"the obituary carries the node's COMPLETE item key"
);
assert_eq!(shed[0].field("decision"), Some("drop_oldest"));
assert_eq!(shed[0].field("queued"), Some("8"));
assert_eq!(shed[0].field("capacity"), Some("8"));
let sick = heard.events_with("concern");
assert_eq!(sick.len(), 1);
assert_eq!(sick[0].level, Level::ERROR);
assert_eq!(sick[0].field("concern"), Some("overflow"));
assert_eq!(sick[0].field("error"), Some("the advisor panicked"));
}
#[test]
fn an_unstated_optional_field_is_declared_and_not_recorded() {
let tap = TracingTap::new();
let node = NodeName::new("clip");
let heard = heard(|| {
tap.observe(
node,
&Lifecycle::<u64>::Skipped(Skip::new(SkipReason::NoConsumers)).erase(),
);
tap.observe(
node,
&Observation::Retrying {
attempt: 1,
after: None,
},
);
});
let heard = heard.lock().expect("the capture lock");
let skipped = heard.events_with("station");
assert_eq!(skipped.len(), 1);
assert!(
skipped[0].declares("content"),
"the callsite names the field in every build"
);
assert_eq!(
skipped[0].field("content"),
None,
"and records it only where the operator stated one"
);
let retrying = heard.events_with("attempt");
assert!(retrying[0].declares("after"));
assert_eq!(retrying[0].field("after"), None);
}
#[test]
fn a_pure_units_batch_and_tick_are_spanned_and_its_commit_is_not() {
let (feed, inbox) = channel::<ItemId, u64>(8);
let (out, downstream) = channel::<ItemId, u64>(8);
let mut resident = Resident::new("double", Doubling, inbox)
.publish(out)
.polling(Schedule::new().every(Duration::from_millis(5)), ())
.with_sweep(Duration::from_millis(5))
.with_tracing_level(TracingLevel::Debug);
let answers = send(&feed, &[1, 2, 3]);
let holder = holding(feed);
let consumer = thread::spawn(move || drain(&downstream));
let heard = heard(move || {
resident.run();
});
holder.join().expect("the feed holder");
consumer.join().expect("the consumer thread");
drop(answers);
let heard = heard.lock().expect("the capture lock");
let batches = heard.spans("ingraph.batch");
assert_eq!(batches.len(), 1, "one delivery, one batch span");
assert_eq!(batches[0].level, Level::DEBUG, "the DECLARED level");
assert_eq!(batches[0].field("node"), Some("double"));
assert_eq!(batches[0].field("items"), Some("3"));
assert!(
heard.spans("ingraph.commit").is_empty(),
"a node that lands nothing has no commit to time: {:?}",
heard.span_names()
);
let ticks = heard.spans("ingraph.tick");
assert!(!ticks.is_empty(), "the clock ran: {:?}", heard.span_names());
assert_eq!(ticks[0].level, Level::DEBUG);
assert_eq!(ticks[0].field("node"), Some("double"));
assert_eq!(ticks[0].field("source"), Some("0"));
}
#[test]
fn a_landing_units_commit_is_spanned_and_carries_its_rows() {
let (feed, inbox) = channel::<ItemId, u64>(8);
let mut resident = Resident::new("store", Doubling, inbox)
.with_effect(Effect::Lands)
.with_ack(AckMode::Local)
.with_tracing_level(TracingLevel::Warn);
let answers = send(&feed, &[1, 2]);
drop(feed);
let heard = heard(move || {
resident.run();
});
drop(answers);
let heard = heard.lock().expect("the capture lock");
let commits = heard.spans("ingraph.commit");
assert_eq!(commits.len(), 1, "one batch, one commit span");
assert_eq!(
commits[0].level,
Level::WARN,
"the declared level governs every one of the four"
);
assert_eq!(commits[0].field("node"), Some("store"));
assert_eq!(commits[0].field("rows"), Some("2"));
}
struct Counting;
impl Answers<String> for Counting {
type Error = core::convert::Infallible;
type Output = usize;
fn on_invoke(&mut self, input: String) -> Result<usize, Self::Error> {
Ok(input.len())
}
}
#[test]
fn a_query_doors_round_trip_is_spanned_once_per_invoke() {
let (front, invokes) = door::<String, usize>(4);
let mut arm = QueryArm::new("tower", Counting, invokes).with_tracing_level(TracingLevel::Trace);
let first = front.invoke("red".to_owned()).expect("listening");
let second = front.invoke("blue car".to_owned()).expect("listening");
drop(front);
let heard = heard(move || {
arm.run();
});
assert_eq!(first.take().expect("answered"), 3);
assert_eq!(second.take().expect("answered"), 8);
let heard = heard.lock().expect("the capture lock");
let doors = heard.spans("ingraph.door");
assert_eq!(doors.len(), 2, "one span per invoke, not per arm");
assert_eq!(doors[0].level, Level::TRACE, "the DECLARED level");
assert_eq!(doors[0].field("node"), Some("tower"));
assert_eq!(doors[0].field("query"), Some("1"), "the arm's own count");
assert_eq!(doors[1].field("query"), Some("2"));
}
#[test]
fn the_span_list_is_the_four_and_nothing_else() {
let (feed, inbox) = channel::<ItemId, u64>(8);
let mut resident = Resident::new("store", Doubling, inbox)
.with_effect(Effect::Lands)
.polling(Schedule::new().every(Duration::from_millis(5)), ())
.with_sweep(Duration::from_millis(5))
.with_taps(Taps::new().with(Arc::new(TracingTap::new())));
let answers = send(&feed, &[1]);
let holder = holding(feed);
let heard = heard(move || {
resident.run();
});
holder.join().expect("the feed holder");
drop(answers);
let heard = heard.lock().expect("the capture lock");
let names = heard.span_names();
for name in &names {
assert!(
matches!(
name.as_str(),
"ingraph.batch" | "ingraph.door" | "ingraph.commit" | "ingraph.tick"
),
"{name} is a fifth span: {names:?}"
);
}
assert!(
!names.is_empty(),
"the walk opened no span at all, so it proves nothing"
);
assert!(
heard.events() > 0,
"the tap rode along and said something about the same run"
);
}
}