functiontrace_server/
function_trace.rs

1use std::borrow::Cow;
2use std::num::NonZeroU32;
3use std::time::Duration;
4
5/// A representation of the various trace messages a client thread can send us during normal
6/// tracing operation.
7///
8/// We use [`Cow`] instead of [`String`] because most strings should be zero-copy deserializable.
9#[derive(Debug)]
10#[cfg_attr(feature = "server", derive(serde::Deserialize))]
11#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
12#[serde(tag = "type")]
13pub enum FunctionTrace<'event> {
14    /// A request to register this as a new thread.
15    ///
16    /// **NOTE**: This must be sent as the first message from a new thread, and may not be sent
17    /// twice by any thread.
18    RegisterThread(ThreadRegistration),
19    Call {
20        time: Duration,
21        #[serde(borrow)]
22        func_name: Cow<'event, str>,
23        #[serde(borrow)]
24        filename: Cow<'event, str>,
25        /// This _should_ be a [`NonZeroU32`], but sometimes Python passes us things that seem like
26        /// they should be `NativeCall`s instead.  It's easier to be liberal here and to handle
27        /// this later.
28        linenumber: u32,
29    },
30    Return {
31        time: Duration,
32        #[serde(borrow)]
33        func_name: Cow<'event, str>,
34    },
35    NativeCall {
36        time: Duration,
37        #[serde(borrow)]
38        func_name: Cow<'event, str>,
39        #[serde(borrow)]
40        module_name: Cow<'event, str>,
41    },
42    NativeReturn {
43        time: Duration,
44        #[serde(borrow)]
45        func_name: Cow<'event, str>,
46    },
47    Exception {
48        time: Duration,
49        #[serde(borrow)]
50        exception_type: Cow<'event, str>,
51        #[serde(borrow)]
52        exception_value: Cow<'event, str>,
53        filename: String,
54        linenumber: NonZeroU32,
55    },
56    Log {
57        time: Duration,
58        #[serde(borrow)]
59        log_type: Cow<'event, str>,
60        #[serde(borrow)]
61        log_value: Cow<'event, str>,
62    },
63    Import {
64        time: Duration,
65        #[serde(borrow)]
66        module_name: Cow<'event, str>,
67    },
68    Allocation {
69        time: Duration,
70        details: AllocationDetails,
71    },
72}
73
74/// Information about allocations.
75#[derive(Debug)]
76#[cfg_attr(feature = "server", derive(serde::Deserialize))]
77#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
78#[serde(tag = "type")]
79pub enum AllocationDetails {
80    /// The amount and location of a new allocation
81    Alloc { bytes: usize, addr: usize },
82    /// The new size of a reallocation from `old_addr` to `new_addr`.
83    Realloc {
84        bytes: usize,
85        old_addr: usize,
86        new_addr: usize,
87    },
88    /// The address that was `free()`ed.
89    Free { old_addr: usize },
90}
91
92/// Information relevant for initializing a trace.
93#[derive(Debug)]
94#[cfg_attr(feature = "server", derive(serde::Deserialize))]
95#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
96pub struct TraceInitialization {
97    /// The name (typically based off of argv) of the program initializing the trace (ex:
98    /// `hello.py world`).
99    pub program_name: String,
100    /// The version information of the `functiontrace` client talking to this server (ex:
101    /// `py-functiontrace 0.3.0`).
102    pub program_version: String,
103    /// The version for the underlying language the program is running on (ex: `Python 3.7.1`).
104    pub lang_version: String,
105    /// The general operating system platform the program is running on (ex: `darwin`).
106    pub platform: String,
107    /// An opaque system time that all other client-sent times will be relative to.
108    pub time: Duration,
109}
110
111/// This message contains information for registering threads (including a program's main thread).
112#[derive(Debug)]
113#[cfg_attr(feature = "server", derive(serde::Deserialize))]
114#[cfg_attr(feature = "serialize", derive(serde::Serialize))]
115pub struct ThreadRegistration {
116    /// A system time for when this thread registered itself as being traced with FunctionTrace.
117    pub time: Duration,
118    /// The program name this thread corresponds to.
119    pub program_name: String,
120    /// The process this thread belongs to.
121    pub pid: usize,
122}
functiontrace_server/function_trace.rs

functiontrace_server/
function_trace.rs
