Better docs, also allow spawning its own runtime #97

arielb1 · 2025-09-21T16:01:34Z

📬 Issue #, if available:

✍️ Description of changes:

🔏 By submitting this pull request

I confirm that I've made a best effort attempt to update all relevant documentation.
I confirm that my contribution is made under the terms of the Apache 2.0 license.

Fixes async-profiler#96

This makes ProfilerOptions non-exhaustive, and is therefore technically a breaking-change, but that was a bug

rcoh · 2025-09-24T18:47:06Z

src/profiler.rs

-    /// Sets the reporting interval.
+    /// Sets the reporting interval (default: 30 seconds).
+    ///
+    /// This is the interval that samples are *reported* at, and is unrelated


since reported and collected can both mean sampled in this context, I think we should change it to be more explicit:

This is the interval that samples are reported to the backend (e.g. S3, Local file etc.) and is unrelated to the interval in which the application is sampled by async profiler (which defaults to 10hz)

rcoh · 2025-09-24T18:48:27Z

src/profiler.rs

+    /// to the interval in which samples are *collected*. There are few
+    /// needs to change this from the default 30 seconds.


as written sounds like it is about to list reasons. we should either list them or change it to

Most users should not change this setting.

rcoh · 2025-09-24T18:50:30Z

src/profiler.rs

+    #[cfg_attr(not(feature = "s3-no-defaults"), doc = "`S3Reporter`.")]
+    #[cfg_attr(feature = "s3-no-defaults", doc = "[`S3Reporter`].")]


can we assume docs are always built with --all-features?

[package.metadata.docs.rs] all-features = true

No, because people run cargo doc locally, and I don't want them to get spammy warnings.

also the tests run cargo test locally and can fail if there are problems in examples.

rcoh · 2025-09-24T18:52:50Z

src/profiler.rs

+    ///     .with_reporter(LocalReporter::new(path))
+    ///     .with_custom_agent_metadata(AgentMetadata::Other)


in the local reporter the metadata is totally ignored right? so this example might be slightly misleading

But AgentMetadata::Other prevents async-profiler from trying to auto-detect metadata, which is why it's important.

rcoh · 2025-09-24T18:53:26Z

src/reporter/local.rs

+/// # async fn main() -> Result<(), SpawnError> {
+/// let profiler = ProfilerBuilder::default()
+///    .with_reporter(LocalReporter::new("/tmp/profiles"))
+///    .with_custom_agent_metadata(AgentMetadata::Other)


with_custom_agent_metdata isn't required is it? So you shouldn't need to set it to use the LocalReporter?

or is that just required to suppress the error about missing metadata? Maybe we could add a uses_metadata() method to the reporter trait or something?

yea, it will prevent an error due to missing metadata

I don't like the unorthogonality of not having uses_metadata

rcoh · 2025-09-24T19:02:05Z

src/profiler.rs

        self.detach_inner();
    }
+
+    fn spawn_attached(


somewhat hard to follow the purpose of these different spawn code paths. some comments may help

added comment

rcoh · 2025-09-24T19:03:31Z

src/profiler.rs

+    /// [Profiler::spawn_controllable_thread_to_runtime].
+    ///
+    /// `spawn_fn` should be [`std::thread::spawn`], or some function that behaves like it (to
+    /// allow for configuring thread properties).


an example that sets the thread name would probably be very helpful

rcoh · 2025-09-24T19:05:19Z

src/profiler.rs

+    ///
+    /// This function must be run within a Tokio runtime. If your application does
+    /// not have a `main` Tokio runtime, see
+    /// [Profiler::spawn_controllable_thread_to_runtime].


should this link to spawn_thread instead?

rcoh · 2025-09-24T19:07:31Z

src/profiler.rs

-    pub fn with_native_mem(mut self, native_mem_interval: String) -> Self {
-        self.native_mem = Some(native_mem_interval);
+    pub fn with_native_mem_bytes(mut self, native_mem_interval: usize) -> Self {
+        self.native_mem = Some(native_mem_interval.to_string());


this works without an string suffix?

yea it works (bytes precision).

rcoh · 2025-09-24T19:07:46Z

src/profiler.rs

+        self
+    }
+
+    /// Sets the interval, in nanoseconds, in which the profiler will collect


can you use a Duration instead?

rcoh · 2025-09-25T17:45:49Z

.github/workflows/build.yml

        shell: bash
        working-directory: tests
-        run: chmod +x simple pollcatch-decoder && LD_LIBRARY_PATH=$PWD ./integration.sh
+        run: chmod +x simple pollcatch-decoder && LD_LIBRARY_PATH=$PWD ./integration.sh && LD_LIBRARY_PATH=$PWD ./separate_runtime_integration.sh


for ease of debugging we might want two separate targets / steps

Feels overcomplicated to me. If we have a problem with a big step, we can always split it.

rcoh · 2025-09-25T17:46:29Z

src/reporter/local.rs

+///
+/// It does not currently use the metadata, so if you are using
+/// [LocalReporter] alone, rather than inside a [MultiReporter], you
+/// can just use [AgentMetadata::Other] as metadata.


I think part of my confusion is from calling it Other. Should we call it NoMetadata?

rcoh · 2025-09-25T17:47:01Z

src/reporter/local.rs

+/// let profiler = ProfilerBuilder::default()
+///    .with_local_reporter("/tmp/profiles")
+///    .build();
+/// # if false { // don't spawn the profiler in doctests


should we just not run the doctests instead? They will still be compiled. (that also makes the build significantly faster)

I wanted to run as much of the doctests as I can, to make sure we don't have weird panic problems

src/profiler.rs

rcoh · 2025-09-25T17:49:28Z

src/profiler.rs

+    /// CPU-time samples, via the [async-profiler `interval` option].
+    ///
+    /// CPU-time samples (JFR `jdk.ExecutionSample`) sample only threads that
+    /// are currently running on a CPU, not threads that are sleeping.
+    ///
+    /// It can use a higher frequency than wall-clock sampling since the
+    /// number of the threads that are running on a CPU at a given time is
+    /// naturally limited by the number of CPUs, while the number of sleeping
+    /// threads can be much larger.
+    ///
+    /// The default is to do a CPU-time sample every 100 milliseconds.
+    ///
+    /// The async-profiler agent collects both CPU time and wall-clock time


this is really important info about the profiler in general. I wonder if we should hoist it into the readme. (the wall vs. cpu discussion)

It would probably also need to touch on the fact that tasks are one level higher still so you can't really see "wall clock" profiling for async programs

so you can't really see "wall clock" profiling for async programs

It is plenty useful since it is what catches problems with synchronous locks. It just tells you the answer to a different question.

rcoh · 2025-09-25T17:58:31Z

src/profiler.rs

+        doc = "[`S3Reporter`]: crate::reporter::s3::S3Reporter"
+    )]
+    ///
+    #[cfg_attr(feature = "s3-no-defaults", doc = "## Example")]


not sure if worth it but you could probably make this #[cfg_attr(feature = "s3-no-defaults", doc = include_str!("s3-example.md")] which would it easier to edit and easier to read this code and the similar code below

worth it, the cargo fmt way is ugly

rcoh · 2025-09-25T18:20:42Z

src/profiler.rs

+
+    /// Like [Self::spawn], but instead of spawning within the current Tokio
+    /// runtime, spawns within a new Tokio runtime and then runs a thread that calls
+    /// [tokio::runtime::Runtime::block_on] on that runtime, setting up the runtime


this link doesn't render in any of the three places it is used

Renders for me

rcoh · 2025-09-25T18:22:59Z

src/profiler.rs

+
+    /// Spawns this [RunningProfiler] into a separate thread within a new Tokio runtime,
+    /// and returns a [RunningProfilerThread] attached to it.
+    fn spawn_attached(


a table or other doc at the struct level with spawn spawn_controllable, spawn_controllable_to_thread etc. in struct docs would be very helpful in picking which one to use.

doc: add some examples

c3dacac

arielb1 requested a review from rcoh September 21, 2025 16:01

arielb1 force-pushed the better-docs branch from 8a5cdb4 to 59b42a7 Compare September 21, 2025 16:08

feat: allow running in its own Tokio runtime

4dc8825

Fixes async-profiler#96

arielb1 force-pushed the better-docs branch from 59b42a7 to 4dc8825 Compare September 21, 2025 16:46

allow configuring the profiler interval

4a95590

This makes ProfilerOptions non-exhaustive, and is therefore technically a breaking-change, but that was a bug

rcoh reviewed Sep 24, 2025

View reviewed changes

Ariel Ben-Yehuda added 2 commits September 24, 2025 19:55

temp

7d20fc3

address review comments

95eab39

arielb1 force-pushed the better-docs branch from 972c30f to 95eab39 Compare September 24, 2025 20:17

chore: add rustdoc tests

e78f5cf

arielb1 force-pushed the better-docs branch 2 times, most recently from 0f12ba2 to a7bb694 Compare September 24, 2025 20:33

doc: use with_local_reporter in docs

d5e60a8

arielb1 force-pushed the better-docs branch from a7bb694 to d5e60a8 Compare September 24, 2025 20:35

wording

37ff678

rcoh reviewed Sep 25, 2025

View reviewed changes

arielb1 force-pushed the better-docs branch from f6bfa90 to 1d050fd Compare September 25, 2025 19:35

address review comments

c2ef426

arielb1 force-pushed the better-docs branch from 1d050fd to c2ef426 Compare September 25, 2025 19:37

ci: add a step to install clippy

a82bbeb

rcoh approved these changes Sep 25, 2025

View reviewed changes

rcoh merged commit e66ca9f into async-profiler:main Sep 25, 2025
18 checks passed

This was referenced Sep 26, 2025

Make sampling interval configurable #93

Closed

Improve ProfilerBuilder docs #94

Closed

Add sensible default + non-string constructor for with_native_mem #95

Closed

		/// to the interval in which samples are collected. There are few
		/// needs to change this from the default 30 seconds.

		#[cfg_attr(not(feature = "s3-no-defaults"), doc = "`S3Reporter`.")]
		#[cfg_attr(feature = "s3-no-defaults", doc = "[`S3Reporter`].")]

		/// .with_reporter(LocalReporter::new(path))
		/// .with_custom_agent_metadata(AgentMetadata::Other)

Better docs, also allow spawning its own runtime #97

Better docs, also allow spawning its own runtime #97

Uh oh!

Conversation

arielb1 commented Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arielb1 Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arielb1 Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arielb1 Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arielb1 Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arielb1 commented Sep 21, 2025 •

edited

Loading

arielb1 Sep 24, 2025 •

edited

Loading

arielb1 Sep 24, 2025 •

edited

Loading

arielb1 Sep 25, 2025 •

edited

Loading

arielb1 Sep 25, 2025 •

edited

Loading