Trait Visit

Source

pub trait Visit {
    // Required method
    fn record_debug(&mut self, field: &Field, value: &dyn Debug);

    // Provided methods
    fn record_i64(&mut self, field: &Field, value: i64) { ... }
    fn record_u64(&mut self, field: &Field, value: u64) { ... }
    fn record_bool(&mut self, field: &Field, value: bool) { ... }
    fn record_str(&mut self, field: &Field, value: &str) { ... }
}

Expand description

Visits typed values.

An instance of Visit (“a visitor”) represents the logic necessary to record field values of various types. When an implementor of Value is recorded, it calls the appropriate method on the provided visitor to indicate the type that value should be recorded as.

When a Subscriber implementation records an Event or a set of Values added to a Span, it can pass an &mut Visit to the record method on the provided ValueSet or Event. This visitor will then be used to record all the field-value pairs present on that Event or ValueSet.

§Examples

A simple visitor that writes to a string might be implemented like so:

use std::fmt::{self, Write};
use tokio_trace::field::{Value, Visit, Field};
pub struct StringVisitor<'a> {
    string: &'a mut String,
}

impl<'a> Visit for StringVisitor<'a> {
    fn record_debug(&mut self, field: &Field, value: &fmt::Debug) {
        write!(self.string, "{} = {:?}; ", field.name(), value).unwrap();
    }
}

This visitor will format each recorded value using fmt::Debug, and append the field name and formatted value to the provided string, regardless of the type of the recorded value. When all the values have been recorded, the StringVisitor may be dropped, allowing the string to be printed or stored in some other data structure.

The Visit trait provides default implementations for record_i64, record_u64, record_bool, and record_str which simply forward the recorded value to record_debug. Thus, record_debug is the only method which a Visit implementation must implement. However, visitors may override the default implementations of these functions in order to implement type-specific behavior.

Additionally, when a visitor recieves a value of a type it does not care about, it is free to ignore those values completely. For example, a visitor which only records numeric data might look like this:

pub struct SumVisitor {
    sum: i64,
}

impl Visit for SumVisitor {
    fn record_i64(&mut self, _field: &Field, value: i64) {
       self.sum += value;
    }

    fn record_u64(&mut self, _field: &Field, value: u64) {
        self.sum += value as i64;
    }

    fn record_debug(&mut self, _field: &Field, _value: &fmt::Debug) {
        // Do nothing
    }
}

This visitor (which is probably not particularly useful) keeps a running sum of all the numeric values it records, and ignores all other values. A more practical example of recording typed values is presented in examples/counters.rs, which demonstrates a very simple metrics system implemented using tokio-trace.