Line data Source code
1 : // Copyright The OpenTelemetry Authors
2 : // SPDX-License-Identifier: Apache-2.0
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 sum only increases over time, like a Counter. A
132 : /// non-monotonic sum can increase and decrease, like an UpDownCounter.
133 : /// Exporters treat a null value as non-monotonic.
134 : final bool? isMonotonic;
135 :
136 : /// Creates a new Metric instance.
137 : ///
138 : /// @param name The name of the metric
139 : /// @param description Optional description of what the metric measures
140 : /// @param unit Optional unit of measurement (e.g., "ms", "bytes")
141 : /// @param type The type of metric (sum, gauge, or histogram)
142 : /// @param temporality The aggregation temporality (cumulative or delta)
143 : /// @param instrumentationScope Optional scope that created this metric
144 : /// @param points The data points for this metric
145 : /// @param isMonotonic Whether the metric is monotonic (for sum metrics only)
146 37 : Metric({
147 : required this.name,
148 : this.description,
149 : this.unit,
150 : required this.type,
151 : this.temporality = AggregationTemporality.cumulative,
152 : this.instrumentationScope,
153 : required this.points,
154 : this.isMonotonic,
155 : });
156 :
157 : /// Creates a sum metric.
158 : ///
159 : /// Sum metrics represent values that accumulate over time, such as
160 : /// request counts, bytes sent, or errors encountered.
161 : ///
162 : /// @param name The name of the metric
163 : /// @param description Optional description of what the metric measures
164 : /// @param unit Optional unit of measurement (e.g., "requests", "bytes")
165 : /// @param points The data points for this metric
166 : /// @param temporality The aggregation temporality (default: cumulative)
167 : /// @param instrumentationScope Optional scope that created this metric
168 : /// @param isMonotonic Whether the sum can only increase (default: true)
169 : /// @return A new sum metric
170 20 : factory Metric.sum({
171 : required String name,
172 : String? description,
173 : String? unit,
174 : required List<MetricPoint<dynamic>> points,
175 : AggregationTemporality temporality = AggregationTemporality.cumulative,
176 : InstrumentationScope? instrumentationScope,
177 : bool isMonotonic = true,
178 : }) {
179 20 : return Metric(
180 : name: name,
181 : description: description,
182 : unit: unit,
183 : type: MetricType.sum,
184 : temporality: temporality,
185 : instrumentationScope: instrumentationScope,
186 : points: points,
187 : isMonotonic: isMonotonic,
188 : );
189 : }
190 :
191 : /// Creates a gauge metric.
192 : ///
193 : /// Gauge metrics represent current values that can go up and down,
194 : /// such as CPU usage, memory usage, or queue size.
195 : ///
196 : /// @param name The name of the metric
197 : /// @param description Optional description of what the metric measures
198 : /// @param unit Optional unit of measurement (e.g., "percent", "bytes")
199 : /// @param points The data points for this metric
200 : /// @param instrumentationScope Optional scope that created this metric
201 : /// @return A new gauge metric
202 10 : factory Metric.gauge({
203 : required String name,
204 : String? description,
205 : String? unit,
206 : required List<MetricPoint<dynamic>> points,
207 : InstrumentationScope? instrumentationScope,
208 : }) {
209 10 : return Metric(
210 : name: name,
211 : description: description,
212 : unit: unit,
213 : type: MetricType.gauge,
214 : temporality:
215 : AggregationTemporality.cumulative, // Gauges are always cumulative
216 : instrumentationScope: instrumentationScope,
217 : points: points,
218 : );
219 : }
220 :
221 : /// Creates a histogram metric.
222 : ///
223 : /// Histogram metrics represent distributions of values, such as
224 : /// request durations, response sizes, or latencies.
225 : ///
226 : /// @param name The name of the metric
227 : /// @param description Optional description of what the metric measures
228 : /// @param unit Optional unit of measurement (e.g., "ms", "bytes")
229 : /// @param points The data points for this metric
230 : /// @param temporality The aggregation temporality (default: cumulative)
231 : /// @param instrumentationScope Optional scope that created this metric
232 : /// @return A new histogram metric
233 2 : factory Metric.histogram({
234 : required String name,
235 : String? description,
236 : String? unit,
237 : required List<MetricPoint<dynamic>> points,
238 : AggregationTemporality temporality = AggregationTemporality.cumulative,
239 : InstrumentationScope? instrumentationScope,
240 : }) {
241 2 : return Metric(
242 : name: name,
243 : description: description,
244 : unit: unit,
245 : type: MetricType.histogram,
246 : temporality: temporality,
247 : instrumentationScope: instrumentationScope,
248 : points: points,
249 : );
250 : }
251 : }
|
