pw_metric/public/pw_metric/metric.h - pigweed/pigweed - Git at Google

 // Copyright 2020 The Pigweed Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
 // use this file except in compliance with the License. You may obtain a copy of
 // the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 // License for the specific language governing permissions and limitations under
 // the License.
 #pragma once

 #include <algorithm>
 #include <initializer_list>
 #include <limits>

 #include "pw_containers/intrusive_list.h"
 #include "pw_preprocessor/arguments.h"
 #include "pw_tokenizer/tokenize.h"

 namespace pw::metric {

 // Currently, this is for tokens, but later may be a char* when non-tokenized
 // metric names are supported.
 using tokenizer::Token;

 #define _PW_METRIC_TOKEN_MASK 0x7fffffff

 // An individual metric. There are only two supported types: uint32_t and
 // float. More complicated compound metrics can be built on these primitives.
 // See the documentation for a discussion for this design was selected.
 //
 // Size: 12 bytes / 96 bits - next, name, value.
 //
 // TODO(keir): Implement Set() and Increment() using atomics.
 // TODO(keir): Consider an alternative structure where metrics have pointers to
 // parent groups, which would enable (1) safe destruction and (2) safe static
 // initialization, but at the cost of an additional 4 bytes per metric and 4
 // bytes per group..
 class Metric : public IntrusiveList<Metric>::Item {
  public:
   Token name() const { return name_and_type_ & kTokenMask; }

   bool is_float() const { return (name_and_type_ & kTypeMask) == kTypeFloat; }
   bool is_int() const { return (name_and_type_ & kTypeMask) == kTypeInt; }

   float as_float() const;
   uint32_t as_int() const;

   // Dump a metric or metrics to logs. Level determines the indentation
   // indent_level up to a maximum of 4. Example output:
   //
   //   "$FCM4qQ==": 0,
   //
   // Note the base64-encoded token name. Detokenization tools are necessary to
   // convert this to human-readable form.
   void Dump(int indent_level = 0);
   static void Dump(IntrusiveList<Metric>& metrics, int indent_level = 0);

   // Disallow copy and assign.
   Metric(Metric const&) = delete;
   void operator=(const Metric&) = delete;

  protected:
   Metric(Token name, float value)
       : name_and_type_((name & kTokenMask) | kTypeFloat), float_(value) {}

   Metric(Token name, uint32_t value)
       : name_and_type_((name & kTokenMask) | kTypeInt), uint_(value) {}

   Metric(Token name, float value, IntrusiveList<Metric>& metrics);
   Metric(Token name, uint32_t value, IntrusiveList<Metric>& metrics);

   // Hide mutation methods, and only offer write access through the specialized
   // TypedMetric below. This makes it impossible to call metric.Increment() on
   // a float metric at compile time.
   void Increment(uint32_t amount = 1);

   void SetInt(uint32_t value);

   void SetFloat(float value);

  private:
   // The name of this metric as a token; from PW_TOKENIZE_STRING("my_metric").
   // Last bit of the token is used to store int or float; 0 == int, 1 == float.
   Token name_and_type_;

   union {
     float float_;
     uint32_t uint_;
   };

   enum : uint32_t {
     kTokenMask = _PW_METRIC_TOKEN_MASK,  // 0x7fff'ffff
     kTypeMask = 0x8000'0000,
     kTypeFloat = 0x8000'0000,
     kTypeInt = 0x0,
   };
 };

 // TypedMetric provides a type-safe wrapper the runtime-typed Metric object.
 // Note: Definition omitted to prevent accidental instantiation.
 // TODO(keir): Provide a more precise error message via static assert.
 template <typename T>
 class TypedMetric;

 // A metric for floats. Does not offer an Increment() function, since it is too
 // easy to do unsafe operations like accumulating small values in floats.
 template <>
 class TypedMetric<float> : public Metric {
  public:
   TypedMetric(Token name, float value) : Metric(name, value) {}
   TypedMetric(Token name, float value, IntrusiveList<Metric>& metrics)
       : Metric(name, value, metrics) {}

   void Set(float value) { SetFloat(value); }
   float value() const { return Metric::as_float(); }

  private:
   // Shadow these accessors to hide them on the typed version of Metric.
   float as_float() const { return 0.0; }
   uint32_t as_int() const { return 0; }
 };

 // A metric for uint32_ts. Offers both Set() and Increment().
 template <>
 class TypedMetric<uint32_t> : public Metric {
  public:
   TypedMetric(Token name, uint32_t value) : Metric(name, value) {}
   TypedMetric(Token name, uint32_t value, IntrusiveList<Metric>& metrics)
       : Metric(name, value, metrics) {}

   void Increment(uint32_t amount = 1u) { Metric::Increment(amount); }
   void Set(uint32_t value) { SetInt(value); }
   uint32_t value() const { return Metric::as_int(); }

  private:
   // Shadow these accessors to hide them on the typed version of Metric.
   float as_float() const { return 0.0; }
   uint32_t as_int() const { return 0; }
 };

 // A metric tree; consisting of children groups and leaf metrics.
 //
 // Size: 16 bytes/128 bits - next, name, metrics, children.
 class Group : public IntrusiveList<Group>::Item {
  public:
   Group(Token name);
   Group(Token name, IntrusiveList<Group>& groups);

   Token name() const { return name_; }

   void Add(Metric& metric) { metrics_.push_front(metric); }
   void Add(Group& group) { children_.push_front(group); }

   IntrusiveList<Metric>& metrics() { return metrics_; }
   IntrusiveList<Group>& children() { return children_; }

   const IntrusiveList<Metric>& metrics() const { return metrics_; }
   const IntrusiveList<Group>& children() const { return children_; }

   // Dump a metric group or groups to logs. Level determines the indentation
   // indent_level up to a maximum of 4. Example output:
   //
   //   "$6doqFw==": {
   //     "$05OCZw==": {
   //       "$VpPfzg==": 1,
   //       "$LGPMBQ==": 1.000000,
   //       "$+iJvUg==": 5,
   //     }
   //     "$9hPNxw==": 65,
   //     "$oK7HmA==": 13,
   //     "$FCM4qQ==": 0,
   //   }
   //
   // Note the base64-encoded token name. Detokenization tools are necessary to
   // convert this to human-readable form.
   void Dump(int indent_level = 0);
   static void Dump(IntrusiveList<Group>& groups, int indent_level = 0);

   // Disallow copy and assign.
   Group(Group const&) = delete;
   void operator=(const Group&) = delete;

  private:
   // The name of this group as a token; from PW_TOKENIZE_STRING("my_group").
   Token name_;

   IntrusiveList<Metric> metrics_;
   IntrusiveList<Group> children_;
 };

 // Declare a metric, optionally adding it to a group. Use:
 //
 //   PW_METRIC(variable_name, metric_name, value)
 //   PW_METRIC(group, variable_name, metric_name, value)
 //
 // - variable_name is an identifier
 // - metric_name is a string name for the metric (will be tokenized)
 // - value must be either a floating point value (3.2f) or unsigned int (21u).
 // - group is a Group instance.
 //
 // The macro declares a variable or member named "name" with type Metric, and
 // works in three contexts: global, local, and member.
 //
 // 1. At global scope
 //
 //    PW_METRIC(foo, 15.5f);
 //
 //    void MyFunc() {
 //      foo.Increment();
 //    }
 //
 // 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 a assertion will fail. Example:
 //
 //   PW_METRIC_GROUP(my_group, "my_group_name_here");
 //   PW_METRIC(my_group, foo_, "foo", 0.2f);
 //   PW_METRIC(my_group, bar_, "bar", 44000u);
 //   PW_METRIC(my_group, zap_, "zap", 3.14f);
 //
 // NOTE: If you want a globally registered metric, see pw_metric/global.h; in
 // that contexts, metrics are globally registered without the need to centrally
 // register in a single place.
 #define PW_METRIC(...) PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_, , __VA_ARGS__)
 #define PW_METRIC_STATIC(...) \
   PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_, static, __VA_ARGS__)

 // Force conversion to uint32_t for non-float types, no matter what the
 // platform uses as the "u" suffix literal. This enables dispatching to the
 // correct TypedMetric specialization.
 #define _PW_METRIC_FLOAT_OR_UINT32(literal)                       \
   std::conditional_t<std::is_floating_point_v<decltype(literal)>, \
                      float,                                       \
                      uint32_t>

 // Case: PW_METRIC(name, initial_value)
 #define _PW_METRIC_4(static_def, variable_name, metric_name, init)            \
   static constexpr uint32_t variable_name##_token =                           \
       PW_TOKENIZE_STRING_MASK("metrics", _PW_METRIC_TOKEN_MASK, metric_name); \
   static_def ::pw::metric::TypedMetric<_PW_METRIC_FLOAT_OR_UINT32(init)>      \
       variable_name = {variable_name##_token, init}

 // Case: PW_METRIC(group, name, initial_value)
 #define _PW_METRIC_5(static_def, group, variable_name, metric_name, init)     \
   static constexpr uint32_t variable_name##_token =                           \
       PW_TOKENIZE_STRING_MASK("metrics", _PW_METRIC_TOKEN_MASK, metric_name); \
   static_def ::pw::metric::TypedMetric<_PW_METRIC_FLOAT_OR_UINT32(init)>      \
       variable_name = {variable_name##_token, init, group.metrics()}

 // Define a metric group. Works like PW_METRIC, and works in the same contexts.
 //
 // Example:
 //
 //   class MySubsystem {
 //    public:
 //     void DoSomething() {
 //       attempts.Increment();
 //       if (ActionSucceeds()) {
 //         successes.Increment();
 //       }
 //     }
 //     const Group& metrics() const { return metrics_; }
 //     Group& metrics() { return metrics_; }
 //
 //    private:
 //     PW_METRIC_GROUP(metrics_, "my_subsystem");
 //     PW_METRIC(metrics_, attempts_, "attempts", 0u);
 //     PW_METRIC(metrics_, successes_, "successes", 0u);
 //   };
 //
 #define PW_METRIC_GROUP(...) \
   PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_GROUP_, , __VA_ARGS__)
 #define PW_METRIC_GROUP_STATIC(...) \
   PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_GROUP_, static, __VA_ARGS__)

 #define _PW_METRIC_GROUP_3(static_def, variable_name, group_name) \
   static constexpr uint32_t variable_name##_token =               \
       PW_TOKENIZE_STRING_DOMAIN("metrics", group_name);           \
   static_def ::pw::metric::Group variable_name = {variable_name##_token}

 #define _PW_METRIC_GROUP_4(static_def, parent, variable_name, group_name) \
   static constexpr uint32_t variable_name##_token =                       \
       PW_TOKENIZE_STRING_DOMAIN("metrics", group_name);                   \
   static_def ::pw::metric::Group variable_name = {variable_name##_token,  \
                                                   parent.children()}

 }  // namespace pw::metric
	// Copyright 2020 The Pigweed Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License"); you may not
	// use this file except in compliance with the License. You may obtain a copy of
	// the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	// License for the specific language governing permissions and limitations under
	// the License.
	#pragma once

	#include <algorithm>
	#include <initializer_list>
	#include <limits>

	#include "pw_containers/intrusive_list.h"
	#include "pw_preprocessor/arguments.h"
	#include "pw_tokenizer/tokenize.h"

	namespace pw::metric {

	// Currently, this is for tokens, but later may be a char* when non-tokenized
	// metric names are supported.
	using tokenizer::Token;

	#define _PW_METRIC_TOKEN_MASK 0x7fffffff

	// An individual metric. There are only two supported types: uint32_t and
	// float. More complicated compound metrics can be built on these primitives.
	// See the documentation for a discussion for this design was selected.
	//
	// Size: 12 bytes / 96 bits - next, name, value.
	//
	// TODO(keir): Implement Set() and Increment() using atomics.
	// TODO(keir): Consider an alternative structure where metrics have pointers to
	// parent groups, which would enable (1) safe destruction and (2) safe static
	// initialization, but at the cost of an additional 4 bytes per metric and 4
	// bytes per group..
	class Metric : public IntrusiveList<Metric>::Item {
	public:
	Token name() const { return name_and_type_ & kTokenMask; }

	bool is_float() const { return (name_and_type_ & kTypeMask) == kTypeFloat; }
	bool is_int() const { return (name_and_type_ & kTypeMask) == kTypeInt; }

	float as_float() const;
	uint32_t as_int() const;

	// Dump a metric or metrics to logs. Level determines the indentation
	// indent_level up to a maximum of 4. Example output:
	//
	// "$FCM4qQ==": 0,
	//
	// Note the base64-encoded token name. Detokenization tools are necessary to
	// convert this to human-readable form.
	void Dump(int indent_level = 0);
	static void Dump(IntrusiveList<Metric>& metrics, int indent_level = 0);

	// Disallow copy and assign.
	Metric(Metric const&) = delete;
	void operator=(const Metric&) = delete;

	protected:
	Metric(Token name, float value)
	: name_and_type_((name & kTokenMask) \| kTypeFloat), float_(value) {}

	Metric(Token name, uint32_t value)
	: name_and_type_((name & kTokenMask) \| kTypeInt), uint_(value) {}

	Metric(Token name, float value, IntrusiveList<Metric>& metrics);
	Metric(Token name, uint32_t value, IntrusiveList<Metric>& metrics);

	// Hide mutation methods, and only offer write access through the specialized
	// TypedMetric below. This makes it impossible to call metric.Increment() on
	// a float metric at compile time.
	void Increment(uint32_t amount = 1);

	void SetInt(uint32_t value);

	void SetFloat(float value);

	private:
	// The name of this metric as a token; from PW_TOKENIZE_STRING("my_metric").
	// Last bit of the token is used to store int or float; 0 == int, 1 == float.
	Token name_and_type_;

	union {
	float float_;
	uint32_t uint_;
	};

	enum : uint32_t {
	kTokenMask = _PW_METRIC_TOKEN_MASK, // 0x7fff'ffff
	kTypeMask = 0x8000'0000,
	kTypeFloat = 0x8000'0000,
	kTypeInt = 0x0,
	};
	};

	// TypedMetric provides a type-safe wrapper the runtime-typed Metric object.
	// Note: Definition omitted to prevent accidental instantiation.
	// TODO(keir): Provide a more precise error message via static assert.
	template <typename T>
	class TypedMetric;

	// A metric for floats. Does not offer an Increment() function, since it is too
	// easy to do unsafe operations like accumulating small values in floats.
	template <>
	class TypedMetric<float> : public Metric {
	public:
	TypedMetric(Token name, float value) : Metric(name, value) {}
	TypedMetric(Token name, float value, IntrusiveList<Metric>& metrics)
	: Metric(name, value, metrics) {}

	void Set(float value) { SetFloat(value); }
	float value() const { return Metric::as_float(); }

	private:
	// Shadow these accessors to hide them on the typed version of Metric.
	float as_float() const { return 0.0; }
	uint32_t as_int() const { return 0; }
	};

	// A metric for uint32_ts. Offers both Set() and Increment().
	template <>
	class TypedMetric<uint32_t> : public Metric {
	public:
	TypedMetric(Token name, uint32_t value) : Metric(name, value) {}
	TypedMetric(Token name, uint32_t value, IntrusiveList<Metric>& metrics)
	: Metric(name, value, metrics) {}

	void Increment(uint32_t amount = 1u) { Metric::Increment(amount); }
	void Set(uint32_t value) { SetInt(value); }
	uint32_t value() const { return Metric::as_int(); }

	private:
	// Shadow these accessors to hide them on the typed version of Metric.
	float as_float() const { return 0.0; }
	uint32_t as_int() const { return 0; }
	};

	// A metric tree; consisting of children groups and leaf metrics.
	//
	// Size: 16 bytes/128 bits - next, name, metrics, children.
	class Group : public IntrusiveList<Group>::Item {
	public:
	Group(Token name);
	Group(Token name, IntrusiveList<Group>& groups);

	Token name() const { return name_; }

	void Add(Metric& metric) { metrics_.push_front(metric); }
	void Add(Group& group) { children_.push_front(group); }

	IntrusiveList<Metric>& metrics() { return metrics_; }
	IntrusiveList<Group>& children() { return children_; }

	const IntrusiveList<Metric>& metrics() const { return metrics_; }
	const IntrusiveList<Group>& children() const { return children_; }

	// Dump a metric group or groups to logs. Level determines the indentation
	// indent_level up to a maximum of 4. Example output:
	//
	// "$6doqFw==": {
	// "$05OCZw==": {
	// "$VpPfzg==": 1,
	// "$LGPMBQ==": 1.000000,
	// "$+iJvUg==": 5,
	// }
	// "$9hPNxw==": 65,
	// "$oK7HmA==": 13,
	// "$FCM4qQ==": 0,
	// }
	//
	// Note the base64-encoded token name. Detokenization tools are necessary to
	// convert this to human-readable form.
	void Dump(int indent_level = 0);
	static void Dump(IntrusiveList<Group>& groups, int indent_level = 0);

	// Disallow copy and assign.
	Group(Group const&) = delete;
	void operator=(const Group&) = delete;

	private:
	// The name of this group as a token; from PW_TOKENIZE_STRING("my_group").
	Token name_;

	IntrusiveList<Metric> metrics_;
	IntrusiveList<Group> children_;
	};

	// Declare a metric, optionally adding it to a group. Use:
	//
	// PW_METRIC(variable_name, metric_name, value)
	// PW_METRIC(group, variable_name, metric_name, value)
	//
	// - variable_name is an identifier
	// - metric_name is a string name for the metric (will be tokenized)
	// - value must be either a floating point value (3.2f) or unsigned int (21u).
	// - group is a Group instance.
	//
	// The macro declares a variable or member named "name" with type Metric, and
	// works in three contexts: global, local, and member.
	//
	// 1. At global scope
	//
	// PW_METRIC(foo, 15.5f);
	//
	// void MyFunc() {
	// foo.Increment();
	// }
	//
	// 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 a assertion will fail. Example:
	//
	// PW_METRIC_GROUP(my_group, "my_group_name_here");
	// PW_METRIC(my_group, foo_, "foo", 0.2f);
	// PW_METRIC(my_group, bar_, "bar", 44000u);
	// PW_METRIC(my_group, zap_, "zap", 3.14f);
	//
	// NOTE: If you want a globally registered metric, see pw_metric/global.h; in
	// that contexts, metrics are globally registered without the need to centrally
	// register in a single place.
	#define PW_METRIC(...) PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_, , __VA_ARGS__)
	#define PW_METRIC_STATIC(...) \
	PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_, static, __VA_ARGS__)

	// Force conversion to uint32_t for non-float types, no matter what the
	// platform uses as the "u" suffix literal. This enables dispatching to the
	// correct TypedMetric specialization.
	#define _PW_METRIC_FLOAT_OR_UINT32(literal) \
	std::conditional_t<std::is_floating_point_v<decltype(literal)>, \
	float, \
	uint32_t>

	// Case: PW_METRIC(name, initial_value)
	#define _PW_METRIC_4(static_def, variable_name, metric_name, init) \
	static constexpr uint32_t variable_name##_token = \
	PW_TOKENIZE_STRING_MASK("metrics", _PW_METRIC_TOKEN_MASK, metric_name); \
	static_def ::pw::metric::TypedMetric<_PW_METRIC_FLOAT_OR_UINT32(init)> \
	variable_name = {variable_name##_token, init}

	// Case: PW_METRIC(group, name, initial_value)
	#define _PW_METRIC_5(static_def, group, variable_name, metric_name, init) \
	static constexpr uint32_t variable_name##_token = \
	PW_TOKENIZE_STRING_MASK("metrics", _PW_METRIC_TOKEN_MASK, metric_name); \
	static_def ::pw::metric::TypedMetric<_PW_METRIC_FLOAT_OR_UINT32(init)> \
	variable_name = {variable_name##_token, init, group.metrics()}

	// Define a metric group. Works like PW_METRIC, and works in the same contexts.
	//
	// Example:
	//
	// class MySubsystem {
	// public:
	// void DoSomething() {
	// attempts.Increment();
	// if (ActionSucceeds()) {
	// successes.Increment();
	// }
	// }
	// const Group& metrics() const { return metrics_; }
	// Group& metrics() { return metrics_; }
	//
	// private:
	// PW_METRIC_GROUP(metrics_, "my_subsystem");
	// PW_METRIC(metrics_, attempts_, "attempts", 0u);
	// PW_METRIC(metrics_, successes_, "successes", 0u);
	// };
	//
	#define PW_METRIC_GROUP(...) \
	PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_GROUP_, , __VA_ARGS__)
	#define PW_METRIC_GROUP_STATIC(...) \
	PW_DELEGATE_BY_ARG_COUNT(_PW_METRIC_GROUP_, static, __VA_ARGS__)

	#define _PW_METRIC_GROUP_3(static_def, variable_name, group_name) \
	static constexpr uint32_t variable_name##_token = \
	PW_TOKENIZE_STRING_DOMAIN("metrics", group_name); \
	static_def ::pw::metric::Group variable_name = {variable_name##_token}

	#define _PW_METRIC_GROUP_4(static_def, parent, variable_name, group_name) \
	static constexpr uint32_t variable_name##_token = \
	PW_TOKENIZE_STRING_DOMAIN("metrics", group_name); \
	static_def ::pw::metric::Group variable_name = {variable_name##_token, \
	parent.children()}

	} // namespace pw::metric