Idea: A companion crate for markers

[nordzilla]

Background

This issue is inspired by this conversation in Mozilla's Firefox Profiler Matrix channel.

It would be amazing to have a companion crate, e.g. samply-markers, that one could add to their project as a dependency. This crate would expose an API where the programmer could create new markers directly in their code that are compatible the the Firefox Profiler.

The crate would be responsible for recording the markers and persisting them in such a way that samply can locate them and insert them into the resulting profile.json.

@gregtatum presented an interesting thought on the idea:

"Ok, here's an idea if I'm understanding mmap correctly, which I haven't ever used in practice myself. The user's program imports the marker Rust crate. The marker crate mmaps a file at some kind of known path. As it collects markers from the user program, it writes them into the mmaped space. I believe this will lazily be persisted to file so shouldn't cause a performance problem. When the user program exits, samply reads in that file and pulls out all the markers. Samply is then in charge of persisting that data into the profile JSON format and joining it to the sampled data."

[vvuk]

There's actually already support on mac/linux for parsing a marker-{pid}.txt file that a process opens, however the file format is extremely simple (literally "[time] [name]"), which is not good for anything but low frequency markers and doesn't support ranges. Needs some care to do things like define markers up front and then refer to them by ID + provide binary payload in the actual marker stream.

[hardfist]

There's actually already support on mac/linux for parsing a marker-{pid}.txt file that a process opens, however the file format is extremely simple (literally "[time] [name]"), which is not good for anything but low frequency markers and doesn't support ranges. Needs some care to do things like define markers up front and then refer to them by ID + provide binary payload in the actual marker stream.

@vvuk the format is simple but the timestamp seems tricky, how can i align the timestamp with samply's internal timeline, is there any public api for generate timestamp which align with internal timeline?

[blp]

@vvuk the format is simple but the timestamp seems tricky, how can i align the timestamp with samply's internal timeline, is there any public api for generate timestamp which align with internal timeline?

At least on Linux, the timestamps are from the kernel's monotonic clock. You can get appropriate values with the nix crate:

use nix::time::{clock_gettime, ClockId};

let now = clock_gettime(ClockId::CLOCK_MONOTONIC).unwrap();
now.tv_sec() as i64 * 1_000_000_000 + now.tv_nsec() as i64

[blp]

There's actually already support on mac/linux for parsing a marker-{pid}.txt file that a process opens, however the file format is extremely simple (literally "[time] [name]"), which is not good for anything but low frequency markers and doesn't support ranges. Needs some care to do things like define markers up front and then refer to them by ID + provide binary payload in the actual marker stream.

The file format is start end name, specifying a range. (I've been using it the last few days.)

[DaniPopes]

Hey, just wanted to flag that I wrote a tracing adapter for the marker files that people might prefer using since they wouldn't have to write any new "spans": https://github.com/DaniPopes/tracing-samply/ (previous art: tracing-chrome, tracing-tracy)

(reposting from #710 (comment))

[nordzilla]

Hey, just wanted to flag that I wrote a tracing adapter for the marker files that people might prefer using since they wouldn't have to write any new "spans": https://github.com/DaniPopes/tracing-samply/ (previous art: tracing-chrome, tracing-tracy)

(reposting from #710 (comment))

It looks like your crate was implemented and published to crates.io within the span (hah... span) of roughly 4 hours. That doesn't give me much confidence that careful consideration has been put into the design and implementation.

In the spirit of assuming good faith in your intentions, I've filed at least a first issue (DaniPopes/tracing-samply#3) for the most blatant error that causes code to panic from simple and well-documented usage of a tracing span.

However, I have to say that I don't think I could personally endorse or recommend that anyone use your crate in its current state. I can't speak on behalf of the Samply project itself, because I am not, at the moment, a maintainer of Samply in any capacity, though I would like to get more involved with this project because I believe that Samply is an amazing tool that benefits many people.

For what it's worth, I think that the concept of being able to subscribe Samply to tracing automatically is a worthwhile endeavor for its convenience to the projects that already utilize tracing. But there are reasons why I explicitly removed tracing as a dependency in the initial implementation of #710, despite it being used in @blp's catalyst commit that I lifted into the base of the implementation.

I wish that you would have let your implementation settle for a moment, or even be reviewed, before publishing runnable code to crates.io, but we cannot change the past.

Given that it's already out there, I hope that you put the work in to make your crate function more correctly and unsurprisingly.

[DaniPopes]

Thanks for the report.

Given that I just released it, and I was the only person who ran that code, it's natural that there are going to be cases I didn't consider. So far I tested only with one project, which as it happens it never re-uses spans or uses spans with async code, so my initial approach worked fine.

My intention with the post is to solicit feedback on an alternative API for integrating samply markers. It's easier to test and integrate if it's already released on crates.io. I don't understand your concern for this since the API surface is very simple and these are issues that are easily fixable with a patch release, as I've already done with a few MacOS issues.

I'm curious as to why you removed support for tracing.

[nordzilla]

Given that I just released it, and I was the only person who ran that code, it's natural that there are going to be cases I didn't consider. So far I tested only with one project, which as it happens it never re-uses spans or uses spans with async code, so my initial approach worked fine.

I think that I just have a different perspective on the level of quality that a project should have before its source code is published to an official, persistent package-management system like crates.io, especially when it is associated, particularly by name, with other highly regarded projects such as tracing and samply.

My intention with the post is to solicit feedback on an alternative API for integrating samply markers. It's easier to test and integrate if it's already released on crates.io. I don't understand your concern for this since the API surface is very simple and these are issues that are easily fixable with a patch release, as I've already done with a few MacOS issues.

I think that you could have just as easily solicited feedback with your project only on GitHub to the same effect. In fact, I think that would have been preferable. However, I recognize that my views on this topic are subjective, and are just my own personal opinions. You are well within your rights to publish your own project at any time for any reason.

I don't think this is a great place to debate the philosophies of when it is most appropriate to publish a project for others to use. There is no objectively correct single answer, and I'm sure there are many people out there who disagree with my perspective for various reasons.

I wish you luck with your project, and I hope that people find benefit in using it.

I'm curious as to why you removed support for tracing.

Tracing spans have a lot of complexity:

• They can be entered and exited multiple times, as we've discussed.
• They are Clone, Send, and Sync.
• They can have parent/child relationships (e.g. child_of()).
• They can have indirect causal relationships (e.g. follows_from()).

It wasn't immediately clear to me how how all of these considerations should interact with emitting markers for Samply. I felt that a simpler API to build upon would be more approachable, and that convenience functionality with regard to things like tracing could follow once the core functionality for emitting markers felt relatively stable.

There are also the different levels for tracing, such as info and debug. Currently, samply's marker system can only categorize the markers as "SimpleMarker," and I felt that this functionality would be better served once a more robust marker metadata system has been put in place.