Struct Tracer 

pub struct Tracer { /* private fields */ }

A traceroute implementation.

See the crate documentation for more information.

Note that this is type cheaply cloneable.

Implementations

impl Tracer

pub fn run(&self) -> Result<(), Error>

Run the Tracer.

This method will block until either the trace completes all rounds (if crate::Builder::max_rounds has been called to set to a non-zero value) or until the trace fails.

At the completion of the trace, the state of the tracer can be retrieved using the Tracer::snapshot method.

If you want to run the tracer indefinitely (by not setting crate::Builder::max_rounds), you can either clone and run the tracer on a separate thread by using the Tracer::spawn method or by use the Tracer::run_with method in the current thread to gather pee round state manually.

Example

The following will run the tracer for a fixed number (3) of rounds and then retrieve the final state snapshot:

use trippy_core::Builder;

let addr = IpAddr::from_str("1.1.1.1")?;
let tracer = Builder::new(addr).max_rounds(Some(3)).build()?;
tracer.run()?;
let _state = tracer.snapshot();

See Also

• Tracer::run_with - Run the tracer with a custom round handler.
• Tracer::spawn - Spawn the tracer on a new thread without a custom round handler.

pub fn run_with<F: Fn(&Round<'_>)>(&self, func: F) -> Result<(), Error>

Run the Tracer with a custom round handler.

This method will block until either the trace completes all rounds (if crate::Builder::max_rounds has been called to set to a non-zero value) or until the trace fails.

At the completion of the trace, the state of the tracer can be retrieved using the Tracer::snapshot method.

This method will additionally call the provided function for each round that is completed. This can be useful if you want to gather round state manually if the tracer is run indefinitely (by not setting crate::Builder::max_rounds)

Example

The following will run the tracer indefinitely and print the data from each round of tracing:

use trippy_core::Builder;

let addr = IpAddr::from_str("1.1.1.1")?;
let tracer = Builder::new(addr).build()?;
tracer.run_with(|round| println!("{:?}", round))?;

See Also

• Tracer::run - Run the tracer without a custom round handler.

pub fn spawn(self) -> Result<(Self, JoinHandle<Result<(), Error>>), Error>

Spawn the tracer on a new thread.

This method will spawn a new thread to run the tracer and immediately return the Tracer and a handle to the thread, so it may be joined with JoinHandle::join.

If you want to run the tracer indefinitely (by not setting crate::Builder::max_rounds) you can use this method to spawn the tracer on a new thread and return the Tracer such that a Tracer::snapshot of the state can be taken at any time.

Example

The following will spawn a tracer on a new thread and take a snapshot of the state every 5 seconds:

use trippy_core::Builder;

let addr = IpAddr::from_str("1.1.1.1")?;
let (tracer, _) = Builder::new(addr).build()?.spawn()?;
loop {
    thread::sleep(Duration::from_secs(5));
    // get the latest state.
    let _state = tracer.snapshot();
}

See Also

• Tracer::run - Run the tracer on the current thread.

pub fn spawn_with<F: Fn(&Round<'_>) + Send + 'static>( self, func: F, ) -> Result<(Self, JoinHandle<Result<(), Error>>), Error>

Spawn the tracer with a custom round handler on a new thread.

This method will spawn a new thread to run the tracer with a custom round handler and immediately return the Tracer and a handle to the thread, so it may be joined with JoinHandle::join.

Example

The following will spawn a tracer on a new thread with a custom round handler to print the data from each round of tracing and also take a snapshot of the state every 5 seconds until the tracer completes all rounds:

use trippy_core::Builder;

let addr = IpAddr::from_str("1.1.1.1")?;
let (tracer, handle) = Builder::new(addr)
    .max_rounds(Some(3))
    .build()?
    .spawn_with(|round| println!("{:?}", round))?;
for i in 0..3 {
    thread::sleep(Duration::from_secs(5));
    // get the latest state.
    let _state = tracer.snapshot();
}
handle.join().unwrap()?;

See Also

• Tracer::spawn - Spawn the tracer on a new thread without a custom round handler.

pub fn snapshot(&self) -> State

Take a snapshot of the tracer state.

pub fn clear(&self)

Clear the tracer state.

pub fn max_flows(&self) -> usize

The maximum number of flows to record.

pub fn max_samples(&self) -> usize

The maximum number of samples to record.

pub fn privilege_mode(&self) -> PrivilegeMode

The privilege mode of the tracer.

pub fn protocol(&self) -> Protocol

The protocol of the tracer.

pub fn interface(&self) -> Option<&str>

The interface to use for the tracer.

pub fn source_addr(&self) -> Option<IpAddr>

The source address of the tracer.

pub fn target_addr(&self) -> IpAddr

The target address of the tracer.

pub fn packet_size(&self) -> PacketSize

The packet size of the tracer.

pub fn payload_pattern(&self) -> PayloadPattern

The payload pattern of the tracer.

pub fn initial_sequence(&self) -> Sequence

The initial sequence number of the tracer.

pub fn tos(&self) -> TypeOfService

The type of service of the tracer.

pub fn icmp_extension_parse_mode(&self) -> IcmpExtensionParseMode

The ICMP extension parse mode of the tracer.

pub fn read_timeout(&self) -> Duration

The read timeout of the tracer.

pub fn tcp_connect_timeout(&self) -> Duration

The TCP connect timeout of the tracer.

pub fn trace_identifier(&self) -> TraceId

The trace identifier of the tracer.

pub fn max_rounds(&self) -> Option<MaxRounds>

The maximum number of rounds of the tracer.

pub fn first_ttl(&self) -> TimeToLive

The first time-to-live value of the tracer.

pub fn max_ttl(&self) -> TimeToLive

The maximum time-to-live value of the tracer.

pub fn grace_duration(&self) -> Duration

The grace duration of the tracer.

pub fn max_inflight(&self) -> MaxInflight

The maximum number of in-flight probes of the tracer.

pub fn multipath_strategy(&self) -> MultipathStrategy

The multipath strategy of the tracer.

pub fn port_direction(&self) -> PortDirection

The port direction of the tracer.

pub fn min_round_duration(&self) -> Duration

The minimum round duration of the tracer.

pub fn max_round_duration(&self) -> Duration

The maximum round duration of the tracer.

Trait Implementations

impl Clone for Tracer

fn clone(&self) -> Tracer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Tracer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.