Lines Matching full:metrics
16 tracking system health metrics like counts or set values. For example,
26 - **Tree structure** - Metrics can form a tree, enabling grouping of related
27 metrics for clearer organization.
29 - **Per object collection** - Metrics and groups can live on object instances
30 and be flexibly combined with metrics from other instances.
33 ``pw_metric`` supports automatic aggregation of metrics. This is optional but
44 and metrics might look like. In this case, the object's
45 ``MySubsystem::metrics()`` member is not globally registered; the user is on
46 their own for combining this subsystem's metrics with others.
60 Group& metrics() { return metrics_; }
68 The metrics subsystem has no canonical output format at this time, but a JSON
85 which is hard to change; where it is perhaps impossible to plumb metrics
86 objects around with dependency injection. The alternative to plumbing metrics
87 is to register the metrics through a global mechanism. ``pw_metric`` supports
126 In this case, the developer merely had to add the metrics header, define some
127 metrics, and then start incrementing them. These metrics will be available
137 - **Metrics offload** - To make it easy to get metrics off-device by sharing
140 - **Consistent format** - To get the metrics in a consistent format (e.g.
144 developers on a team to all collect metrics for their subsystems, without
150 UART). In those cases, metrics provide a low-overhead approach to understand
151 what is happening. During early boot, metrics can be incremented, then after
152 boot dumping the metrics provides insights into what happened. While basic
157 Metrics API reference
160 The metrics API consists of just a few components:
163 - The macros for scoped metrics and groups ``PW_METRIC`` and
165 - The macros for globally registered metrics and groups
167 - The global groups and metrics list: ``pw::metric::global_groups`` and
204 - A list of leaf metrics groups
213 Recursively dump a metrics group to ``pw_log``. Produces output like:
247 The **macros are the primary mechanism for creating metrics**, and should be
248 used instead of directly constructing metrics or groups. The macros handle
310 You can also put a metric into a group with the macro. Metrics can belong to
323 that contexts, metrics are globally registered without the need to
350 global metrics list ``pw::metric::global_metrics``.
363 Note that metrics defined with ``PW_METRIC_GLOBAL`` should never be added to
365 to one group, and metrics defined with ``PW_METRIC_GLOBAL`` are
366 pre-registered with the global metrics list.
372 pointers and misery. Metrics are never deleted or unregistered!
379 Note that metrics created with ``PW_METRIC_GLOBAL`` should never be added to
399 dangling pointers and misery. Metrics are never deleted or unregistered!
408 Use the Init() pattern for static objects with metrics
434 Through the course of building a product, the team may want to add metrics to
436 of data transfer. When adding metrics to the above imaginary UART object, one
491 // Note that metrics is not passed in here at all.
534 The order of declaring in-class groups and metrics matters if the metrics are
544 Group& metrics() { return metrics_; }
545 const Group& metrics() const { return metrics_; }
553 but the following one will not since the group is constructed after the metrics
562 Group& metrics() { return metrics_; }
563 const Group& metrics() const { return metrics_; }
573 Put **groups before metrics** when declaring metrics members inside classes.
581 advise destructing metrics or groups.
583 Individual metrics have atomic ``Increment()``, ``Set()``, and the value
589 **You must synchronize access to metrics**. ``pw_metrics`` does not
597 creation/destruction of metrics, ``pw_metric`` does not attempt to cover that
602 2. A run phase where metrics are collected. The tree structure is fixed.
604 Technically, it is possible to destruct metrics provided care is taken to
617 // BAD! The metrics have a different lifetime than the group.
627 **Don't destruct metrics**. Metrics are designed to be registered /
632 Exporting metrics
634 Collecting metrics on a device is not useful without a mechanism to export
635 those metrics for analysis and debugging. ``pw_metric`` offers an optional RPC
637 user-supplied set of on-device metrics via RPC. This facility is intended to
641 The metrics are fetched by calling the ``MetricService.Get`` RPC method, which
642 streams all registered metrics to the caller in batches (server streaming RPC).
643 Batching the returned metrics avoids requiring a large buffer or large RPC MTU.
646 returned metrics (post detokenization and jsonified) might look something like:
666 1. Define metrics around the system, and put them in a group or list of
667 metrics. Easy choices include for example the ``global_groups`` and
708 Take care when exporting metrics. Ensure **appropriate access control** is in
709 place. In some cases it may make sense to entirely disable metrics export for
710 production builds. Although reading metrics via RPC won't influence the
711 device, in some cases the metrics could expose sensitive information if
718 Calls to is ``MetricService::Get`` are blocking and will send all metrics
724 pumping the metrics into the streaming response. This gives flow control to
731 metrics. This does not include the RPC service.
744 There are many possible approaches to metrics collection and aggregation. We've
747 - **Atomic-sized metrics** - Using simple metric objects with just uint32/float
749 is more useful to have safe metrics increment from interrupt subroutines.
751 - **No aggregate metrics (yet)** - Aggregate metrics (e.g. average, max, min,
753 metrics. By taking this route, we can considerably simplify the core metrics
755 feed into the metrics system - for example by creating multiple metrics for a
763 Note that we will add helpers for aggregated metrics.
765 - **No virtual metrics** - An alternate approach to the concrete Metric class
766 in the current module is to have a virtual interface for metrics, and then
767 allow those metrics to have their own storage. This is attractive but can
772 alternatives include a global table of metrics, which has the disadvantage of
773 requiring centralizing the metrics -- an impossibility for middleware like
788 impossible to automatically collect the metrics without post-processing the
789 C++ code to find the metrics; a huge and debatably worthwhile approach. We
810 - **Aggregate metrics** - We plan to add support for aggregate metrics on top
814 - **Selectively enable or disable metrics** - Currently the metrics are always
816 few metrics are wanted in production, but having to strip all the metrics
818 metrics are enabled or disabled at compile time. This may rely on of C++20's
821 - **Async RCPC** - The current RPC service exports the metrics by streaming
823 metrics to completion; this may block the RPC thread. In the future we will
835 where post-initialization metrics manipulations are done.
837 - **Proto structure** - It may be possible to directly map metrics to a custom
845 constructors, and also make it safe to remove metrics dynamically. We will
847 is substantial on projects with many metrics.