Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

tracing sdk documentation outdated #28

Closed
nickdesaulniers opened this issue May 23, 2020 · 10 comments
Closed

tracing sdk documentation outdated #28

nickdesaulniers opened this issue May 23, 2020 · 10 comments

Comments

@nickdesaulniers
Copy link
Member

nickdesaulniers commented May 23, 2020

As a big fan of systrace on Android, I was looking to make use of perfetto to measure custom events in LLVM running on a Linux host.

I'm having a hard time from the documentation building a library+header that I can link against+include into a simple hello world binary. Once I have that figured out, I'd like to wire it up to LLVM's build system.

I'm mostly following this page: https://perfetto.dev/docs/instrumentation/tracing-sdk

It provides instructions for building against libperfetto using Cmake. While that's what we'll end up using for LLVM, for hello world I just want to know the -I, -l and -L commands (where to search for includes, what library to link against, where to search for libraries).

When I try to build hello world:

#include <perfetto.h>

#include <unistd.h>

PERFETTO_DEFINE_CATEGORIES(
    perfetto::Category("hello").SetDescription("my first cat"));

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();
}

via

clang++ -I /tmp/perfetto/sdk -L /tmp/perfetto/sdk/ -lperfetto main.cpp

I see the following failures:

main.cpp:6:15: error: no member named 'Category' in namespace 'perfetto'
    perfetto::Category("hello").SetDescription("my first cat"));
    ~~~~~~~~~~^
/tmp/perfetto/sdk/perfetto.h:6917:40: note: expanded from macro 'PERFETTO_DEFINE_CATEGORIES'
  PERFETTO_INTERNAL_DECLARE_CATEGORIES(__VA_ARGS__);           \
                                       ^~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6691:7: note: expanded from macro 'PERFETTO_INTERNAL_DECLARE_CATEGORIES'
      __VA_ARGS__};                                                           \
      ^~~~~~~~~~~
main.cpp:5:1: error: invalid application of 'sizeof' to an incomplete type '::perfetto::internal::TrackEventCategory const[]'
PERFETTO_DEFINE_CATEGORIES(
^~~~~~~~~~~~~~~~~~~~~~~~~~~
/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:6693:13: note: expanded from macro 'PERFETTO_INTERNAL_DECLARE_CATEGORIES'
      sizeof(kCategories) / sizeof(kCategories[0]);                           \
            ^~~~~~~~~~~~~
main.cpp:5:1: error: variable length array declaration not allowed at file scope
PERFETTO_DEFINE_CATEGORIES(
^~~~~~~~~~~~~~~~~~~~~~~~~~~
/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:6695:31: note: expanded from macro 'PERFETTO_INTERNAL_DECLARE_CATEGORIES'
  extern std::atomic<uint8_t> g_category_state_storage[kCategoryCount];       \
                              ^                        ~~~~~~~~~~~~~~
main.cpp:5:1: error: static_assert expression is not an integral constant expression
PERFETTO_DEFINE_CATEGORIES(
^~~~~~~~~~~~~~~~~~~~~~~~~~~
/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:44: note: expanded from macro 'PERFETTO_INTERNAL_DECLARE_CATEGORIES'
  static_assert(kConstExprCategoryRegistry.ValidateCategories(),              \
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~
main.cpp:11:3: error: no matching function for call to 'Validate'
  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:3: note: expanded from macro 'PERFETTO_GET_CATEGORY_INDEX'
  ::perfetto::internal::TrackEventCategoryRegistry::Validate<                \
  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6401:27: note: candidate template ignored: invalid explicitly-specified argument for template parameter 'CategoryIndex'
  static constexpr size_t Validate() {
                          ^
main.cpp:11:3: error: no matching function for call to 'Validate'
  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:6759:9: note: expanded from macro 'PERFETTO_INTERNAL_TRACK_EVENT'
        PERFETTO_GET_CATEGORY_INDEX(category)>(instances, name,               \
        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6737:3: note: expanded from macro 'PERFETTO_GET_CATEGORY_INDEX'
  ::perfetto::internal::TrackEventCategoryRegistry::Validate<                \
  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6401:27: note: candidate template ignored: invalid explicitly-specified argument for template parameter 'CategoryIndex'
  static constexpr size_t Validate() {
                          ^
main.cpp:11:3: error: no matching function for call to 'Validate'
  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:6783:7: note: expanded from macro 'PERFETTO_INTERNAL_SCOPED_TRACK_EVENT'
      TRACE_EVENT_BEGIN(category, name, ##__VA_ARGS__);                       \
      ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6933:3: note: expanded from macro 'TRACE_EVENT_BEGIN'
  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:3: note: expanded from macro 'PERFETTO_GET_CATEGORY_INDEX'
  ::perfetto::internal::TrackEventCategoryRegistry::Validate<                \
  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6401:27: note: candidate template ignored: invalid explicitly-specified argument for template parameter 'CategoryIndex'
  static constexpr size_t Validate() {
                          ^
main.cpp:11:3: error: no matching function for call to 'Validate'
  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:6783:7: note: expanded from macro 'PERFETTO_INTERNAL_SCOPED_TRACK_EVENT'
      TRACE_EVENT_BEGIN(category, name, ##__VA_ARGS__);                       \
      ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6933:3: note: expanded from macro 'TRACE_EVENT_BEGIN'
  PERFETTO_INTERNAL_TRACK_EVENT(               \
  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6759:9: note: expanded from macro 'PERFETTO_INTERNAL_TRACK_EVENT'
        PERFETTO_GET_CATEGORY_INDEX(category)>(instances, name,               \
        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6737:3: note: expanded from macro 'PERFETTO_GET_CATEGORY_INDEX'
  ::perfetto::internal::TrackEventCategoryRegistry::Validate<                \
  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/tmp/perfetto/sdk/perfetto.h:6401:27: note: candidate template ignored: invalid explicitly-specified argument for template parameter 'CategoryIndex'
  static constexpr size_t Validate() {
                          ^
8 errors generated.
@nickdesaulniers
Copy link
Member Author

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.

@nickdesaulniers nickdesaulniers changed the title multiple build errors for hello world + SDK tracing sdk documentation outdated May 23, 2020
@primiano
Copy link
Collaborator

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

@betasheet
Copy link
Collaborator

betasheet commented May 26, 2020

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

@primiano
Copy link
Collaborator

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.

@skyostil
Copy link
Contributor

skyostil commented May 26, 2020

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?

@primiano
Copy link
Collaborator

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.

@primiano
Copy link
Collaborator

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

@skyostil
Copy link
Contributor

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.

@nickdesaulniers
Copy link
Member Author

nickdesaulniers commented May 29, 2020

thanks all, LGTM
its_working

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?

@primiano
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants