Debian Codegraph @

.cargo/vendor/profiling/README.md

raw
1 # profiling
2
3 Provides a very thin abstraction over instrumented profiling crates like `puffin`, `optick`, `tracy`, and `superluminal-perf`.
4
5 Mark up your code like this:
6
7 ```rust
8 #[profiling::function]
9 fn some_function() {
10 burn_time(5);
11
12 for i in 0..5 {
13 profiling::scope!("Looped Operation");
14 }
15 }
16 ```
17
18 See below for resulting visualization and more details on the exposed API.
19
20 **Friendly Warning:** Some profiler backends implicitly listen on network ports immediately when the host app is
21 launched. If this is a concern, please review the enabled profiler(s) documentation for details!
22
23 ## Puffin
24
25 * https://github.com/EmbarkStudios/puffin
26 * Cross-platform
27 * You need to call `profiling::finish_frame!()` at least once per frame
28 * To show the flamegraph, you either need to use [`puffin_http`](`https://github.com/EmbarkStudios/puffin/tree/main/puffin_http`) and [`puffin_viewer`](`https://github.com/EmbarkStudios/puffin/tree/main/puffin_viewer`), or if you're writing an [`egui`](https://github.com/emilk/egui) app, use [`puffin_egui`](`https://github.com/EmbarkStudios/puffin/tree/main/puffin_egui`).
29
30 [![Puffin](screenshots/puffin-small.png)](screenshots/puffin.png)
31
32 ## Optick
33
34 * https://github.com/bombomby/optick
35 * The upstream crate only provides binaries for windows. However it could probably be made to work by building
36 optick capture code and linking against it manually. The UI is windows only.
37
38 [![Optick](screenshots/optick-small.png)](screenshots/optick.jpeg)
39
40 ## Superluminal
41
42 * https://superluminal.eu
43 * Windows only
44
45 [![Superluminal](screenshots/superluminal-small.png)](screenshots/superluminal.jpeg)
46
47 ## Tracing
48
49 * https://crates.io/crates/tracing
50 * Cross-platform
51 * The tracing backend injects tracing `span!()` macros that match the lifetime of the profiling macros.
52 Tracing uses callbacks rather than inlining specific pre-determined code,
53 so it is more flexible than profiling
54 (at the cost of more lines of code and potentially higher overhead).
55 This allows existing and new tracing-compatible handlers to work with profiling.
56
57 ![Tracing](screenshots/tracing.png)
58
59 ## Tracy
60
61 * https://github.com/wolfpld/tracy
62 * Cross-platform (windows, macOS, linux)
63
64 [![Tracy](screenshots/tracy-small.png)](screenshots/tracy.jpeg)
65
66 ## Usage
67
68 Currently, there's just six macros:
69 * `profiling::scope!(name: &str, [tag: &str])`
70 * name: scopes will appear in the profiler under this name
71 * tag: optional extra data
72 * For maximum compatibility, you are **strongly** recommended to use literal strings for the name. Some backends require
73 static lifetime string references and some require literal strings.
74 * `#[profiling::function]`
75 * procmacro placed on a function to quickly wrap it in a scope using the function name
76 * `#[profiling::all_functions]`
77 * procmacro placed on a struct impl block to apply `#[profiling::function]` on each function under that struct impl block
78 * `#[profiling::skip]`
79 * use with `#[profiling::all_functions]`, placed this procmacro on a function to avoid the action that `#[profiling::all_functions]` apply
80 * `profiling::register_thread!([name: &str])`
81 * name: optional, defaults to `std::thread::current().name`, or `.id` if it's unnamed
82 * `profiling::finish_frame!()`
83 * Many profilers have the concept of a "frame" as a unit of work. Use this to indicate where one frame ends and the
84 next one begins.
85 * `profiling::function_scope!([tag: &str])`
86 * Macro that can be placed within a function to create a scope with the function name
87 * tag: optional extra data
88
89 Support for individual profilers can be turned on/off with feature flags. By default, they're all off, resulting in
90 no dependencies or runtime code.
91
92 ## Who is this for?
93 * Authors of binaries that want to have multiple options for profiling their code, but don't want to duplicate their
94 instrumentation once per each profiler's individual API.
95 * Authors of libraries that would like to instrument their crate for their end-users.
96
97 This crate is intended to be **TINY**. It won't support every possible usage, just the basics. I'm open to adding
98 more things but I plan to be very selective to maintain a slim size.
99
100 When enabled, using a macro produces identical code as if you used the wrapped profiling API directly. So it is
101 completely fine to directly use a profiler's API when this abstraction doesn't support something you want to do.
102
103 ## Alternatives
104
105 **tracing**: `tracing` is more flexible than `profiling` but is significantly larger and has
106 some potential runtime cost. `profiling` is only useful for instrumented profiling. Instrumentation is inserted directly
107 into your code inline via macros as if you were using the profiler's crate directly. This results in smaller code with
108 no additional overhead.
109
110 Using profiling crates (i.e. puffin/optick/etc.) directly:
111 * For authors of binaries, you may still need to use APIs on those crates to get started. But when instrumenting your
112 code, `profiling::scope!("Scope Name")` inside a function or `#[profiling::function]` on a function will instrument
113 it for all the supported profiler-specific crates. You can still use those crates directly if you want to take
114 advantage of custom APIs they provide to surface additional data.
115 * For authors of upstream libraries, this crate lets you implement simple instrumentation once. Hopefully this will
116 allow the community to benefit from instrumented profiling, even if a significant amount of a codebase is made
117 of upstream crates.
118
119 ## Using from a Binary
120
121 It's up to you to initialize the profiling crate of your choice (although some do not need explicit initialization
122 and will immediately work). The examples demonstrate this for all the supported crates, but it's worth looking
123 at the docs for the profiler you're interested in using! `profiling` re-exports the profiler crates if they are
124 enabled, simplifying the modifications you would need to make to your Cargo.toml.
125
126 Once initialized, you can mix/match the macros provided by your profiler of choice and the generic ones in this
127 crate. For example:
128
129 ```rust
130 // This may map to something like:
131 // - puffin::profile_scope!("Scope Name")
132 // - optick::event!("Scope Name")
133 // - tracing::span!(tracing::Level::INFO, "Scope Name")
134 // - superluminal_perf::begin_event("Scope Name")
135 profiling::scope!("Scope Name");
136
137 // This may map to something like:
138 // - puffin::profile_scope_data!("Scope Name", "extra data")
139 // - optick::event!("Scope Name"); optick::tag!("tag", "extra data");
140 // - tracing::span!(tracing::Level::INFO, "Scope Name", tag = "extra data")
141 // - superluminal_perf::begin_event_with_data("Scope Name", "extra data", 0)
142 profiling::scope!("Scope Name", "extra data");
143 ```
144
145 There is also a proc macro to decorate functions:
146
147 ```rust
148 #[profiling::function]
149 fn my_function() {
150
151 }
152 ```
153
154 Take a look at the code for the helpful macros `register_thread!()` and `finish_frame!()`.
155
156 I recommend adding features for each backend you want to use to your binary crate. This allows you to optionally compile
157 in code to setup and configure a backend.
158
159 ```toml
160 [dependencies]
161 profiling = "1.0"
162
163 [features]
164 profile-with-puffin = ["profiling/profile-with-puffin"]
165 profile-with-optick = ["profiling/profile-with-optick"]
166 profile-with-superluminal = ["profiling/profile-with-superluminal"]
167 profile-with-tracing = ["profiling/profile-with-tracing"]
168 profile-with-tracy = ["profiling/profile-with-tracy"]
169 ```
170
171 * You can use the default feature to quickly/temporarily turn something on: `default = ["profile-with-optick"]`
172 * `cargo run --features=profile-with-optick` works too!
173
174 ## Using from a Library
175
176 Add the profiling crate to Cargo.toml:
177
178 ```toml
179 [dependencies]
180 profiling = "1.0"
181 ```
182
183 Now you can instrument your library using the API exposed via the `profiling` crate.
184
185 If the end-user of your library doesn't use profiling, the macros in this crate will emit no code at all.
186
187 ## Feature Flags
188
189 * profile-with-puffin: Enable the `puffin` crate
190 * profile-with-optick: Enable the `optick` crate
191 * profile-with-superluminal: Enable the `superluminal-perf` crate
192 * profile-with-tracing: Enable the `tracing` crate. (This is just an abstraction layer - you'd want to hook it to do something!)
193 * profile-with-tracy: Enable the `tracy-client` crate.
194
195 **Only one backend can be enabled at a time!**
196
197 ## Examples
198
199 * simple: Shows a bare minimum requirements to do some simple instrumented profiling. Once it's running, you
200 can connect to the process using optick/tracy/superluminal. Some of these are windows only!
201
202 ```
203 run --example simple --features="profile-with-optick"
204 run --example simple --features="profile-with-tracy"
205 run --example simple --features="profile-with-puffin"
206 run --example simple --features="profile-with-superluminal"
207 ```
208
209 * puffin: Launches a basic app with imgui integration showing the puffin UI. This one should run everywhere
210 that supports imgui.
211
212 ```
213 cargo run --example puffin --features="profile-with-puffin"
214 ```
215
216 ## MSRV
217
218 This project will strive to keep a conservative MSRV, but some backends will support a lower MSRV than others.
219 The MSRV set in this project only represents the MSRV for compiling the profiling crate with no backends
220 enabled.
221
222 As a point of reference, currently the most popular crate relying on profiling is wgpu, and their
223 MSRV is constrained to Firefox nightly build MSRV. So the MSRV of this crate (ignoring backends)
224 should not move faster than wgpu and firefox nightly. (See `MINIMUM_RUST_VERSION` in
225 [`python/mozboot/mozboot/util.py`](https://searchfox.org/mozilla-central/source/python/mozboot/mozboot/util.py))
226
227 ## License
228
229 Licensed under either of
230
231 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
232 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
233
234 at your option.
235
236 The examples directory contains [`NotoSans-Medium.ttf`](https://www.google.com/get/noto/), available under SIL Open Font
237 License (OFL).
238
239 ### Contribution
240
241 Unless you explicitly state otherwise, any contribution intentionally
242 submitted for inclusion in the work by you, as defined in the Apache-2.0
243 license, shall be dual licensed as above, without any additional terms or
244 conditions.
245
246 See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT).