Clang tool for adding trace annotations to functions

[Karel Král]

Dear Clang team,

TLDR; We believe that a tool which could annotate functions with TRACE_EVENTs would be really useful for developers when they are debugging. We have implemented an MVP in crrev.com/c/2332401 We would really appreciate your insight on how to provide such a tool to developers.

Longer version:

I am an intern of altimin@ working with the BFCache team.

We would like to provide a tool for developers that would auto-annotate functions (and import "base/trace_event/base_tracing.h"). I.e., it turns the following code:

int foo(int x, int y) {

  return 42;

}

into:

int foo(int x, int y) {

  TRACE_EVENT0("test", "foo");

  return 42;

}

Or later when we add support for |AddValue| even into:

int foo(int x, int y) {

  TRACE_EVENT1("test", "foo", "arguments", [&]() {

        auto traced_value = std::make_unique<base::trace_event::TracedValue>();

        traced_value->AddValue(x, "x");

        traced_value->AddValue(y, "y");

        return traced_value;

      }());

  return 42;

}

There is a minimum working prototype of the first version: crrev.com/c/2332401 (the prototype has already been used).

Tool design plans:

• We wish to keep the tool as minimal as possible to facilitate its maintenance.
• Do the heavy lifting of adding different parameter types in //base/trace_event (there is already a SFINAE support for various types in //base/trace_event/trace_conversion_helper.h).
• Leverage scripts in //tools/clang/scripts.

Questions:

• Do you have any tips or ideas regarding the tool?
• How can we supply such a tool to Chromium developers?
• What form is the best for such a tool?
• So far we have a standalone source to source tool, as that enables also annotating large source files later to be submitted as Chromium patches.

All the best

Karel

[Daniel Cheng]

Sorry for the delayed response. Some initial thoughts inline:

Is the idea that a developer could run this against a source file locally, and the tool would annotate all the methods with the trace macros? But the result wouldn't be checked in?

> Do you have any tips or ideas regarding the tool?

LibTooling, run_tool.py, et cetera aren't really officially maintained in Chromium; they're generally maintained on an ad-hoc basis, with the potential for extended breakage that doesn't get fixed until the next dev notices.

The network traffic annotation extractor used to use a clang tool but eventually migrated away due to this sort of issue: https://bugs.chromium.org/p/chromium/issues/detail?id=966883

> How can we supply such a tool to Chromium developers?

One way could be to ship it like clang-format does in a google storage bucket: https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=4379;drc=4f4593f8ccea72814337794b9bc5ecccd22f6271

Someone would have to be responsible for building it/uploading packages though.

> What form is the best for such a tool?

Can you clarify this question? Is this asking if we should be investigating an alternative other than clang tooling? As mentioned previously, I find LibTooling to be rather sharp and fiddly around the edges: due to gradual changes over time, things tend to randomly break (as you recently discovered with the empty_string tool). But I'd suggest that if we want to pursue a LIbTooling-based approach, we'd definitely want a frontend script that performs all the magic invocations. Developers would only have to run this script, rather than invoking run_tool.py directly.

Daniel

[Karel Král]

Thank you for the response!

Is the idea that a developer could run this against a source file locally, and the tool would annotate all the methods with the trace macros? But the result wouldn't be checked in?

I believe there would be two use-cases:

• Debugging: run the tool against source file(s) locally, do not make a patch out of the resulting traces (but fix the original issue).
• Bulk adding TRACE_EVENTs: run the tool locally, check the generated code by hand, make a patch out of this. This has already been done.

> Do you have any tips or ideas regarding the tool?

LibTooling, run_tool.py, et cetera aren't really officially maintained in Chromium; they're generally maintained on an ad-hoc basis, with the potential for extended breakage that doesn't get fixed until the next dev notices.

Yes. In some sense this tool would not be all that critical.

But I have not yet found a way how to build (e.g. empty_string) and be able to use it reliably after multiple |gclient sync|. And having to build Clang in order to be able to run a binary would not be pleasant...

 

> How can we supply such a tool to Chromium developers?

One way could be to ship it like clang-format does in a google storage bucket: https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=4379;drc=4f4593f8ccea72814337794b9bc5ecccd22f6271

Someone would have to be responsible for building it/uploading packages though.

@Alexander Timin Would this be a good option for this tool?

 

> What form is the best for such a tool?

Can you clarify this question? Is this asking if we should be investigating an alternative other than clang tooling? As mentioned previously, I find LibTooling to be rather sharp and fiddly around the edges: due to gradual changes over time, things tend to randomly break (as you recently discovered with the empty_string tool). But I'd suggest that if we want to pursue a LIbTooling-based approach, we'd definitely want a frontend script that performs all the magic invocations. Developers would only have to run this script, rather than invoking run_tool.py directly.

I believe this answers my question (LibTooling and a user-friendly script). 

All the best

Karel

[Alexander Timin]

On Wed, 12 Aug 2020 at 15:52, Karel Král <kare...@google.com> wrote:

Thank you for the response!

Is the idea that a developer could run this against a source file locally, and the tool would annotate all the methods with the trace macros? But the result wouldn't be checked in?

I believe there would be two use-cases:

• Debugging: run the tool against source file(s) locally, do not make a patch out of the resulting traces (but fix the original issue).
• Bulk adding TRACE_EVENTs: run the tool locally, check the generated code by hand, make a patch out of this. This has already been done.

> Do you have any tips or ideas regarding the tool?

LibTooling, run_tool.py, et cetera aren't really officially maintained in Chromium; they're generally maintained on an ad-hoc basis, with the potential for extended breakage that doesn't get fixed until the next dev notices.

Yes. In some sense this tool would not be all that critical.

But I have not yet found a way how to build (e.g. empty_string) and be able to use it reliably after multiple |gclient sync|. And having to build Clang in order to be able to run a binary would not be pleasant...

 

> How can we supply such a tool to Chromium developers?

One way could be to ship it like clang-format does in a google storage bucket: https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=4379;drc=4f4593f8ccea72814337794b9bc5ecccd22f6271

Someone would have to be responsible for building it/uploading packages though.

@Alexander Timin Would this be a good option for this tool?

Yep, that would be great — I would be happy to maintain this going forward. My understanding is that we wouldn't need to rebuild it more than a couple of times a year, so it's probably not worth coming up with a smarter solution than make && scp.

[Daniel Cheng]

On Wed, Aug 12, 2020 at 8:00 AM Alexander Timin <alt...@google.com> wrote:

On Wed, 12 Aug 2020 at 15:52, Karel Král <kare...@google.com> wrote:

Thank you for the response!

Is the idea that a developer could run this against a source file locally, and the tool would annotate all the methods with the trace macros? But the result wouldn't be checked in?

I believe there would be two use-cases:

• Debugging: run the tool against source file(s) locally, do not make a patch out of the resulting traces (but fix the original issue).
• Bulk adding TRACE_EVENTs: run the tool locally, check the generated code by hand, make a patch out of this. This has already been done.

> Do you have any tips or ideas regarding the tool?

LibTooling, run_tool.py, et cetera aren't really officially maintained in Chromium; they're generally maintained on an ad-hoc basis, with the potential for extended breakage that doesn't get fixed until the next dev notices.

Yes. In some sense this tool would not be all that critical.

But I have not yet found a way how to build (e.g. empty_string) and be able to use it reliably after multiple |gclient sync|. And having to build Clang in order to be able to run a binary would not be pleasant...

To clarify, this happens because the build scripts dump the output into //third_party/llvm-build/Release+Asserts. However, when you run gclient sync, it updates the clang toolchain... which is stored in the same place.

In addition, having your own local build prevents goma from working so this confirms that having a prebuilt version is best if you expect other people to use the tool.

Daniel

[Alexander Timin]

On Mon, 17 Aug 2020 at 19:55, Daniel Cheng <dch...@google.com> wrote:

On Wed, Aug 12, 2020 at 8:00 AM Alexander Timin <alt...@google.com> wrote:

On Wed, 12 Aug 2020 at 15:52, Karel Král <kare...@google.com> wrote:

Thank you for the response!

Is the idea that a developer could run this against a source file locally, and the tool would annotate all the methods with the trace macros? But the result wouldn't be checked in?

I believe there would be two use-cases:

• Debugging: run the tool against source file(s) locally, do not make a patch out of the resulting traces (but fix the original issue).
• Bulk adding TRACE_EVENTs: run the tool locally, check the generated code by hand, make a patch out of this. This has already been done.

> Do you have any tips or ideas regarding the tool?

LibTooling, run_tool.py, et cetera aren't really officially maintained in Chromium; they're generally maintained on an ad-hoc basis, with the potential for extended breakage that doesn't get fixed until the next dev notices.

Yes. In some sense this tool would not be all that critical.

But I have not yet found a way how to build (e.g. empty_string) and be able to use it reliably after multiple |gclient sync|. And having to build Clang in order to be able to run a binary would not be pleasant...

To clarify, this happens because the build scripts dump the output into //third_party/llvm-build/Release+Asserts. However, when you run gclient sync, it updates the clang toolchain... which is stored in the same place.

In addition, having your own local build prevents goma from working so this confirms that having a prebuilt version is best if you expect other people to use the tool.

Thanks! One question that I have is that the clang tools need clang headers to work — do you have any advice on how to distribute them?
(that's why I was thinking about just adding the binary to tools/clang/trace_annotator/bin/linux, as we will be able to store the required headers next to the tool) 

[Daniel Cheng]

Sorry I missed this email!

This sounds familiar, and it looks like what we did for rewrite_to_chrome_style: https://codereview.chromium.org/2806033003

Sadly, I think that storage bucket was deleted a long time ago, so the contents are lost to the mists of space and time. I really wonder why the tool needs these and can't simply use whatever is normally packaged with the build in Chrome though. Might be worth investigating...

Daniel

[Alexander Timin]

On Sat, 29 Aug 2020 at 07:00, Daniel Cheng <dch...@google.com> wrote:

Sorry I missed this email!

This sounds familiar, and it looks like what we did for rewrite_to_chrome_style: https://codereview.chromium.org/2806033003

Sadly, I think that storage bucket was deleted a long time ago, so the contents are lost to the mists of space and time. I really wonder why the tool needs these and can't simply use whatever is normally packaged with the build in Chrome though. Might be worth investigating...

Using ones normally packaged with Chrome theoretically should work, but I have two concerns:

- The header lookup logic is really interesting — it's pretty much a hardcoded path relative to the binary path. Downloading the binary and putting it is a special place inside chrome's build directory feels very weird and error-prone. 

- Chrome's clang is probably going to be updated more frequently than the tool binary, so it's probably a good idea to avoid adding an assumption that their headers match.

So overall binary + headers is my preference for now. (the ideal outcome actually would be to support building the headers into the binary as a part of libtooling build process. I saw the discussion around that on clang's mailing lists, but I don't think that I will be able to get to it any time soon).