Debian Codegraph @

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