Debian Codegraph @

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