Line data Source code
1 : // Licensed under the Apache License, Version 2.0
2 : // Copyright 2025, Michael Bushe, All rights reserved.
3 :
4 : import 'package:dartastic_opentelemetry_api/dartastic_opentelemetry_api.dart';
5 : import 'metric_point.dart';
6 :
7 : /// Defines the kind of metric point.
8 : ///
9 : /// This enumeration represents the different types of metric data points
10 : /// as defined in the OpenTelemetry metrics data model.
11 : ///
12 : /// More information:
13 : /// https://opentelemetry.io/docs/specs/otel/metrics/data-model/
14 : enum MetricPointKind {
15 : /// Sum represents a cumulative or delta sum.
16 : ///
17 : /// Sum points record a running total of a value that increases or decreases over time.
18 : sum,
19 :
20 : /// Gauge represents the last value.
21 : ///
22 : /// Gauge points record the instantaneous value of a measurement at a specific time.
23 : gauge,
24 :
25 : /// Histogram represents a distribution of values.
26 : ///
27 : /// Histogram points record a statistical distribution of values, with count, sum,
28 : /// and frequency counts for different bucket ranges.
29 : histogram,
30 :
31 : /// ExponentialHistogram represents a distribution of values using
32 : /// exponential scale bucket boundaries.
33 : ///
34 : /// This is a more efficient representation of histograms for high-cardinality data.
35 : exponentialHistogram,
36 : }
37 :
38 : /// Defines the type of metric.
39 : ///
40 : /// This enumeration represents the different types of metrics
41 : /// that can be collected and exported.
42 : ///
43 : /// More information:
44 : /// https://opentelemetry.io/docs/specs/otel/metrics/data-model/#metric-points
45 : enum MetricType {
46 : /// Sum represents a cumulative or delta sum.
47 : ///
48 : /// Sum metrics accumulate values over time and are used for counters.
49 : sum,
50 :
51 : /// Gauge represents the last value.
52 : ///
53 : /// Gauge metrics record the current value at a specific time.
54 : gauge,
55 :
56 : /// Histogram represents a distribution of values.
57 : ///
58 : /// Histogram metrics record statistical distributions of values.
59 : histogram,
60 : }
61 :
62 : /// Defines the aggregation temporality of a metric.
63 : ///
64 : /// Aggregation temporality defines how metrics are aggregated over time.
65 : ///
66 : /// More information:
67 : /// https://opentelemetry.io/docs/specs/otel/metrics/data-model/#temporality
68 : enum AggregationTemporality {
69 : /// Cumulative aggregation reports the total sum since the start.
70 : ///
71 : /// Cumulative temporality means that each data point contains the total sum
72 : /// of all measurements since the start time.
73 : cumulative,
74 :
75 : /// Delta aggregation reports the change since the last measurement.
76 : ///
77 : /// Delta temporality means that each data point contains only the change
78 : /// since the last reported measurement.
79 : delta,
80 : }
81 :
82 : /// Metric represents a named collection of data points.
83 : ///
84 : /// A Metric is a collection of data points that share the same name, description,
85 : /// unit, and other metadata. It is the fundamental unit of telemetry that is
86 : /// exported to backends.
87 : ///
88 : /// More information:
89 : /// https://opentelemetry.io/docs/specs/otel/metrics/data-model/#metric
90 : class Metric {
91 : /// The name of the metric.
92 : ///
93 : /// This should be unique within the instrumentation scope and should follow
94 : /// the naming convention recommended by OpenTelemetry.
95 : final String name;
96 :
97 : /// The description of the metric.
98 : ///
99 : /// A human-readable description of what the metric measures.
100 : final String? description;
101 :
102 : /// The unit of the metric.
103 : ///
104 : /// The unit of measure for the metric values. Should follow
105 : /// the UCUM convention where possible (e.g., "ms", "bytes").
106 : final String? unit;
107 :
108 : /// The kind of metric.
109 : ///
110 : /// Defines whether this metric is a Sum, Gauge, or Histogram.
111 : final MetricType type;
112 :
113 : /// The aggregation temporality of the metric.
114 : ///
115 : /// Defines whether the metric values are cumulative or delta.
116 : final AggregationTemporality temporality;
117 :
118 : /// The instrumentation scope that created this metric.
119 : ///
120 : /// Identifies the library or component that created this metric.
121 : final InstrumentationScope? instrumentationScope;
122 :
123 : /// The data points for this metric.
124 : ///
125 : /// Each data point contains a set of attributes, a value or values,
126 : /// and timestamps.
127 : final List<MetricPoint<dynamic>> points;
128 :
129 : /// Whether this metric is monotonic (sum metrics only).
130 : ///
131 : /// A monotonic metric only increases or only decreases over time.
132 : /// This is applicable only for sum metrics.
133 : final bool? isMonotonic;
134 :
135 : /// Creates a new Metric instance.
136 : ///
137 : /// @param name The name of the metric
138 : /// @param description Optional description of what the metric measures
139 : /// @param unit Optional unit of measurement (e.g., "ms", "bytes")
140 : /// @param type The type of metric (sum, gauge, or histogram)
141 : /// @param temporality The aggregation temporality (cumulative or delta)
142 : /// @param instrumentationScope Optional scope that created this metric
143 : /// @param points The data points for this metric
144 : /// @param isMonotonic Whether the metric is monotonic (for sum metrics only)
145 16 : Metric({
146 : required this.name,
147 : this.description,
148 : this.unit,
149 : required this.type,
150 : this.temporality = AggregationTemporality.cumulative,
151 : this.instrumentationScope,
152 : required this.points,
153 : this.isMonotonic,
154 : });
155 :
156 : /// Creates a sum metric.
157 : ///
158 : /// Sum metrics represent values that accumulate over time, such as
159 : /// request counts, bytes sent, or errors encountered.
160 : ///
161 : /// @param name The name of the metric
162 : /// @param description Optional description of what the metric measures
163 : /// @param unit Optional unit of measurement (e.g., "requests", "bytes")
164 : /// @param points The data points for this metric
165 : /// @param temporality The aggregation temporality (default: cumulative)
166 : /// @param instrumentationScope Optional scope that created this metric
167 : /// @param isMonotonic Whether the sum can only increase (default: true)
168 : /// @return A new sum metric
169 3 : factory Metric.sum({
170 : required String name,
171 : String? description,
172 : String? unit,
173 : required List<MetricPoint<dynamic>> points,
174 : AggregationTemporality temporality = AggregationTemporality.cumulative,
175 : InstrumentationScope? instrumentationScope,
176 : bool isMonotonic = true,
177 : }) {
178 3 : return Metric(
179 : name: name,
180 : description: description,
181 : unit: unit,
182 : type: MetricType.sum,
183 : temporality: temporality,
184 : instrumentationScope: instrumentationScope,
185 : points: points,
186 : isMonotonic: isMonotonic,
187 : );
188 : }
189 :
190 : /// Creates a gauge metric.
191 : ///
192 : /// Gauge metrics represent current values that can go up and down,
193 : /// such as CPU usage, memory usage, or queue size.
194 : ///
195 : /// @param name The name of the metric
196 : /// @param description Optional description of what the metric measures
197 : /// @param unit Optional unit of measurement (e.g., "percent", "bytes")
198 : /// @param points The data points for this metric
199 : /// @param instrumentationScope Optional scope that created this metric
200 : /// @return A new gauge metric
201 1 : factory Metric.gauge({
202 : required String name,
203 : String? description,
204 : String? unit,
205 : required List<MetricPoint<dynamic>> points,
206 : InstrumentationScope? instrumentationScope,
207 : }) {
208 1 : return Metric(
209 : name: name,
210 : description: description,
211 : unit: unit,
212 : type: MetricType.gauge,
213 : temporality:
214 : AggregationTemporality.cumulative, // Gauges are always cumulative
215 : instrumentationScope: instrumentationScope,
216 : points: points,
217 : );
218 : }
219 :
220 : /// Creates a histogram metric.
221 : ///
222 : /// Histogram metrics represent distributions of values, such as
223 : /// request durations, response sizes, or latencies.
224 : ///
225 : /// @param name The name of the metric
226 : /// @param description Optional description of what the metric measures
227 : /// @param unit Optional unit of measurement (e.g., "ms", "bytes")
228 : /// @param points The data points for this metric
229 : /// @param temporality The aggregation temporality (default: cumulative)
230 : /// @param instrumentationScope Optional scope that created this metric
231 : /// @return A new histogram metric
232 0 : factory Metric.histogram({
233 : required String name,
234 : String? description,
235 : String? unit,
236 : required List<MetricPoint<dynamic>> points,
237 : AggregationTemporality temporality = AggregationTemporality.cumulative,
238 : InstrumentationScope? instrumentationScope,
239 : }) {
240 0 : return Metric(
241 : name: name,
242 : description: description,
243 : unit: unit,
244 : type: MetricType.histogram,
245 : temporality: temporality,
246 : instrumentationScope: instrumentationScope,
247 : points: points,
248 : );
249 : }
250 : }
|
