tracing sdk documentation outdated about perfetto HOT 10 CLOSED

pulling open /tmp/perfetto/sdk/perfetto.cc, I can see a note:

47989 //       PERFETTO_DEFINE_CATEGORIES(                                                                                         
47990 //           PERFETTO_CATEGORY(base),                                                                                        
47991 //           PERFETTO_CATEGORY(v8),                                                                                          
47992 //           PERFETTO_CATEGORY(cc));

so it looks like the macro PERFETTO_CATEGORY should be used, rather than the explicit class perfetto::Category which doesn't seem to exist. Ok, so that looks like a simple documentation bug.

PERFETTO_DEFINE_CATEGORIES(PERFETTO_CATEGORY("hello"));

Now this fails with:

main.cpp:5:1: error: static_assert failed due to requirement 'kConstExprCategoryRegistry.ValidateCategories()' "Invalid category names found"
PERFETTO_DEFINE_CATEGORIES(PERFETTO_CATEGORY("hello"));
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6917:3: note: expanded from macro 'PERFETTO_DEFINE_CATEGORIES'
  PERFETTO_INTERNAL_DECLARE_CATEGORIES(__VA_ARGS__);           \
  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6714:3: note: expanded from macro 'PERFETTO_INTERNAL_DECLARE_CATEGORIES'
  static_assert(kConstExprCategoryRegistry.ValidateCategories(),              \
  ^             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6402:5: error: static_assert failed due to requirement '18446744073709551615UL != kInvalidCategoryIndex' "A track event used an unknown category. Please add it to PERFETTO_DEFINE_CATEGORIES()."
    static_assert(CategoryIndex != kInvalidCategoryIndex,
    ^             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
main.cpp:10:3: note: in instantiation of function template specialization 'perfetto::internal::TrackEventCategoryRegistry::Validate<18446744073709551615>' requested here
  TRACE_EVENT("hello", "do_sleep");
  ^
/tmp/perfetto/sdk/perfetto.h:6946:3: note: expanded from macro 'TRACE_EVENT'
  PERFETTO_INTERNAL_SCOPED_TRACK_EVENT(category, name, ##__VA_ARGS__)
  ^
/tmp/perfetto/sdk/perfetto.h:6779:27: note: expanded from macro 'PERFETTO_INTERNAL_SCOPED_TRACK_EVENT'
      ~EventFinalizer() { TRACE_EVENT_END(category); }                        \
                          ^
/tmp/perfetto/sdk/perfetto.h:6939:3: note: expanded from macro 'TRACE_EVENT_END'
  PERFETTO_INTERNAL_TRACK_EVENT(       \
  ^
/tmp/perfetto/sdk/perfetto.h:6745:7: note: expanded from macro 'PERFETTO_INTERNAL_TRACK_EVENT'
      PERFETTO_GET_CATEGORY_INDEX(category)>([&](uint32_t instances) {        \
      ^
/tmp/perfetto/sdk/perfetto.h:6737:53: note: expanded from macro 'PERFETTO_GET_CATEGORY_INDEX'
  ::perfetto::internal::TrackEventCategoryRegistry::Validate<                \
                                                    ^
2 errors generated.

from perfetto.

@skyostil @betasheet
can you have a look here? maybe our docs are outdated?

from perfetto.

I have a feeling this might be missing a:
PERFETTO_TRACK_EVENT_STATIC_STORAGE();

We should probably add this to the docs :)

FWIW, perfetto::Category should also work, not sure why it doesn't. We have tests that use it:
https://source.chromium.org/chromium/chromium/src/+/master:third_party/perfetto/src/tracing/test/api_integrationtest.cc;l=80

The PERFETTO_CATEGORY macro is deprecated and only expands to perfetto::Category too:
https://source.chromium.org/chromium/chromium/src/+/master:third_party/perfetto/include/perfetto/tracing/track_event.h;l=131

from perfetto.

I think we really need a snippet / example source code that works.
People can figure all the rest but we must have an example .cc file that shows the thing working.

from perfetto.

The issue here is that the v3.1 SDK is fairly old at this point and doesn't match the latest API described by the documentation. The code here needs two changes to match v3.1: category registration and adding the static storage macro as pointed out by @betasheet:

#include <perfetto.h>

#include <unistd.h>

PERFETTO_DEFINE_CATEGORIES(
    PERFETTO_CATEGORY(hello));

PERFETTO_TRACK_EVENT_STATIC_STORAGE();

void do_sleep() {
  TRACE_EVENT("hello", "do_sleep");
  sleep(3);
}

int main(int argv, char** argc) {
  perfetto::TracingInitArgs args;
  args.backends |= perfetto::kInProcessBackend;
  perfetto::Tracing::Initialize(args);
  perfetto::TrackEvent::Register();
  do_sleep();
}

I checked that this builds with:

c++ -I perfetto/sdk -lpthread hello.cc perfetto/sdk/perfetto.cc

Here's a repo with fully working minimal examples with v3.1: https://github.com/skyostil/perfetto-sdk-example

@primiano -- let's make a new SDK release to bring everything in line. Also, should we somehow merge the above repo and https://github.com/primiano/perfetto-sdk?

from perfetto.

Ahh gotcha.
So, strong yes to a new release and also consolidating the sdk examples.
I am happy to nuke https://github.com/primiano/perfetto-sdk (that was just needed for some pre-sdk work with some other companies) in favour of a living examples/ directory somewhere.

from perfetto.

@nickdesaulniers can you check if this JustWorks with v4.0 we just released?
https://github.com/google/perfetto/tree/v4.0

from perfetto.

With v4.1 we now also have integrated the SDK samples into the repository: https://cs.android.com/android/platform/superproject/+/master:external/perfetto/examples/sdk/README.md

Let me close this this issue. If you run into more problems with the SDK, please open a new issue.

from perfetto.

thanks all, LGTM

Was the updated documentation pushed?
https://perfetto.dev/docs/instrumentation/tracing-sdk
https://perfetto.dev/docs/instrumentation/track-events
** EDIT **
Looks like the newest sdk is referenced in the clone command. I was curious about the references to perfetto::Category though?

Next n00b question, when I run the produced a.out, I see:

$ ./a.out                                                                                 
[093.170] perfetto.cc:46436       Producer 1 connected
[093.170] perfetto.cc:37317       Producer connected
[093.170] perfetto.cc:48099       Producer 1 registered data source "track_event"

does this write a trace somewhere (using in process mode)? https://perfetto.dev/docs/quickstart/linux-tracing seems to imply that another command line utility is needed?

from perfetto.

Was the updated documentation pushed?

I think so given the updated tag.
Now there are some examples in https://github.com/google/perfetto/tree/master/examples/sdk

Next n00b question, when I run the produced a.out, I see:

Those log statements are only about the initialization. Tracing is not started at that point (you'd see a "Enabling tracing... " message otherwise.

does this write a trace somewhere (using in process mode)? > https://perfetto.dev/docs/quickstart/linux-tracing seems to imply that another command line utility is needed?

Those docs apply only to system-mode and not to in-process mode.
For in-process mode you need to start/stop/save the trace file yourself.
See the example in https://github.com/google/perfetto/blob/master/examples/sdk/example.cc
Where it does perfetto::Tracing::NewTrace().
That's what you need to do in in-process mode.

from perfetto.