functiontrace-server 0.8.6

The server component that FunctionTrace (functiontrace.com) clients will spawn and connect to
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

use std::borrow::Cow;
use std::num::NonZeroU32;
use std::time::Duration;

/// A representation of the various trace messages a client thread can send us during normal
/// tracing operation.
///
/// We use [`Cow`] instead of [`String`] because most strings should be zero-copy deserializable.
#[derive(Debug)]
#[cfg_attr(feature = "server", derive(serde::Deserialize))]
#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
#[serde(tag = "type")]
pub enum FunctionTrace<'event> {
    /// A request to register this as a new thread.
    ///
    /// **NOTE**: This must be sent as the first message from a new thread, and may not be sent
    /// twice by any thread.
    RegisterThread(ThreadRegistration),
    Call {
        time: Duration,
        #[serde(borrow)]
        func_name: Cow<'event, str>,
        #[serde(borrow)]
        filename: Cow<'event, str>,
        /// This _should_ be a [`NonZeroU32`], but sometimes Python passes us things that seem like
        /// they should be `NativeCall`s instead.  It's easier to be liberal here and to handle
        /// this later.
        linenumber: u32,
    },
    Return {
        time: Duration,
        #[serde(borrow)]
        func_name: Cow<'event, str>,
    },
    NativeCall {
        time: Duration,
        #[serde(borrow)]
        func_name: Cow<'event, str>,
        #[serde(borrow)]
        module_name: Cow<'event, str>,
    },
    NativeReturn {
        time: Duration,
        #[serde(borrow)]
        func_name: Cow<'event, str>,
    },
    Exception {
        time: Duration,
        #[serde(borrow)]
        exception_type: Cow<'event, str>,
        #[serde(borrow)]
        exception_value: Cow<'event, str>,
        filename: String,
        linenumber: NonZeroU32,
    },
    Log {
        time: Duration,
        #[serde(borrow)]
        log_type: Cow<'event, str>,
        #[serde(borrow)]
        log_value: Cow<'event, str>,
    },
    Import {
        time: Duration,
        #[serde(borrow)]
        module_name: Cow<'event, str>,
    },
    Allocation {
        time: Duration,
        details: AllocationDetails,
    },
}

/// Information about allocations.
#[derive(Debug)]
#[cfg_attr(feature = "server", derive(serde::Deserialize))]
#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
#[serde(tag = "type")]
pub enum AllocationDetails {
    /// The amount and location of a new allocation
    Alloc { bytes: usize, addr: usize },
    /// The new size of a reallocation from `old_addr` to `new_addr`.
    Realloc {
        bytes: usize,
        old_addr: usize,
        new_addr: usize,
    },
    /// The address that was `free()`ed.
    Free { old_addr: usize },
}

/// Information relevant for initializing a trace.
#[derive(Debug)]
#[cfg_attr(feature = "server", derive(serde::Deserialize))]
#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
pub struct TraceInitialization {
    /// The name (typically based off of argv) of the program initializing the trace (ex:
    /// `hello.py world`).
    pub program_name: String,
    /// The version information of the `functiontrace` client talking to this server (ex:
    /// `py-functiontrace 0.3.0`).
    pub program_version: String,
    /// The version for the underlying language the program is running on (ex: `Python 3.7.1`).
    pub lang_version: String,
    /// The general operating system platform the program is running on (ex: `darwin`).
    pub platform: String,
    /// An opaque system time that all other client-sent times will be relative to.
    pub time: Duration,
}

/// This message contains information for registering threads (including a program's main thread).
#[derive(Debug)]
#[cfg_attr(feature = "server", derive(serde::Deserialize))]
#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
pub struct ThreadRegistration {
    /// A system time for when this thread registered itself as being traced with FunctionTrace.
    pub time: Duration,
    /// The program name this thread corresponds to.
    pub program_name: String,
    /// The process this thread belongs to.
    pub pid: usize,
}