fastrace 0.7.17

A high-performance timeline tracing library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

// Copyright 2020 TiKV Project Authors. Licensed under Apache-2.0.

use std::borrow::Cow;

use crate::Span;
use crate::local::LocalSpan;
use crate::util::Properties;

/// An event that represents a single point in time during the execution of a span.
pub struct Event {
    pub(crate) name: Cow<'static, str>,
    pub(crate) properties: Properties,
}

impl Event {
    /// Create a new event with the given name.
    ///
    /// # Examples
    ///
    /// ```
    /// use fastrace::prelude::*;
    ///
    /// LocalSpan::add_event(Event::new("event"));
    /// ```
    #[inline]
    pub fn new(name: impl Into<Cow<'static, str>>) -> Self {
        Event {
            name: name.into(),
            properties: Properties::default(),
        }
    }

    /// Add a single property to the `Event` and return the modified `Event`.
    ///
    /// A property is an arbitrary key-value pair associated with an event.
    ///
    /// # Examples
    ///
    /// ```
    /// use fastrace::prelude::*;
    ///
    /// LocalSpan::add_event(Event::new("event").with_property(|| ("key", "value")));
    /// ```
    #[inline]
    pub fn with_property<K, V, F>(self, property: F) -> Self
    where
        K: Into<Cow<'static, str>>,
        V: Into<Cow<'static, str>>,
        F: FnOnce() -> (K, V),
    {
        self.with_properties(|| [property()])
    }

    /// Add multiple properties to the `Event` and return the modified `Event`.
    ///
    /// # Examples
    ///
    /// ```
    /// use fastrace::prelude::*;
    ///
    /// LocalSpan::add_event(Event::new("event").with_properties(|| [("key1", "value")]));
    /// ```
    #[inline]
    pub fn with_properties<K, V, I, F>(mut self, properties: F) -> Self
    where
        K: Into<Cow<'static, str>>,
        V: Into<Cow<'static, str>>,
        I: IntoIterator<Item = (K, V)>,
        F: FnOnce() -> I,
    {
        #[cfg(feature = "enable")]
        {
            self.properties
                .extend(properties().into_iter().map(|(k, v)| (k.into(), v.into())))
        }
        self
    }

    /// Adds an event to the parent span with the given name and properties.
    ///
    /// # Examples
    ///
    /// ```
    /// use fastrace::prelude::*;
    ///
    /// let root = Span::root("root", SpanContext::random());
    ///
    /// Event::add_to_parent("event in root", &root, || [("key".into(), "value".into())]);
    /// ```
    #[deprecated(since = "0.7.8", note = "use `Span::add_event` instead")]
    pub fn add_to_parent<I, F>(name: impl Into<Cow<'static, str>>, parent: &Span, properties: F)
    where
        I: IntoIterator<Item = (Cow<'static, str>, Cow<'static, str>)>,
        F: FnOnce() -> I,
    {
        let event = Event::new(name).with_properties(properties);
        parent.add_event(event);
    }

    /// Adds an event to the current local parent span with the given name and properties.
    ///
    /// # Examples
    ///
    /// ```
    /// use fastrace::prelude::*;
    ///
    /// let root = Span::root("root", SpanContext::random());
    /// let _guard = root.set_local_parent();
    ///
    /// Event::add_to_local_parent("event in root", || [("key".into(), "value".into())]);
    /// ```
    #[deprecated(since = "0.7.8", note = "use `LocalSpan::add_event` instead")]
    pub fn add_to_local_parent<I, F>(name: impl Into<Cow<'static, str>>, properties: F)
    where
        I: IntoIterator<Item = (Cow<'static, str>, Cow<'static, str>)>,
        F: FnOnce() -> I,
    {
        let event = Event::new(name).with_properties(properties);
        LocalSpan::add_event(event);
    }
}