Google Git
Sign in
pigweed / third_party / github / project-chip / connectedhomeip / HEAD / . / src / tracing
tree: 97831676e5f1a03d18f6e6e8af7207736e7fc99c [path history] [tgz]
  1. darwin/
  2. esp32_diagnostics/
  3. esp32_trace/
  4. json/
  5. multiplexed/
  6. none/
  7. perfetto/
  8. tests/
  9. backend.h
  10. BUILD.gn
  11. log_declares.h
  12. macros.h
  13. metric_event.h
  14. metric_keys.h
  15. metric_macros.h
  16. README.md
  17. registry.cpp
  18. registry.h
  19. registry_disabled.cpp
  20. tracing_args.gni
src/tracing/README.md

Matter Tracing

This library provides a runtime-configurable tracing and logging infrastructure for matter. The overall tracing subsystem is enabled or disabled via the matter_enable_tracing_support build setting; when disabled all tracing code is compiled out completely.

Types of data

Low-Level Tracing

This is mostly intended for following execution flow and measuring time spent for various operations. These traces are either

  • scoped where separate begin and end events are emitted, or
  • instant where a single notable event is emitted, representing a point in time of a notable event.

The low-level tracing API is provided via MATTER_TRACE_* macros and is thread-safe.

Tracing labels and instant values MUST be constant strings as some backends rely on that property for caching (e.g. pw_trace would do tokenization and perfetto marks them as perfetto::StaticString)

The tracing implementation is selected via the matter_trace_config build setting; the selected implementation directly provides the implementations of the tracing macros, allowing these to be bridged to a platform tracing mechanism with very low overhead.

A multiplexed configuration is available that routes tracing macros through the runtime backend registry used by the higher-level Data Logging / Metrics API (see below). The none configuration compiles out trace macros completely.

Data Logging / Metrics

Data logging provides the tracing module the opportunity to report input/output data for matter data processing, as well as high-level operational metrics.

The data logging is generally limited in count and covers:

  • Messages, specifically sent matter requests and received matter responses
  • DNSSD operations as they are a core component of matter, specifically attempts to discover nodes as well as when a node is discovered or fails discovery.
  • Metrics, for tracking operational events with associated values and error codes

The high-level data logging / metrics API consists of various MATTER_LOG_* macros (e.g. MATTER_LOG_MESSAGE_SEND, MATTER_LOG_NODE_DISCOVERED, MATTER_LOG_METRIC, ...).

Backends for this data logging layer implement the chip::Tracing::Backend API (see backend.h), and are registered at runtime via chip::Tracing::Register() (see registry.h).

Note that while registration and unregistration of backends must be performed while the Matter stack lock is being held, data logging itself is thread-safe (and must be implemented as such by all backends.)