tracing-prof 0.3.0

Experimental library for profiling tracing spans.
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
122

//! Reporters are used to report profiling data produced by the profile layer.

use tracing::span;
use tracing_core::callsite;

use crate::config::ProfileConfig;

#[cfg(feature = "pprof")]
pub mod pprof;

/// A trait that is used for reporting profile samples.
///
/// The reporting always happens on a dedicated thread, thus
/// all operations are allowed to block as long as required.
pub trait ProfileReporter {
    /// Called once when the reporter is created.
    fn init(&mut self, config: &ProfileConfig) {
        _ = config;
    }

    /// A span was created, the reporter should keep
    /// span metadata until the span is destroyed.
    fn span_created(&mut self, span: &span::Id, metadata: SpanMetadata) {
        _ = (span, metadata);
    }

    /// A span was destroyed, any labels and
    /// other data recorded for it can be discarded.
    fn span_destroyed(&mut self, span: &span::Id) {
        _ = span;
    }

    /// Process CPU time data for a span.
    ///
    /// The values are relative to the last call to this function (if any).
    fn span_cpu(&mut self, span: &span::Id, cpu: SpanCpuTime) {
        _ = (span, cpu);
    }

    /// Process wall time data for a span.
    ///
    /// The values are relative to the last call to this function (if any).
    fn span_wall(&mut self, span: &span::Id, wall: SpanWallTime) {
        _ = (span, wall);
    }

    /// Process allocations for a span.
    ///
    /// The values are relative to the last call to this function (if any).
    fn span_allocations(&mut self, span: &span::Id, allocs: SpanAllocations) {
        _ = (span, allocs);
    }

    /// Process heap statistics for a span.
    ///
    /// The values represent the total current heap usage at the time of the call.
    fn span_heap(&mut self, span: &span::Id, heap: SpanHeap) {
        _ = (span, heap);
    }

    /// Flush all accumulated data.
    ///
    /// This function is also called when the reporter is shut down,
    /// so it should never buffer or delay processing of data in any way.
    fn flush(&mut self) {}
}

/// Metadata for a span.
pub struct SpanMetadata {
    /// The scope of the span.
    pub scope: Vec<span::Id>,
    /// The callsite ID of the span.
    pub callsite: callsite::Identifier,
    /// The span ID of the span.
    pub target: &'static str,
    /// The name of the span.
    pub span_name: &'static str,
    /// The file the span was created in.
    pub file: &'static str,
    /// The line the span was created on.
    pub line: u32,
    /// Labels for the span.
    pub labels: Vec<(&'static str, String)>,
}

/// CPU time statistics for a span.
#[derive(Debug)]
pub struct SpanCpuTime {
    /// The elapsed CPU time in nanoseconds in user mode.
    pub elapsed_user_nanos: u64,
    /// The elapsed CPU time in nanoseconds in kernel mode.
    pub elapsed_system_nanos: u64,
}

/// Wall time statistics for a span.
#[derive(Debug)]
pub struct SpanWallTime {
    /// The elapsed wall time in nanoseconds while
    /// the span was entered.
    pub elapsed_busy_nanos: u64,
    /// The elapsed wall time in nanoseconds while
    /// the span was idle.
    pub elapsed_idle_nanos: u64,
}

/// Allocation statistics for a span.
#[derive(Debug, Default)]
pub struct SpanAllocations {
    /// The number of allocations.
    pub allocation_count: u64,
    /// The number of bytes allocated.
    pub allocated_bytes: u64,
}

/// Heap statistics for a span.
#[derive(Debug)]
pub struct SpanHeap {
    /// The number of bytes in use.
    pub in_use_bytes: u64,
    /// The number of allocations in use.
    pub in_use_count: u64,
}