API Namespace metric

来源：互联网发布：廖雪峰java 编辑：程序博客网时间：2024/06/06 07:45

原文链接：https://github.com/Microsoft/napajs/blob/master/docs/api/metric.md

Namespace metric

Introduction
C++ API
- Interface Metric
- Interface MetricProvider
- Function MetricProvider& GetMetricProvider()
JavaScript API
- Enum MetricType
- Class Metric
  - set(value: number, dimensions?: string[]): void
  - increment(dimensions?: string[]): void;
  - decrement(dimensions?: string[]): void;
- Function get(section: string, name: string, type: MetricType, dimensionNames: string[])
Using custom metric providers
Developing custom metric providers

介绍

与日志类似，metric是创建可监听服务的必要条件。通过Metric API，开发者在JavaScript和C++（addon）里都可以使用他们自己定义的metric系统。一个metric有它的标识，包括如下信息：

Section：metric的组或分类
Name：metric的名字。在系统中Section/Name的联合使用必须是唯一的。
Type：metric的类型，类型可以是：
- Number（数字）：一个纯数字，例如PrivateBytes
- Rate（频率）：带有量词的数字，例如QueryPerSecond
- Percentile（百分比）：一个需要按百分制化简的纯数字，例如SuccessLatency
Dimensions（维度）：一个metric有多个维度，每个维度在运行时绑定一个字符串值。例如：IncomingRequestRate 有两个维度：['client-id', 'request-type']。

Metrics是进程知晓的（process-wise）对象，能跨zone使用。

C++ API

Interface Metric （Metric 接口）

 /// <summary> Enumeration of metric type. </summary>    enum class MetricType {        Number = 0,        Rate,        Percentile,    };    /// <summary> Interface to represents a multi-dimensional metric with a maximum dimensionality of 64. </summary>    class Metric {    public:        /// <summary> Sets a metric value with variadic dimension arguments. </summary>        /// <param name="value"> Int64 value. </param>        /// <param name="numberOfDimensions"> Number of dimensions being set. </param>        /// <param name="dimensionValues"> Array of dimension value names. </param>        /// <returns> Success/Fail. </returns>        /// <remarks>        ///     The number of dimension values must exactly match the number of dimensions provided when        ///     creating this metric.        /// </remarks>        virtual bool Set(int64_t value, size_t numberOfDimensions, const char* dimensionValues[]) = 0;        /// <summary>        ///     Increments a metric value with variadic dimension arguments.        ///     Use mainly to simplify rate counters.        /// </summary>        /// <param name="value"> UInt64 value to increment. </param>        /// <param name="numberOfDimensions"> Number of dimensions being set. </param>        /// <param name="dimensionValues"> Array of dimension value names. </param>        /// <returns> Success/Fail. </returns>        /// <remarks>        ///     The number of dimension values must exactly match the number of dimensions        ///     provided when creating this metric.        /// </remarks>        virtual bool Increment(uint64_t value, size_t numberOfDimensions, const char* dimensionValues[]) = 0;        /// <summary>        ///     Decrements metric value with variadic dimension arguments.        ///     Use mainly to simplify rate counters.        /// </summary>        /// <param name="value"> UInt64 value to decrement. </param>        /// <param name="numberOfDimensions"> Number of dimensions being set. </param>        /// <param name="dimensionValues"> Array of dimension value names. </param>        /// <returns> Success/Fail. </returns>        /// <remarks>        ///     The number of dimension values must exactly match the number of dimensions        ///     provided when creating this metric.        /// </remarks>        virtual bool Decrement(uint64_t value, size_t numberOfDimensions, const char* dimensionValues[]) = 0;        /// <summary> Explicitly destroys the Metric. </summary>        /// <remarks>        ///     Consumers are not required to call this.        ///     The MetricProvider owns this class and will automatically perform cleanup on shutdown.        /// </remarks>        virtual void Destroy() = 0;    protected:        ///<summary> Prevent calling delete on the interface. Must use Destroy! </summary>        virtual ~Metric() = default;    };

Interface MetricProvider（MetricProvider 接口）

    /// <summary> Interface for a generic metric provider. </summary>    /// <remarks>     ///     Ownership of this metric provider belongs to the shared library which created it. Hence the explicit    ///     Destroy method in this class. To simplify memory management across multiple shared libraries, this class    ///     can only be created via a factory method provided by the shared library. When it is no longer needed,    ///     the caller may call Destroy() which will tell the shared library which created it to dispose of the object.    /// </remarks>    class MetricProvider {    public:        /// <summary>        ///     Gets or creates a N-dimensional metric. Metric objects are owned and cached by this class.        ///     Up to 64 dimensions may be used.</summary>        /// <param name="section"> Section of the metric.</param>        /// <param name="name"> Name of the metric.</param>        /// <param name="type"> Type of the metric.</param>        /// <param name="dimensions">        ///     Number of dimensions requested for this metric.        ///     Represents the size of the array passed in for p_dimensionNames.        /// </param>        /// <param name="dimensionNames"> Array of dimension names being requested for this metric.</param>        /// <remarks>        ///     The IMetric class returned is owned and cached by this class.        ///     Callers are not required to call destroy() on the Metric.        /// </remarks>        virtual Metric* GetMetric(            const char* section,            const char* name,            MetricType type,            size_t dimensions,            const char* dimensionNames[]) = 0;        ///<summary> Explicitly destroys the metric provider. </summary>        virtual void Destroy() = 0;    protected:        ///<summary> Prevent calling delete on the interface. Must use Destroy! </summary>        virtual ~MetricProvider() = default;    };

function MetricProvider& GetMetricProvider()

/// <summary> Exports a getter function for retrieves the configured metric provider. </summary>NAPA_API MetricProvider& GetMetricProvider();

JavaScript API

enum MetricType

export enum MetricType {    Number = 0,    Rate,    Percentile,

Class Metric

JavaScript中操作metric的类。

set(value: number, dimensions?: string[]): void

给被维度值限制的metric实例赋值。例如：

// Create a percentile metric to measure end-to-end latency, with 1 dimension of client-id.// 创建百分比的metric测试端到端延迟，带有client-id维度。latency = napa.metric.get(    'app1',    'end-to-end-latency',    napa.metric.MetricType.Percentile,     ['client-id']);// Set end-to-end latency of current request to 100, with client-id 'client1'.//给client-id为client1的实例赋值当前请求的端到端的延迟为100。latency.set(100, ['client1']);

increment(dimensions?: string[]): void

给受维度值约束的metric实例的增加值。

Example:

// Create a percentile metric to measure end-to-end latency, with 1 dimension of client-id.latency = napa.metric.get(    'app1',    'qps',    napa.metric.MetricType.Rate,     ['client-id']);// Increment QPS of client-id 'client1'.latency.increment(['client1']);

decrement(dimensions?: string[]): void

给受维度值约束的metric实例的减值。

function get(section: string, name: string, type: MetricType, dimensions: string[] = []): Metric

创建一个metric，包含section、name、type和维度。如果所给参数的metric已经存在，则其返回。