typed_macros.h 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. // Copyright 2019 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef BASE_TRACE_EVENT_TYPED_MACROS_H_
  5. #define BASE_TRACE_EVENT_TYPED_MACROS_H_
  6. #include "base/trace_event/trace_event.h"
  7. #include "base/tracing_buildflags.h"
  8. #include "build/build_config.h"
  9. // Needed not for this file, but for every user of the TRACE_EVENT macros for
  10. // the lambda definition. So included here for convenience.
  11. #include "base/tracing/protos/chrome_track_event.pbzero.h"
  12. #include "third_party/perfetto/include/perfetto/tracing/event_context.h"
  13. #include "third_party/perfetto/include/perfetto/tracing/string_helpers.h"
  14. #if !BUILDFLAG(USE_PERFETTO_CLIENT_LIBRARY)
  15. #include "base/trace_event/typed_macros_internal.h"
  16. #if defined(TRACE_EVENT_BEGIN)
  17. #error "Another copy of perfetto tracing macros have been included"
  18. #endif
  19. // This file implements typed event macros [1,2] that will be provided by the
  20. // Perfetto client library in the future, as a stop-gap to support typed trace
  21. // events in Chrome until we are ready to switch to the client library's
  22. // implementation of trace macros.
  23. // [1] https://perfetto.dev/docs/instrumentation/track-events
  24. // [2] //third_party/perfetto/include/perfetto/tracing/track_event.h
  25. // TODO(crbug/1006541): Replace this file with the Perfetto client library.
  26. // Typed event macros:
  27. //
  28. // These macros emit a slice under |category| with the title |name|. Both
  29. // strings must be static constants. The track event is only recorded if
  30. // |category| is enabled for the tracing session.
  31. //
  32. // The slice is thread-scoped (i.e., written to the default track of the current
  33. // thread) unless overridden with a custom track object (see perfetto::Track).
  34. //
  35. // |name| must be a string with static lifetime (i.e., the same address must not
  36. // be used for a different event name in the future). If you want to use a
  37. // dynamically allocated name, do this:
  38. //
  39. // TRACE_EVENT("category", nullptr, [&](perfetto::EventContext ctx) {
  40. // ctx.event()->set_name(dynamic_name);
  41. // });
  42. //
  43. // The varargs can include a perfetto::Track (e.g. async events), a
  44. // base::TimeTicks timestamp, and a trace lambda. If passed, the lambda is
  45. // executed synchronously.
  46. //
  47. // Examples:
  48. //
  49. // // Sync event with typed field.
  50. // TRACE_EVENT("cat", "Name", [](perfetto::EventContext ctx) {
  51. // auto* event = ctx.event<perfetto::protos::pbzero::ChromeTrackEvent>();
  52. // // Fill in some field in event.
  53. // event->set_my_chrome_field();
  54. // });
  55. //
  56. // // Async event.
  57. // TRACE_EVENT_BEGIN("cat", "Name", perfetto::Track(1234));
  58. //
  59. // // Async event with explicit timestamp.
  60. // base::TimeTicks time_ticks;
  61. // TRACE_EVENT_BEGIN("cat", "Name", perfetto::Track(1234), time_ticks);
  62. // Begin a slice under |category| with the title |name|.
  63. // Defaults to the current thread's track.
  64. #define TRACE_EVENT_BEGIN(category, name, ...) \
  65. TRACING_INTERNAL_ADD_TRACE_EVENT(TRACE_EVENT_PHASE_BEGIN, category, name, \
  66. ##__VA_ARGS__)
  67. // End a slice under |category|.
  68. // Defaults to the current thread's track.
  69. #define TRACE_EVENT_END(category, ...) \
  70. TRACING_INTERNAL_ADD_TRACE_EVENT(TRACE_EVENT_PHASE_END, category, \
  71. trace_event_internal::kTraceEventEndName, \
  72. ##__VA_ARGS__)
  73. // Begin a thread-scoped slice which gets automatically closed when going out
  74. // of scope.
  75. //
  76. // BEWARE: similarly to TRACE_EVENT_BEGIN, this macro does accept a track, but
  77. // it does not work properly and should not be used.
  78. // TODO(b/154583431): figure out how to fix or disallow that and update the
  79. // comment.
  80. #define TRACE_EVENT(category, name, ...) \
  81. TRACING_INTERNAL_SCOPED_ADD_TRACE_EVENT(category, name, ##__VA_ARGS__)
  82. // Emit a single slice with title |name| and zero duration.
  83. // Defaults to the current thread's track.
  84. #define TRACE_EVENT_INSTANT(category, name, ...) \
  85. TRACING_INTERNAL_ADD_TRACE_EVENT(TRACE_EVENT_PHASE_INSTANT, category, name, \
  86. ##__VA_ARGS__)
  87. #endif // !BUILDFLAG(USE_PERFETTO_CLIENT_LIBRARY)
  88. #endif // BASE_TRACE_EVENT_TYPED_MACROS_H_