Debian Codegraph @

semconv/v1.32.0/cicdconv/metric.go

raw
1 // Code generated from semantic convention specification. DO NOT EDIT.
2
3 // Copyright The OpenTelemetry Authors
4 // SPDX-License-Identifier: Apache-2.0
5
6 // Package cicdconv provides types and functionality for OpenTelemetry semantic
7 // conventions in the "cicd" namespace.
8 package cicdconv
9
10 import (
11 "context"
12 "sync"
13
14 "go.opentelemetry.io/otel/attribute"
15 "go.opentelemetry.io/otel/metric"
16 "go.opentelemetry.io/otel/metric/noop"
17 )
18
19 var (
20 addOptPool = &sync.Pool{New: func() any { return &[]metric.AddOption{} }}
21 recOptPool = &sync.Pool{New: func() any { return &[]metric.RecordOption{} }}
22 )
23
24 // PipelineResultAttr is an attribute conforming to the cicd.pipeline.result
25 // semantic conventions. It represents the result of a pipeline run.
26 type PipelineResultAttr string
27
28 var (
29 // PipelineResultSuccess is the pipeline run finished successfully.
30 PipelineResultSuccess PipelineResultAttr = "success"
31 // PipelineResultFailure is the pipeline run did not finish successfully, eg.
32 // due to a compile error or a failing test. Such failures are usually detected
33 // by non-zero exit codes of the tools executed in the pipeline run.
34 PipelineResultFailure PipelineResultAttr = "failure"
35 // PipelineResultError is the pipeline run failed due to an error in the CICD
36 // system, eg. due to the worker being killed.
37 PipelineResultError PipelineResultAttr = "error"
38 // PipelineResultTimeout is a timeout caused the pipeline run to be interrupted.
39 PipelineResultTimeout PipelineResultAttr = "timeout"
40 // PipelineResultCancellation is the pipeline run was cancelled, eg. by a user
41 // manually cancelling the pipeline run.
42 PipelineResultCancellation PipelineResultAttr = "cancellation"
43 // PipelineResultSkip is the pipeline run was skipped, eg. due to a precondition
44 // not being met.
45 PipelineResultSkip PipelineResultAttr = "skip"
46 )
47
48 // PipelineRunStateAttr is an attribute conforming to the cicd.pipeline.run.state
49 // semantic conventions. It represents the pipeline run goes through these states
50 // during its lifecycle.
51 type PipelineRunStateAttr string
52
53 var (
54 // PipelineRunStatePending is the run pending state spans from the event
55 // triggering the pipeline run until the execution of the run starts (eg. time
56 // spent in a queue, provisioning agents, creating run resources).
57 PipelineRunStatePending PipelineRunStateAttr = "pending"
58 // PipelineRunStateExecuting is the executing state spans the execution of any
59 // run tasks (eg. build, test).
60 PipelineRunStateExecuting PipelineRunStateAttr = "executing"
61 // PipelineRunStateFinalizing is the finalizing state spans from when the run
62 // has finished executing (eg. cleanup of run resources).
63 PipelineRunStateFinalizing PipelineRunStateAttr = "finalizing"
64 )
65
66 // WorkerStateAttr is an attribute conforming to the cicd.worker.state semantic
67 // conventions. It represents the state of a CICD worker / agent.
68 type WorkerStateAttr string
69
70 var (
71 // WorkerStateAvailable is the worker is not performing work for the CICD
72 // system. It is available to the CICD system to perform work on (online /
73 // idle).
74 WorkerStateAvailable WorkerStateAttr = "available"
75 // WorkerStateBusy is the worker is performing work for the CICD system.
76 WorkerStateBusy WorkerStateAttr = "busy"
77 // WorkerStateOffline is the worker is not available to the CICD system
78 // (disconnected / down).
79 WorkerStateOffline WorkerStateAttr = "offline"
80 )
81
82 // ErrorTypeAttr is an attribute conforming to the error.type semantic
83 // conventions. It represents the describes a class of error the operation ended
84 // with.
85 type ErrorTypeAttr string
86
87 var (
88 // ErrorTypeOther is a fallback error value to be used when the instrumentation
89 // doesn't define a custom value.
90 ErrorTypeOther ErrorTypeAttr = "_OTHER"
91 )
92
93 // PipelineRunActive is an instrument used to record metric values conforming to
94 // the "cicd.pipeline.run.active" semantic conventions. It represents the number
95 // of pipeline runs currently active in the system by state.
96 type PipelineRunActive struct {
97 metric.Int64UpDownCounter
98 }
99
100 // NewPipelineRunActive returns a new PipelineRunActive instrument.
101 func NewPipelineRunActive(
102 m metric.Meter,
103 opt ...metric.Int64UpDownCounterOption,
104 ) (PipelineRunActive, error) {
105 // Check if the meter is nil.
106 if m == nil {
107 return PipelineRunActive{noop.Int64UpDownCounter{}}, nil
108 }
109
110 i, err := m.Int64UpDownCounter(
111 "cicd.pipeline.run.active",
112 append([]metric.Int64UpDownCounterOption{
113 metric.WithDescription("The number of pipeline runs currently active in the system by state."),
114 metric.WithUnit("{run}"),
115 }, opt...)...,
116 )
117 if err != nil {
118 return PipelineRunActive{noop.Int64UpDownCounter{}}, err
119 }
120 return PipelineRunActive{i}, nil
121 }
122
123 // Inst returns the underlying metric instrument.
124 func (m PipelineRunActive) Inst() metric.Int64UpDownCounter {
125 return m.Int64UpDownCounter
126 }
127
128 // Name returns the semantic convention name of the instrument.
129 func (PipelineRunActive) Name() string {
130 return "cicd.pipeline.run.active"
131 }
132
133 // Unit returns the semantic convention unit of the instrument
134 func (PipelineRunActive) Unit() string {
135 return "{run}"
136 }
137
138 // Description returns the semantic convention description of the instrument
139 func (PipelineRunActive) Description() string {
140 return "The number of pipeline runs currently active in the system by state."
141 }
142
143 // Add adds incr to the existing count.
144 //
145 // The pipelineName is the the human readable name of the pipeline within a CI/CD
146 // system.
147 //
148 // The pipelineRunState is the the pipeline run goes through these states during
149 // its lifecycle.
150 func (m PipelineRunActive) Add(
151 ctx context.Context,
152 incr int64,
153 pipelineName string,
154 pipelineRunState PipelineRunStateAttr,
155 attrs ...attribute.KeyValue,
156 ) {
157 o := addOptPool.Get().(*[]metric.AddOption)
158 defer func() {
159 *o = (*o)[:0]
160 addOptPool.Put(o)
161 }()
162
163 *o = append(
164 *o,
165 metric.WithAttributes(
166 append(
167 attrs,
168 attribute.String("cicd.pipeline.name", pipelineName),
169 attribute.String("cicd.pipeline.run.state", string(pipelineRunState)),
170 )...,
171 ),
172 )
173
174 m.Int64UpDownCounter.Add(ctx, incr, *o...)
175 }
176
177 // PipelineRunDuration is an instrument used to record metric values conforming
178 // to the "cicd.pipeline.run.duration" semantic conventions. It represents the
179 // duration of a pipeline run grouped by pipeline, state and result.
180 type PipelineRunDuration struct {
181 metric.Float64Histogram
182 }
183
184 // NewPipelineRunDuration returns a new PipelineRunDuration instrument.
185 func NewPipelineRunDuration(
186 m metric.Meter,
187 opt ...metric.Float64HistogramOption,
188 ) (PipelineRunDuration, error) {
189 // Check if the meter is nil.
190 if m == nil {
191 return PipelineRunDuration{noop.Float64Histogram{}}, nil
192 }
193
194 i, err := m.Float64Histogram(
195 "cicd.pipeline.run.duration",
196 append([]metric.Float64HistogramOption{
197 metric.WithDescription("Duration of a pipeline run grouped by pipeline, state and result."),
198 metric.WithUnit("s"),
199 }, opt...)...,
200 )
201 if err != nil {
202 return PipelineRunDuration{noop.Float64Histogram{}}, err
203 }
204 return PipelineRunDuration{i}, nil
205 }
206
207 // Inst returns the underlying metric instrument.
208 func (m PipelineRunDuration) Inst() metric.Float64Histogram {
209 return m.Float64Histogram
210 }
211
212 // Name returns the semantic convention name of the instrument.
213 func (PipelineRunDuration) Name() string {
214 return "cicd.pipeline.run.duration"
215 }
216
217 // Unit returns the semantic convention unit of the instrument
218 func (PipelineRunDuration) Unit() string {
219 return "s"
220 }
221
222 // Description returns the semantic convention description of the instrument
223 func (PipelineRunDuration) Description() string {
224 return "Duration of a pipeline run grouped by pipeline, state and result."
225 }
226
227 // Record records val to the current distribution.
228 //
229 // The pipelineName is the the human readable name of the pipeline within a CI/CD
230 // system.
231 //
232 // The pipelineRunState is the the pipeline run goes through these states during
233 // its lifecycle.
234 //
235 // All additional attrs passed are included in the recorded value.
236 func (m PipelineRunDuration) Record(
237 ctx context.Context,
238 val float64,
239 pipelineName string,
240 pipelineRunState PipelineRunStateAttr,
241 attrs ...attribute.KeyValue,
242 ) {
243 o := recOptPool.Get().(*[]metric.RecordOption)
244 defer func() {
245 *o = (*o)[:0]
246 recOptPool.Put(o)
247 }()
248
249 *o = append(
250 *o,
251 metric.WithAttributes(
252 append(
253 attrs,
254 attribute.String("cicd.pipeline.name", pipelineName),
255 attribute.String("cicd.pipeline.run.state", string(pipelineRunState)),
256 )...,
257 ),
258 )
259
260 m.Float64Histogram.Record(ctx, val, *o...)
261 }
262
263 // AttrPipelineResult returns an optional attribute for the
264 // "cicd.pipeline.result" semantic convention. It represents the result of a
265 // pipeline run.
266 func (PipelineRunDuration) AttrPipelineResult(val PipelineResultAttr) attribute.KeyValue {
267 return attribute.String("cicd.pipeline.result", string(val))
268 }
269
270 // AttrErrorType returns an optional attribute for the "error.type" semantic
271 // convention. It represents the describes a class of error the operation ended
272 // with.
273 func (PipelineRunDuration) AttrErrorType(val ErrorTypeAttr) attribute.KeyValue {
274 return attribute.String("error.type", string(val))
275 }
276
277 // PipelineRunErrors is an instrument used to record metric values conforming to
278 // the "cicd.pipeline.run.errors" semantic conventions. It represents the number
279 // of errors encountered in pipeline runs (eg. compile, test failures).
280 type PipelineRunErrors struct {
281 metric.Int64Counter
282 }
283
284 // NewPipelineRunErrors returns a new PipelineRunErrors instrument.
285 func NewPipelineRunErrors(
286 m metric.Meter,
287 opt ...metric.Int64CounterOption,
288 ) (PipelineRunErrors, error) {
289 // Check if the meter is nil.
290 if m == nil {
291 return PipelineRunErrors{noop.Int64Counter{}}, nil
292 }
293
294 i, err := m.Int64Counter(
295 "cicd.pipeline.run.errors",
296 append([]metric.Int64CounterOption{
297 metric.WithDescription("The number of errors encountered in pipeline runs (eg. compile, test failures)."),
298 metric.WithUnit("{error}"),
299 }, opt...)...,
300 )
301 if err != nil {
302 return PipelineRunErrors{noop.Int64Counter{}}, err
303 }
304 return PipelineRunErrors{i}, nil
305 }
306
307 // Inst returns the underlying metric instrument.
308 func (m PipelineRunErrors) Inst() metric.Int64Counter {
309 return m.Int64Counter
310 }
311
312 // Name returns the semantic convention name of the instrument.
313 func (PipelineRunErrors) Name() string {
314 return "cicd.pipeline.run.errors"
315 }
316
317 // Unit returns the semantic convention unit of the instrument
318 func (PipelineRunErrors) Unit() string {
319 return "{error}"
320 }
321
322 // Description returns the semantic convention description of the instrument
323 func (PipelineRunErrors) Description() string {
324 return "The number of errors encountered in pipeline runs (eg. compile, test failures)."
325 }
326
327 // Add adds incr to the existing count.
328 //
329 // The pipelineName is the the human readable name of the pipeline within a CI/CD
330 // system.
331 //
332 // The errorType is the describes a class of error the operation ended with.
333 //
334 // There might be errors in a pipeline run that are non fatal (eg. they are
335 // suppressed) or in a parallel stage multiple stages could have a fatal error.
336 // This means that this error count might not be the same as the count of metric
337 // `cicd.pipeline.run.duration` with run result `failure`.
338 func (m PipelineRunErrors) Add(
339 ctx context.Context,
340 incr int64,
341 pipelineName string,
342 errorType ErrorTypeAttr,
343 attrs ...attribute.KeyValue,
344 ) {
345 o := addOptPool.Get().(*[]metric.AddOption)
346 defer func() {
347 *o = (*o)[:0]
348 addOptPool.Put(o)
349 }()
350
351 *o = append(
352 *o,
353 metric.WithAttributes(
354 append(
355 attrs,
356 attribute.String("cicd.pipeline.name", pipelineName),
357 attribute.String("error.type", string(errorType)),
358 )...,
359 ),
360 )
361
362 m.Int64Counter.Add(ctx, incr, *o...)
363 }
364
365 // SystemErrors is an instrument used to record metric values conforming to the
366 // "cicd.system.errors" semantic conventions. It represents the number of errors
367 // in a component of the CICD system (eg. controller, scheduler, agent).
368 type SystemErrors struct {
369 metric.Int64Counter
370 }
371
372 // NewSystemErrors returns a new SystemErrors instrument.
373 func NewSystemErrors(
374 m metric.Meter,
375 opt ...metric.Int64CounterOption,
376 ) (SystemErrors, error) {
377 // Check if the meter is nil.
378 if m == nil {
379 return SystemErrors{noop.Int64Counter{}}, nil
380 }
381
382 i, err := m.Int64Counter(
383 "cicd.system.errors",
384 append([]metric.Int64CounterOption{
385 metric.WithDescription("The number of errors in a component of the CICD system (eg. controller, scheduler, agent)."),
386 metric.WithUnit("{error}"),
387 }, opt...)...,
388 )
389 if err != nil {
390 return SystemErrors{noop.Int64Counter{}}, err
391 }
392 return SystemErrors{i}, nil
393 }
394
395 // Inst returns the underlying metric instrument.
396 func (m SystemErrors) Inst() metric.Int64Counter {
397 return m.Int64Counter
398 }
399
400 // Name returns the semantic convention name of the instrument.
401 func (SystemErrors) Name() string {
402 return "cicd.system.errors"
403 }
404
405 // Unit returns the semantic convention unit of the instrument
406 func (SystemErrors) Unit() string {
407 return "{error}"
408 }
409
410 // Description returns the semantic convention description of the instrument
411 func (SystemErrors) Description() string {
412 return "The number of errors in a component of the CICD system (eg. controller, scheduler, agent)."
413 }
414
415 // Add adds incr to the existing count.
416 //
417 // The systemComponent is the the name of a component of the CICD system.
418 //
419 // The errorType is the describes a class of error the operation ended with.
420 //
421 // Errors in pipeline run execution are explicitly excluded. Ie a test failure is
422 // not counted in this metric.
423 func (m SystemErrors) Add(
424 ctx context.Context,
425 incr int64,
426 systemComponent string,
427 errorType ErrorTypeAttr,
428 attrs ...attribute.KeyValue,
429 ) {
430 o := addOptPool.Get().(*[]metric.AddOption)
431 defer func() {
432 *o = (*o)[:0]
433 addOptPool.Put(o)
434 }()
435
436 *o = append(
437 *o,
438 metric.WithAttributes(
439 append(
440 attrs,
441 attribute.String("cicd.system.component", systemComponent),
442 attribute.String("error.type", string(errorType)),
443 )...,
444 ),
445 )
446
447 m.Int64Counter.Add(ctx, incr, *o...)
448 }
449
450 // WorkerCount is an instrument used to record metric values conforming to the
451 // "cicd.worker.count" semantic conventions. It represents the number of workers
452 // on the CICD system by state.
453 type WorkerCount struct {
454 metric.Int64UpDownCounter
455 }
456
457 // NewWorkerCount returns a new WorkerCount instrument.
458 func NewWorkerCount(
459 m metric.Meter,
460 opt ...metric.Int64UpDownCounterOption,
461 ) (WorkerCount, error) {
462 // Check if the meter is nil.
463 if m == nil {
464 return WorkerCount{noop.Int64UpDownCounter{}}, nil
465 }
466
467 i, err := m.Int64UpDownCounter(
468 "cicd.worker.count",
469 append([]metric.Int64UpDownCounterOption{
470 metric.WithDescription("The number of workers on the CICD system by state."),
471 metric.WithUnit("{count}"),
472 }, opt...)...,
473 )
474 if err != nil {
475 return WorkerCount{noop.Int64UpDownCounter{}}, err
476 }
477 return WorkerCount{i}, nil
478 }
479
480 // Inst returns the underlying metric instrument.
481 func (m WorkerCount) Inst() metric.Int64UpDownCounter {
482 return m.Int64UpDownCounter
483 }
484
485 // Name returns the semantic convention name of the instrument.
486 func (WorkerCount) Name() string {
487 return "cicd.worker.count"
488 }
489
490 // Unit returns the semantic convention unit of the instrument
491 func (WorkerCount) Unit() string {
492 return "{count}"
493 }
494
495 // Description returns the semantic convention description of the instrument
496 func (WorkerCount) Description() string {
497 return "The number of workers on the CICD system by state."
498 }
499
500 // Add adds incr to the existing count.
501 //
502 // The workerState is the the state of a CICD worker / agent.
503 func (m WorkerCount) Add(
504 ctx context.Context,
505 incr int64,
506 workerState WorkerStateAttr,
507 attrs ...attribute.KeyValue,
508 ) {
509 o := addOptPool.Get().(*[]metric.AddOption)
510 defer func() {
511 *o = (*o)[:0]
512 addOptPool.Put(o)
513 }()
514
515 *o = append(
516 *o,
517 metric.WithAttributes(
518 append(
519 attrs,
520 attribute.String("cicd.worker.state", string(workerState)),
521 )...,
522 ),
523 )
524
525 m.Int64UpDownCounter.Add(ctx, incr, *o...)
526 }