Declare a metric, optionally adding it to a group.

Overloads:

• PW_METRIC(variable_name, metric_name, value)
• PW_METRIC(group, variable_name, metric_name, value)
• variable_name - An identifier name for the created variable or member. For example: i2c_transactions might be used as a local or global metric; inside a class, could be named according to members (i2c_transactions_ for Google's C++ style).
• metric_name - The string name for the metric. This will be tokenized. There are no restrictions on the contents of the name; however, consider restricting these to be valid C++ identifiers to ease integration with other systems.
• value - The initial value for the metric. Must be either a floating point value (e.g. 3.2f) or unsigned int (e.g. 21u).
• group - A pw::metric::Group instance. If provided, the metric is added to the given group.

The macro declares a variable or member named variable_name with type pw::metric::TypedMetric<T>, and works in three contexts: global, local, and member.

1. At global scope:
   PW_METRIC(foo, "foo", 15.5f);

   void MyFunc() { foo.Increment(); }

   PW_METRIC

   #define PW_METRIC(...)

   Definition: metric.h:464
2. At local function or member function scope:
   void MyFunc() {

   PW_METRIC(foo, "foo", 15.5f);

   foo.Increment();

   // foo goes out of scope here; be careful!

   }
3. At member level inside a class or struct:
   struct MyStructy {

   void DoSomething() { somethings_.Increment(); }

   // Every instance of MyStructy will have a separate somethings counter.

   PW_METRIC(somethings_, "somethings", 0u);

   };

You can also put a metric into a group with the macro. Metrics can belong to strictly one group, otherwise an assertion will fail. Example:

Note

If you want a globally registered metric, see pw_metric/global.h; in that context, metrics are globally registered without the need to centrally register in a single place.

Control whether 64-bit metrics are enabled.

By default, 64-bit metrics are enabled automatically on 64-bit host platforms (e.g. x86_64, AArch64). On 32-bit target platforms (e.g. ARM Cortex-M), 64-bit metrics are disabled by default to prevent linker errors for atomic libcalls (__atomic_load_8).

Downstream projects targeting 32-bit platforms can opt-in to 64-bit metrics by defining PW_METRIC_CONFIG_ENABLE_64BIT=1 and linking the appropriate atomic helper library (e.g. @pigweed//pw_atomic:cortex_m_64bit_atomics).

Declare a pw::metric::TypedMetric<T> with name metric_name, and register it in the global metrics list pw::metric::global_metrics.

This is useful for cases where uncoordinated instrumentation with metrics is needed; for example, when instrumenting legacy code where plumbing a metric group around by dependency injection is infeasible.

Example:

Note that metrics defined with PW_METRIC_GLOBAL should never be added to groups defined with PW_METRIC_GROUP_GLOBAL. Each metric can only belong to one group, and metrics defined with PW_METRIC_GLOBAL are pre-registered with the global metrics list.

Warning

Do not create PW_METRIC_GLOBAL instances anywhere other than global scope. Putting these on an instance (member context) would lead to dangling pointers and misery. Metrics are never deleted or unregistered!

Declare a pw::metric::TypedMetric<T> with name metric_name and explicit type type, and register it in the global metrics list pw::metric::global_metrics.

This macro works identically to PW_METRIC_GLOBAL, but requires explicitly specifying the metric type (e.g. float, uint32_t, or uint64_t).

Example:

Declares a pw::metric::Group with name group_name; the name is tokenized. Works similar to PW_METRIC and can be used in the same contexts (global, local, and member). Optionally, the group can be added to a parent group.

Overloads:

• PW_METRIC_GROUP(variable_name, group_name)
• PW_METRIC_GROUP(parent_group, variable_name, group_name)

Example:

Declare a pw::metric::Group with name group_name, and register it in the global metric groups list pw::metric::global_groups.

Note that metrics created with PW_METRIC_GLOBAL should never be added to groups! Instead, just create a freestanding metric and register it into the global group (like in the example below).

Example:

Warning

Do not create PW_METRIC_GROUP_GLOBAL instances anywhere other than global scope. Putting these on an instance (member context) would lead to dangling pointers and misery. Metrics are never deleted or unregistered!

Declares a PW_METRIC_GROUP variable with static storage. These can be used in function scopes, but not in classes.

Overloads:

• PW_METRIC_GROUP_STATIC(variable_name, group_name)
• PW_METRIC_GROUP_STATIC(parent_group, variable_name, group_name)

Declares a PW_METRIC variable with static storage. These can be used in function scopes, but not in classes.

Overloads:

• PW_METRIC_STATIC(variable_name, metric_name, value)
• PW_METRIC_STATIC(group, variable_name, metric_name, value)

Declare a pw::metric::Token (pw::tokenizer::Token) for a metric with name metric_name. This token matches the .name() of a metric with the same name.

This is a wrapper around PW_TOKENIZE_STRING_MASK and carries the same semantics.

This is unlikely to be used by most pw_metric consumers.

Similar to PW_TOKENIZE_STRING_EXPR, converts a string literal to a uint32_t token within an expression. Requires C++.

Declare a metric with an explicit type, optionally adding it to a group.

Overloads:

• PW_METRIC_TYPED(variable_name, metric_name, type, value)
• PW_METRIC_TYPED(group, variable_name, metric_name, type, value)

This macro works identically to PW_METRIC, but requires explicitly specifying the metric type (e.g. float, uint32_t, or uint64_t). This is useful for declaring 64-bit metrics or when you want to make the metric's type explicit.

Example:

Declares a PW_METRIC_TYPED variable with static storage. These can be used in function scopes, but not in classes.

Overloads:

• PW_METRIC_TYPED_STATIC(variable_name, metric_name, type, value)
• PW_METRIC_TYPED_STATIC(group, variable_name, metric_name, type, value)