Source: feldera/feldera@1b448b7
Original author: Ben Pfaff <blp@feldera.com>
File renamed from crates/adapters/src/samply.rs to ./samply-markers/src/unix.rs

This commit runs cargo-fmt on the ported commit from feldera/feldera@1b448b7
to ensure that the code style is up to date with samply's repository.

This commit adds all of the required dependencies in order to
get the ported code from feldera/feldera@1b448b7 to build.

Some of these dependencies may be removed as I update the API
to my vision for the project.

This commit removes all of the code from unix.rs
that is not specific to actually writing to the `mmap`
files on unix systems. This preserves the original
author's attributions.

This commit adds the `SamplyTimestamp` implementation
with a default provider that always returns zero.

This commit adds the `SamplyMarker` implementation
with a default provider that intentionally does not
write the markers to a file.

This commit updates the `unix.rs` implementation
to be compatible with the uniform internal provider
APIs that markers require in order to function.

This commit adds unimplemented stubs for a
Windows provider that would conform to the
uniform internal provider APIs.

This commit adds a `SamplyTimer` abstraction
which is a scoped RAII object that records the
start time it was created and emits an interval
marker when it goes out of scope.

This commit adds a declarative macro wrapper around the
`SamplyMarker` implementation with the intent to be the
primary way of emitting markers.

This commit adds a declarative macro wrapper around the
`SamplyTimer` implementation with the intent to be the
primary way of constructing timer objects to emit intervals.

This commit adds a declarative macro wrapper that will
automatically measure the runtime of a provided sync
or async code block by emitting an intterval marker when
the code block has finished running.

This commit adds a `prelude` module to the `samply-markers`
crate so that users have an easy way to glob import everything
that they need to instrument their code with markers.

This commit adds a top-level doc comment to the `samply-markers` crate.

This commit updates the way Samply adds markers to
use instant marker timing, instead of a span marker
timing, if the start time and end time of the span
are exactly the same.

Admittedly, I don't like this change, and I would like
to revert it once a different marker file format is
potentially supported.

I think that a zero-length interval should be possible
if that is actually what was measured. But as of right
now, I have no way to emit an actual instant marker
given the current file-format restrictions.

This commit adds integreation tests. The tests for
Unix systems are fully fleshed out, ensuring that
markers are correctly written to the expected files.

The for Windows systems currently expect to panic.

This commit adds a project-level README
file to the samply-markers crate.

This commit ensures that .truncate(true) is set when creating marker files to clarify
that existing files should be overwritten. This is unlikely to happen with the temp
directory file format containing the PID and TID, but if it were to happen, it's better
to be safe than sorry. This also fixes the clippy::suspicious_open_options warning.

This commit ensures that the `unix.rs` file correctly handles
emitting markers on macOS. I hadn't realized in previous commits
that the functionality was only working on Linux.

It should work on both systems now.

This commit adds a safety comment to every unsafe block
in the `unix.rs` file, explaining why I blieve the call
is justified.

This commit adds an examples directory with instructions
on how to build, run, and profile the examples shown in
the main README file.

This commit improves the performance of samply-markers
when enabled, based on benchmarks of the Fibonacci example
increased to n = 30 and measured with hyperfine.

The Fibonacci example at n = 30 makes 2,692,536 recursive
calls, emitting the same number of markers. This provides
a great stress test for marker emission overhead.

The configurations are as follows:

- disabled: samply-markers disabled
- enabled-baseline: samply-markers enabled before any performance improvements
- buffered-writes: adds the buffered writes improvement
- itoa-buffers: adds the itoa improvement on top of buffered writes

Linux results:

  Benchmark 1: ./fib30-disabled
    Time (mean ± σ):     128.2 ms ±   0.6 ms    [User: 127.2 ms, System: 0.9 ms]
    Range (min … max):   127.1 ms … 129.6 ms    23 runs

  Benchmark 2: ./fib30-enabled-baseline
    Time (mean ± σ):      3.144 s ±  0.009 s    [User: 0.924 s, System: 2.220 s]
    Range (min … max):    3.134 s …  3.161 s    10 runs

  Benchmark 3: ./fib30-enabled-buffered-writes
    Time (mean ± σ):     522.9 ms ±   1.1 ms    [User: 478.9 ms, System: 43.7 ms]
    Range (min … max):   520.2 ms … 524.1 ms    10 runs

  Benchmark 4: ./fib30-enabled-itoa-buffers
    Time (mean ± σ):     423.1 ms ±   1.8 ms    [User: 377.8 ms, System: 45.1 ms]
    Range (min … max):   419.6 ms … 426.3 ms    10 runs

  Summary
    ./fib30-disabled ran
      3.30 ± 0.02 times faster than ./fib30-enabled-itoa-buffers
      4.08 ± 0.02 times faster than ./fib30-enabled-buffered-writes
     24.53 ± 0.14 times faster than ./fib30-enabled-baseline

macOS results:

  Benchmark 1: ./fib30-disabled
    Time (mean ± σ):      90.7 ms ±   0.4 ms    [User: 89.4 ms, System: 0.9 ms]
    Range (min … max):    90.0 ms …  91.6 ms    31 runs

  Benchmark 2: ./fib30-enabled-baseline
    Time (mean ± σ):      4.384 s ±  0.053 s    [User: 0.578 s, System: 3.783 s]
    Range (min … max):    4.295 s …  4.495 s    10 runs

  Benchmark 3: ./fib30-enabled-buffered-writes
    Time (mean ± σ):     257.4 ms ±   1.8 ms    [User: 237.6 ms, System: 16.9 ms]
    Range (min … max):   255.1 ms … 261.8 ms    11 runs

  Benchmark 4: ./fib30-enabled-itoa-buffers
    Time (mean ± σ):     187.6 ms ±   1.1 ms    [User: 169.9 ms, System: 16.1 ms]
    Range (min … max):   186.3 ms … 190.1 ms    15 runs

  Summary
    ./fib30-disabled ran
      2.07 ± 0.01 times faster than ./fib30-enabled-itoa-buffers
      2.84 ± 0.02 times faster than ./fib30-enabled-buffered-writes
     48.32 ± 0.62 times faster than ./fib30-enabled-baseline

Profiles:

Ubuntu:

* fib30-disabled: https://share.firefox.dev/48id64U
* fib30-enabled-baseline: https://share.firefox.dev/47K8Taf
* fib30-enabled-buffered-writes: https://share.firefox.dev/4oK5Uog
* fib30-enabled-itoa-buffers: https://share.firefox.dev/47ZtGVQ

macOS:

* fib30-disabled: https://share.firefox.dev/3LMmaX2
* fib30-enabled-baseline: https://share.firefox.dev/49TPODF
* fib30-enabled-buffered-writes: https://share.firefox.dev/4oFo1LP
* fib30-enabled-itoa-buffers: https://share.firefox.dev/3K6rLqG

Overall:
- Using buffered writes dramatically reduces overhead.
- Using itoa provides an additional ~19% improvement on Linux and ~27% on macOS.