trpc.group/trpc-go/trpc-go@v1.0.3/metrics/sink.go (about)

     1  //
     2  //
     3  // Tencent is pleased to support the open source community by making tRPC available.
     4  //
     5  // Copyright (C) 2023 THL A29 Limited, a Tencent company.
     6  // All rights reserved.
     7  //
     8  // If you have downloaded a copy of the tRPC source code from Tencent,
     9  // please note that tRPC source code is licensed under the  Apache 2.0 License,
    10  // A copy of the Apache 2.0 License is included in this file.
    11  //
    12  //
    13  
    14  package metrics
    15  
    16  // Policy is the metrics aggregation policy.
    17  type Policy int
    18  
    19  // All available Policy(s).
    20  const (
    21  	PolicyNONE      = 0 // Undefined
    22  	PolicySET       = 1 // instantaneous value
    23  	PolicySUM       = 2 // summary
    24  	PolicyAVG       = 3 // average
    25  	PolicyMAX       = 4 // maximum
    26  	PolicyMIN       = 5 // minimum
    27  	PolicyMID       = 6 // median
    28  	PolicyTimer     = 7 // timer
    29  	PolicyHistogram = 8 // histogram
    30  )
    31  
    32  // Sink defines the interface an external monitor system should provide.
    33  type Sink interface {
    34  	// Name returns the name of the monitor system.
    35  	Name() string
    36  	// Report reports a record to monitor system.
    37  	Report(rec Record, opts ...Option) error
    38  }
    39  
    40  // Record is the single record.
    41  //
    42  // terminologies:
    43  //   - dimension name
    44  //     is an attribute of a data, often used to filter data, such as a photo album business module
    45  //     includes region and server room.
    46  //   - dimension value
    47  //     refines the dimension. For example, the regions of the album business module include Shenzhen,
    48  //     Shanghai, etc., the region is the dimension, and Shenzhen and Shanghai are the dimension
    49  //     values.
    50  //   - metric
    51  //     is a measurement, used to aggregate and calculate. For example, request count of album business
    52  //     module in ShenZhen Telecom is a metric.
    53  type Record struct {
    54  	Name string // the name of the record
    55  	// dimension name: such as region, host and disk number.
    56  	// dimension value: such as region=ShangHai.
    57  	dimensions []*Dimension
    58  	metrics    []*Metrics
    59  }
    60  
    61  // Dimension defines the dimension.
    62  type Dimension struct {
    63  	Name  string
    64  	Value string
    65  }
    66  
    67  // GetName returns the record name.
    68  func (r *Record) GetName() string {
    69  	return r.Name
    70  }
    71  
    72  // GetDimensions returns dimensions.
    73  func (r *Record) GetDimensions() []*Dimension {
    74  	if r == nil {
    75  		return nil
    76  	}
    77  	return r.dimensions
    78  }
    79  
    80  // GetMetrics returns metrics.
    81  func (r *Record) GetMetrics() []*Metrics {
    82  	if r == nil {
    83  		return nil
    84  	}
    85  	return r.metrics
    86  }
    87  
    88  // NewSingleDimensionMetrics creates a Record with no dimension and only one metric.
    89  func NewSingleDimensionMetrics(name string, value float64, policy Policy) Record {
    90  	return Record{
    91  		dimensions: nil,
    92  		metrics: []*Metrics{
    93  			{name: name, value: value, policy: policy},
    94  		},
    95  	}
    96  }
    97  
    98  // ReportSingleDimensionMetrics creates and reports a Record with no dimension and only one metric.
    99  func ReportSingleDimensionMetrics(name string, value float64, policy Policy, opts ...Option) error {
   100  	return Report(Record{
   101  		dimensions: nil,
   102  		metrics: []*Metrics{
   103  			{name: name, value: value, policy: policy},
   104  		},
   105  	}, opts...)
   106  }
   107  
   108  // NewMultiDimensionMetricsX creates a named Record with multiple dimensions and metrics.
   109  func NewMultiDimensionMetricsX(name string, dimensions []*Dimension, metrics []*Metrics) Record {
   110  	return Record{
   111  		Name:       name,
   112  		dimensions: dimensions,
   113  		metrics:    metrics,
   114  	}
   115  }
   116  
   117  // ReportMultiDimensionMetricsX creates and reports a named Record with multiple dimensions and
   118  // metrics.
   119  func ReportMultiDimensionMetricsX(
   120  	name string,
   121  	dimensions []*Dimension,
   122  	metrics []*Metrics,
   123  	opts ...Option,
   124  ) error {
   125  	return Report(Record{
   126  		Name:       name,
   127  		dimensions: dimensions,
   128  		metrics:    metrics,
   129  	}, opts...)
   130  }
   131  
   132  // Metrics defines the metric.
   133  type Metrics struct {
   134  	name   string  // metric name
   135  	value  float64 // metric value
   136  	policy Policy  // aggregation policy
   137  }
   138  
   139  // NewMetrics creates a new Metrics.
   140  func NewMetrics(name string, value float64, policy Policy) *Metrics {
   141  	return &Metrics{name, value, policy}
   142  }
   143  
   144  // Name returns the metrics name.
   145  func (m *Metrics) Name() string {
   146  	if m == nil {
   147  		return ""
   148  	}
   149  	return m.name
   150  }
   151  
   152  // Value returns the metrics value.
   153  func (m *Metrics) Value() float64 {
   154  	if m == nil {
   155  		return 0
   156  	}
   157  	return m.value
   158  }
   159  
   160  // Policy returns the metrics policy.
   161  func (m *Metrics) Policy() Policy {
   162  	if m == nil {
   163  		return PolicyNONE
   164  	}
   165  	return m.policy
   166  }