Debian Codegraph @

semconv/v1.38.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 var newPipelineRunActiveOpts = []metric.Int64UpDownCounterOption{
101 metric.WithDescription("The number of pipeline runs currently active in the system by state."),
102 metric.WithUnit("{run}"),
103 }
104
105 // NewPipelineRunActive returns a new PipelineRunActive instrument.
106 func NewPipelineRunActive(
107 m metric.Meter,
108 opt ...metric.Int64UpDownCounterOption,
109 ) (PipelineRunActive, error) {
110 // Check if the meter is nil.
111 if m == nil {
112 return PipelineRunActive{noop.Int64UpDownCounter{}}, nil
113 }
114
115 if len(opt) == 0 {
116 opt = newPipelineRunActiveOpts
117 } else {
118 opt = append(opt, newPipelineRunActiveOpts...)
119 }
120
121 i, err := m.Int64UpDownCounter(
122 "cicd.pipeline.run.active",
123 opt...,
124 )
125 if err != nil {
126 return PipelineRunActive{noop.Int64UpDownCounter{}}, err
127 }
128 return PipelineRunActive{i}, nil
129 }
130
131 // Inst returns the underlying metric instrument.
132 func (m PipelineRunActive) Inst() metric.Int64UpDownCounter {
133 return m.Int64UpDownCounter
134 }
135
136 // Name returns the semantic convention name of the instrument.
137 func (PipelineRunActive) Name() string {
138 return "cicd.pipeline.run.active"
139 }
140
141 // Unit returns the semantic convention unit of the instrument
142 func (PipelineRunActive) Unit() string {
143 return "{run}"
144 }
145
146 // Description returns the semantic convention description of the instrument
147 func (PipelineRunActive) Description() string {
148 return "The number of pipeline runs currently active in the system by state."
149 }
150
151 // Add adds incr to the existing count for attrs.
152 //
153 // The pipelineName is the the human readable name of the pipeline within a CI/CD
154 // system.
155 //
156 // The pipelineRunState is the the pipeline run goes through these states during
157 // its lifecycle.
158 func (m PipelineRunActive) Add(
159 ctx context.Context,
160 incr int64,
161 pipelineName string,
162 pipelineRunState PipelineRunStateAttr,
163 attrs ...attribute.KeyValue,
164 ) {
165 if len(attrs) == 0 {
166 m.Int64UpDownCounter.Add(ctx, incr)
167 return
168 }
169
170 o := addOptPool.Get().(*[]metric.AddOption)
171 defer func() {
172 *o = (*o)[:0]
173 addOptPool.Put(o)
174 }()
175
176 *o = append(
177 *o,
178 metric.WithAttributes(
179 append(
180 attrs,
181 attribute.String("cicd.pipeline.name", pipelineName),
182 attribute.String("cicd.pipeline.run.state", string(pipelineRunState)),
183 )...,
184 ),
185 )
186
187 m.Int64UpDownCounter.Add(ctx, incr, *o...)
188 }
189
190 // AddSet adds incr to the existing count for set.
191 func (m PipelineRunActive) AddSet(ctx context.Context, incr int64, set attribute.Set) {
192 if set.Len() == 0 {
193 m.Int64UpDownCounter.Add(ctx, incr)
194 return
195 }
196
197 o := addOptPool.Get().(*[]metric.AddOption)
198 defer func() {
199 *o = (*o)[:0]
200 addOptPool.Put(o)
201 }()
202
203 *o = append(*o, metric.WithAttributeSet(set))
204 m.Int64UpDownCounter.Add(ctx, incr, *o...)
205 }
206
207 // PipelineRunDuration is an instrument used to record metric values conforming
208 // to the "cicd.pipeline.run.duration" semantic conventions. It represents the
209 // duration of a pipeline run grouped by pipeline, state and result.
210 type PipelineRunDuration struct {
211 metric.Float64Histogram
212 }
213
214 var newPipelineRunDurationOpts = []metric.Float64HistogramOption{
215 metric.WithDescription("Duration of a pipeline run grouped by pipeline, state and result."),
216 metric.WithUnit("s"),
217 }
218
219 // NewPipelineRunDuration returns a new PipelineRunDuration instrument.
220 func NewPipelineRunDuration(
221 m metric.Meter,
222 opt ...metric.Float64HistogramOption,
223 ) (PipelineRunDuration, error) {
224 // Check if the meter is nil.
225 if m == nil {
226 return PipelineRunDuration{noop.Float64Histogram{}}, nil
227 }
228
229 if len(opt) == 0 {
230 opt = newPipelineRunDurationOpts
231 } else {
232 opt = append(opt, newPipelineRunDurationOpts...)
233 }
234
235 i, err := m.Float64Histogram(
236 "cicd.pipeline.run.duration",
237 opt...,
238 )
239 if err != nil {
240 return PipelineRunDuration{noop.Float64Histogram{}}, err
241 }
242 return PipelineRunDuration{i}, nil
243 }
244
245 // Inst returns the underlying metric instrument.
246 func (m PipelineRunDuration) Inst() metric.Float64Histogram {
247 return m.Float64Histogram
248 }
249
250 // Name returns the semantic convention name of the instrument.
251 func (PipelineRunDuration) Name() string {
252 return "cicd.pipeline.run.duration"
253 }
254
255 // Unit returns the semantic convention unit of the instrument
256 func (PipelineRunDuration) Unit() string {
257 return "s"
258 }
259
260 // Description returns the semantic convention description of the instrument
261 func (PipelineRunDuration) Description() string {
262 return "Duration of a pipeline run grouped by pipeline, state and result."
263 }
264
265 // Record records val to the current distribution for attrs.
266 //
267 // The pipelineName is the the human readable name of the pipeline within a CI/CD
268 // system.
269 //
270 // The pipelineRunState is the the pipeline run goes through these states during
271 // its lifecycle.
272 //
273 // All additional attrs passed are included in the recorded value.
274 func (m PipelineRunDuration) Record(
275 ctx context.Context,
276 val float64,
277 pipelineName string,
278 pipelineRunState PipelineRunStateAttr,
279 attrs ...attribute.KeyValue,
280 ) {
281 if len(attrs) == 0 {
282 m.Float64Histogram.Record(ctx, val)
283 return
284 }
285
286 o := recOptPool.Get().(*[]metric.RecordOption)
287 defer func() {
288 *o = (*o)[:0]
289 recOptPool.Put(o)
290 }()
291
292 *o = append(
293 *o,
294 metric.WithAttributes(
295 append(
296 attrs,
297 attribute.String("cicd.pipeline.name", pipelineName),
298 attribute.String("cicd.pipeline.run.state", string(pipelineRunState)),
299 )...,
300 ),
301 )
302
303 m.Float64Histogram.Record(ctx, val, *o...)
304 }
305
306 // RecordSet records val to the current distribution for set.
307 func (m PipelineRunDuration) RecordSet(ctx context.Context, val float64, set attribute.Set) {
308 if set.Len() == 0 {
309 m.Float64Histogram.Record(ctx, val)
310 return
311 }
312
313 o := recOptPool.Get().(*[]metric.RecordOption)
314 defer func() {
315 *o = (*o)[:0]
316 recOptPool.Put(o)
317 }()
318
319 *o = append(*o, metric.WithAttributeSet(set))
320 m.Float64Histogram.Record(ctx, val, *o...)
321 }
322
323 // AttrPipelineResult returns an optional attribute for the
324 // "cicd.pipeline.result" semantic convention. It represents the result of a
325 // pipeline run.
326 func (PipelineRunDuration) AttrPipelineResult(val PipelineResultAttr) attribute.KeyValue {
327 return attribute.String("cicd.pipeline.result", string(val))
328 }
329
330 // AttrErrorType returns an optional attribute for the "error.type" semantic
331 // convention. It represents the describes a class of error the operation ended
332 // with.
333 func (PipelineRunDuration) AttrErrorType(val ErrorTypeAttr) attribute.KeyValue {
334 return attribute.String("error.type", string(val))
335 }
336
337 // PipelineRunErrors is an instrument used to record metric values conforming to
338 // the "cicd.pipeline.run.errors" semantic conventions. It represents the number
339 // of errors encountered in pipeline runs (eg. compile, test failures).
340 type PipelineRunErrors struct {
341 metric.Int64Counter
342 }
343
344 var newPipelineRunErrorsOpts = []metric.Int64CounterOption{
345 metric.WithDescription("The number of errors encountered in pipeline runs (eg. compile, test failures)."),
346 metric.WithUnit("{error}"),
347 }
348
349 // NewPipelineRunErrors returns a new PipelineRunErrors instrument.
350 func NewPipelineRunErrors(
351 m metric.Meter,
352 opt ...metric.Int64CounterOption,
353 ) (PipelineRunErrors, error) {
354 // Check if the meter is nil.
355 if m == nil {
356 return PipelineRunErrors{noop.Int64Counter{}}, nil
357 }
358
359 if len(opt) == 0 {
360 opt = newPipelineRunErrorsOpts
361 } else {
362 opt = append(opt, newPipelineRunErrorsOpts...)
363 }
364
365 i, err := m.Int64Counter(
366 "cicd.pipeline.run.errors",
367 opt...,
368 )
369 if err != nil {
370 return PipelineRunErrors{noop.Int64Counter{}}, err
371 }
372 return PipelineRunErrors{i}, nil
373 }
374
375 // Inst returns the underlying metric instrument.
376 func (m PipelineRunErrors) Inst() metric.Int64Counter {
377 return m.Int64Counter
378 }
379
380 // Name returns the semantic convention name of the instrument.
381 func (PipelineRunErrors) Name() string {
382 return "cicd.pipeline.run.errors"
383 }
384
385 // Unit returns the semantic convention unit of the instrument
386 func (PipelineRunErrors) Unit() string {
387 return "{error}"
388 }
389
390 // Description returns the semantic convention description of the instrument
391 func (PipelineRunErrors) Description() string {
392 return "The number of errors encountered in pipeline runs (eg. compile, test failures)."
393 }
394
395 // Add adds incr to the existing count for attrs.
396 //
397 // The pipelineName is the the human readable name of the pipeline within a CI/CD
398 // system.
399 //
400 // The errorType is the describes a class of error the operation ended with.
401 //
402 // There might be errors in a pipeline run that are non fatal (eg. they are
403 // suppressed) or in a parallel stage multiple stages could have a fatal error.
404 // This means that this error count might not be the same as the count of metric
405 // `cicd.pipeline.run.duration` with run result `failure`.
406 func (m PipelineRunErrors) Add(
407 ctx context.Context,
408 incr int64,
409 pipelineName string,
410 errorType ErrorTypeAttr,
411 attrs ...attribute.KeyValue,
412 ) {
413 if len(attrs) == 0 {
414 m.Int64Counter.Add(ctx, incr)
415 return
416 }
417
418 o := addOptPool.Get().(*[]metric.AddOption)
419 defer func() {
420 *o = (*o)[:0]
421 addOptPool.Put(o)
422 }()
423
424 *o = append(
425 *o,
426 metric.WithAttributes(
427 append(
428 attrs,
429 attribute.String("cicd.pipeline.name", pipelineName),
430 attribute.String("error.type", string(errorType)),
431 )...,
432 ),
433 )
434
435 m.Int64Counter.Add(ctx, incr, *o...)
436 }
437
438 // AddSet adds incr to the existing count for set.
439 //
440 // There might be errors in a pipeline run that are non fatal (eg. they are
441 // suppressed) or in a parallel stage multiple stages could have a fatal error.
442 // This means that this error count might not be the same as the count of metric
443 // `cicd.pipeline.run.duration` with run result `failure`.
444 func (m PipelineRunErrors) AddSet(ctx context.Context, incr int64, set attribute.Set) {
445 if set.Len() == 0 {
446 m.Int64Counter.Add(ctx, incr)
447 return
448 }
449
450 o := addOptPool.Get().(*[]metric.AddOption)
451 defer func() {
452 *o = (*o)[:0]
453 addOptPool.Put(o)
454 }()
455
456 *o = append(*o, metric.WithAttributeSet(set))
457 m.Int64Counter.Add(ctx, incr, *o...)
458 }
459
460 // SystemErrors is an instrument used to record metric values conforming to the
461 // "cicd.system.errors" semantic conventions. It represents the number of errors
462 // in a component of the CICD system (eg. controller, scheduler, agent).
463 type SystemErrors struct {
464 metric.Int64Counter
465 }
466
467 var newSystemErrorsOpts = []metric.Int64CounterOption{
468 metric.WithDescription("The number of errors in a component of the CICD system (eg. controller, scheduler, agent)."),
469 metric.WithUnit("{error}"),
470 }
471
472 // NewSystemErrors returns a new SystemErrors instrument.
473 func NewSystemErrors(
474 m metric.Meter,
475 opt ...metric.Int64CounterOption,
476 ) (SystemErrors, error) {
477 // Check if the meter is nil.
478 if m == nil {
479 return SystemErrors{noop.Int64Counter{}}, nil
480 }
481
482 if len(opt) == 0 {
483 opt = newSystemErrorsOpts
484 } else {
485 opt = append(opt, newSystemErrorsOpts...)
486 }
487
488 i, err := m.Int64Counter(
489 "cicd.system.errors",
490 opt...,
491 )
492 if err != nil {
493 return SystemErrors{noop.Int64Counter{}}, err
494 }
495 return SystemErrors{i}, nil
496 }
497
498 // Inst returns the underlying metric instrument.
499 func (m SystemErrors) Inst() metric.Int64Counter {
500 return m.Int64Counter
501 }
502
503 // Name returns the semantic convention name of the instrument.
504 func (SystemErrors) Name() string {
505 return "cicd.system.errors"
506 }
507
508 // Unit returns the semantic convention unit of the instrument
509 func (SystemErrors) Unit() string {
510 return "{error}"
511 }
512
513 // Description returns the semantic convention description of the instrument
514 func (SystemErrors) Description() string {
515 return "The number of errors in a component of the CICD system (eg. controller, scheduler, agent)."
516 }
517
518 // Add adds incr to the existing count for attrs.
519 //
520 // The systemComponent is the the name of a component of the CICD system.
521 //
522 // The errorType is the describes a class of error the operation ended with.
523 //
524 // Errors in pipeline run execution are explicitly excluded. Ie a test failure is
525 // not counted in this metric.
526 func (m SystemErrors) Add(
527 ctx context.Context,
528 incr int64,
529 systemComponent string,
530 errorType ErrorTypeAttr,
531 attrs ...attribute.KeyValue,
532 ) {
533 if len(attrs) == 0 {
534 m.Int64Counter.Add(ctx, incr)
535 return
536 }
537
538 o := addOptPool.Get().(*[]metric.AddOption)
539 defer func() {
540 *o = (*o)[:0]
541 addOptPool.Put(o)
542 }()
543
544 *o = append(
545 *o,
546 metric.WithAttributes(
547 append(
548 attrs,
549 attribute.String("cicd.system.component", systemComponent),
550 attribute.String("error.type", string(errorType)),
551 )...,
552 ),
553 )
554
555 m.Int64Counter.Add(ctx, incr, *o...)
556 }
557
558 // AddSet adds incr to the existing count for set.
559 //
560 // Errors in pipeline run execution are explicitly excluded. Ie a test failure is
561 // not counted in this metric.
562 func (m SystemErrors) AddSet(ctx context.Context, incr int64, set attribute.Set) {
563 if set.Len() == 0 {
564 m.Int64Counter.Add(ctx, incr)
565 return
566 }
567
568 o := addOptPool.Get().(*[]metric.AddOption)
569 defer func() {
570 *o = (*o)[:0]
571 addOptPool.Put(o)
572 }()
573
574 *o = append(*o, metric.WithAttributeSet(set))
575 m.Int64Counter.Add(ctx, incr, *o...)
576 }
577
578 // WorkerCount is an instrument used to record metric values conforming to the
579 // "cicd.worker.count" semantic conventions. It represents the number of workers
580 // on the CICD system by state.
581 type WorkerCount struct {
582 metric.Int64UpDownCounter
583 }
584
585 var newWorkerCountOpts = []metric.Int64UpDownCounterOption{
586 metric.WithDescription("The number of workers on the CICD system by state."),
587 metric.WithUnit("{count}"),
588 }
589
590 // NewWorkerCount returns a new WorkerCount instrument.
591 func NewWorkerCount(
592 m metric.Meter,
593 opt ...metric.Int64UpDownCounterOption,
594 ) (WorkerCount, error) {
595 // Check if the meter is nil.
596 if m == nil {
597 return WorkerCount{noop.Int64UpDownCounter{}}, nil
598 }
599
600 if len(opt) == 0 {
601 opt = newWorkerCountOpts
602 } else {
603 opt = append(opt, newWorkerCountOpts...)
604 }
605
606 i, err := m.Int64UpDownCounter(
607 "cicd.worker.count",
608 opt...,
609 )
610 if err != nil {
611 return WorkerCount{noop.Int64UpDownCounter{}}, err
612 }
613 return WorkerCount{i}, nil
614 }
615
616 // Inst returns the underlying metric instrument.
617 func (m WorkerCount) Inst() metric.Int64UpDownCounter {
618 return m.Int64UpDownCounter
619 }
620
621 // Name returns the semantic convention name of the instrument.
622 func (WorkerCount) Name() string {
623 return "cicd.worker.count"
624 }
625
626 // Unit returns the semantic convention unit of the instrument
627 func (WorkerCount) Unit() string {
628 return "{count}"
629 }
630
631 // Description returns the semantic convention description of the instrument
632 func (WorkerCount) Description() string {
633 return "The number of workers on the CICD system by state."
634 }
635
636 // Add adds incr to the existing count for attrs.
637 //
638 // The workerState is the the state of a CICD worker / agent.
639 func (m WorkerCount) Add(
640 ctx context.Context,
641 incr int64,
642 workerState WorkerStateAttr,
643 attrs ...attribute.KeyValue,
644 ) {
645 if len(attrs) == 0 {
646 m.Int64UpDownCounter.Add(ctx, incr)
647 return
648 }
649
650 o := addOptPool.Get().(*[]metric.AddOption)
651 defer func() {
652 *o = (*o)[:0]
653 addOptPool.Put(o)
654 }()
655
656 *o = append(
657 *o,
658 metric.WithAttributes(
659 append(
660 attrs,
661 attribute.String("cicd.worker.state", string(workerState)),
662 )...,
663 ),
664 )
665
666 m.Int64UpDownCounter.Add(ctx, incr, *o...)
667 }
668
669 // AddSet adds incr to the existing count for set.
670 func (m WorkerCount) AddSet(ctx context.Context, incr int64, set attribute.Set) {
671 if set.Len() == 0 {
672 m.Int64UpDownCounter.Add(ctx, incr)
673 return
674 }
675
676 o := addOptPool.Get().(*[]metric.AddOption)
677 defer func() {
678 *o = (*o)[:0]
679 addOptPool.Put(o)
680 }()
681
682 *o = append(*o, metric.WithAttributeSet(set))
683 m.Int64UpDownCounter.Add(ctx, incr, *o...)
684 }