Debian Codegraph @

semconv/v1.32.0/hwconv/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 hwconv provides types and functionality for OpenTelemetry semantic
7 // conventions in the "hw" namespace.
8 package hwconv
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 // ErrorTypeAttr is an attribute conforming to the error.type semantic
25 // conventions. It represents the type of error encountered by the component.
26 type ErrorTypeAttr string
27
28 var (
29 // ErrorTypeOther is a fallback error value to be used when the instrumentation
30 // doesn't define a custom value.
31 ErrorTypeOther ErrorTypeAttr = "_OTHER"
32 )
33
34 // StateAttr is an attribute conforming to the hw.state semantic conventions. It
35 // represents the current state of the component.
36 type StateAttr string
37
38 var (
39 // StateOk is the ok.
40 StateOk StateAttr = "ok"
41 // StateDegraded is the degraded.
42 StateDegraded StateAttr = "degraded"
43 // StateFailed is the failed.
44 StateFailed StateAttr = "failed"
45 )
46
47 // TypeAttr is an attribute conforming to the hw.type semantic conventions. It
48 // represents the type of the component.
49 type TypeAttr string
50
51 var (
52 // TypeBattery is the battery.
53 TypeBattery TypeAttr = "battery"
54 // TypeCPU is the CPU.
55 TypeCPU TypeAttr = "cpu"
56 // TypeDiskController is the disk controller.
57 TypeDiskController TypeAttr = "disk_controller"
58 // TypeEnclosure is the enclosure.
59 TypeEnclosure TypeAttr = "enclosure"
60 // TypeFan is the fan.
61 TypeFan TypeAttr = "fan"
62 // TypeGpu is the GPU.
63 TypeGpu TypeAttr = "gpu"
64 // TypeLogicalDisk is the logical disk.
65 TypeLogicalDisk TypeAttr = "logical_disk"
66 // TypeMemory is the memory.
67 TypeMemory TypeAttr = "memory"
68 // TypeNetwork is the network.
69 TypeNetwork TypeAttr = "network"
70 // TypePhysicalDisk is the physical disk.
71 TypePhysicalDisk TypeAttr = "physical_disk"
72 // TypePowerSupply is the power supply.
73 TypePowerSupply TypeAttr = "power_supply"
74 // TypeTapeDrive is the tape drive.
75 TypeTapeDrive TypeAttr = "tape_drive"
76 // TypeTemperature is the temperature.
77 TypeTemperature TypeAttr = "temperature"
78 // TypeVoltage is the voltage.
79 TypeVoltage TypeAttr = "voltage"
80 )
81
82 // Energy is an instrument used to record metric values conforming to the
83 // "hw.energy" semantic conventions. It represents the energy consumed by the
84 // component.
85 type Energy struct {
86 metric.Int64Counter
87 }
88
89 // NewEnergy returns a new Energy instrument.
90 func NewEnergy(
91 m metric.Meter,
92 opt ...metric.Int64CounterOption,
93 ) (Energy, error) {
94 // Check if the meter is nil.
95 if m == nil {
96 return Energy{noop.Int64Counter{}}, nil
97 }
98
99 i, err := m.Int64Counter(
100 "hw.energy",
101 append([]metric.Int64CounterOption{
102 metric.WithDescription("Energy consumed by the component"),
103 metric.WithUnit("J"),
104 }, opt...)...,
105 )
106 if err != nil {
107 return Energy{noop.Int64Counter{}}, err
108 }
109 return Energy{i}, nil
110 }
111
112 // Inst returns the underlying metric instrument.
113 func (m Energy) Inst() metric.Int64Counter {
114 return m.Int64Counter
115 }
116
117 // Name returns the semantic convention name of the instrument.
118 func (Energy) Name() string {
119 return "hw.energy"
120 }
121
122 // Unit returns the semantic convention unit of the instrument
123 func (Energy) Unit() string {
124 return "J"
125 }
126
127 // Description returns the semantic convention description of the instrument
128 func (Energy) Description() string {
129 return "Energy consumed by the component"
130 }
131
132 // Add adds incr to the existing count.
133 //
134 // The id is the an identifier for the hardware component, unique within the
135 // monitored host
136 //
137 // The hwType is the type of the component
138 //
139 // All additional attrs passed are included in the recorded value.
140 func (m Energy) Add(
141 ctx context.Context,
142 incr int64,
143 id string,
144 hwType TypeAttr,
145 attrs ...attribute.KeyValue,
146 ) {
147 o := addOptPool.Get().(*[]metric.AddOption)
148 defer func() {
149 *o = (*o)[:0]
150 addOptPool.Put(o)
151 }()
152
153 *o = append(
154 *o,
155 metric.WithAttributes(
156 append(
157 attrs,
158 attribute.String("hw.id", id),
159 attribute.String("hw.type", string(hwType)),
160 )...,
161 ),
162 )
163
164 m.Int64Counter.Add(ctx, incr, *o...)
165 }
166
167 // AttrName returns an optional attribute for the "hw.name" semantic convention.
168 // It represents an easily-recognizable name for the hardware component.
169 func (Energy) AttrName(val string) attribute.KeyValue {
170 return attribute.String("hw.name", val)
171 }
172
173 // AttrParent returns an optional attribute for the "hw.parent" semantic
174 // convention. It represents the unique identifier of the parent component
175 // (typically the `hw.id` attribute of the enclosure, or disk controller).
176 func (Energy) AttrParent(val string) attribute.KeyValue {
177 return attribute.String("hw.parent", val)
178 }
179
180 // Errors is an instrument used to record metric values conforming to the
181 // "hw.errors" semantic conventions. It represents the number of errors
182 // encountered by the component.
183 type Errors struct {
184 metric.Int64Counter
185 }
186
187 // NewErrors returns a new Errors instrument.
188 func NewErrors(
189 m metric.Meter,
190 opt ...metric.Int64CounterOption,
191 ) (Errors, error) {
192 // Check if the meter is nil.
193 if m == nil {
194 return Errors{noop.Int64Counter{}}, nil
195 }
196
197 i, err := m.Int64Counter(
198 "hw.errors",
199 append([]metric.Int64CounterOption{
200 metric.WithDescription("Number of errors encountered by the component"),
201 metric.WithUnit("{error}"),
202 }, opt...)...,
203 )
204 if err != nil {
205 return Errors{noop.Int64Counter{}}, err
206 }
207 return Errors{i}, nil
208 }
209
210 // Inst returns the underlying metric instrument.
211 func (m Errors) Inst() metric.Int64Counter {
212 return m.Int64Counter
213 }
214
215 // Name returns the semantic convention name of the instrument.
216 func (Errors) Name() string {
217 return "hw.errors"
218 }
219
220 // Unit returns the semantic convention unit of the instrument
221 func (Errors) Unit() string {
222 return "{error}"
223 }
224
225 // Description returns the semantic convention description of the instrument
226 func (Errors) Description() string {
227 return "Number of errors encountered by the component"
228 }
229
230 // Add adds incr to the existing count.
231 //
232 // The id is the an identifier for the hardware component, unique within the
233 // monitored host
234 //
235 // The hwType is the type of the component
236 //
237 // All additional attrs passed are included in the recorded value.
238 func (m Errors) Add(
239 ctx context.Context,
240 incr int64,
241 id string,
242 hwType TypeAttr,
243 attrs ...attribute.KeyValue,
244 ) {
245 o := addOptPool.Get().(*[]metric.AddOption)
246 defer func() {
247 *o = (*o)[:0]
248 addOptPool.Put(o)
249 }()
250
251 *o = append(
252 *o,
253 metric.WithAttributes(
254 append(
255 attrs,
256 attribute.String("hw.id", id),
257 attribute.String("hw.type", string(hwType)),
258 )...,
259 ),
260 )
261
262 m.Int64Counter.Add(ctx, incr, *o...)
263 }
264
265 // AttrErrorType returns an optional attribute for the "error.type" semantic
266 // convention. It represents the type of error encountered by the component.
267 func (Errors) AttrErrorType(val ErrorTypeAttr) attribute.KeyValue {
268 return attribute.String("error.type", string(val))
269 }
270
271 // AttrName returns an optional attribute for the "hw.name" semantic convention.
272 // It represents an easily-recognizable name for the hardware component.
273 func (Errors) AttrName(val string) attribute.KeyValue {
274 return attribute.String("hw.name", val)
275 }
276
277 // AttrParent returns an optional attribute for the "hw.parent" semantic
278 // convention. It represents the unique identifier of the parent component
279 // (typically the `hw.id` attribute of the enclosure, or disk controller).
280 func (Errors) AttrParent(val string) attribute.KeyValue {
281 return attribute.String("hw.parent", val)
282 }
283
284 // HostAmbientTemperature is an instrument used to record metric values
285 // conforming to the "hw.host.ambient_temperature" semantic conventions. It
286 // represents the ambient (external) temperature of the physical host.
287 type HostAmbientTemperature struct {
288 metric.Int64Gauge
289 }
290
291 // NewHostAmbientTemperature returns a new HostAmbientTemperature instrument.
292 func NewHostAmbientTemperature(
293 m metric.Meter,
294 opt ...metric.Int64GaugeOption,
295 ) (HostAmbientTemperature, error) {
296 // Check if the meter is nil.
297 if m == nil {
298 return HostAmbientTemperature{noop.Int64Gauge{}}, nil
299 }
300
301 i, err := m.Int64Gauge(
302 "hw.host.ambient_temperature",
303 append([]metric.Int64GaugeOption{
304 metric.WithDescription("Ambient (external) temperature of the physical host"),
305 metric.WithUnit("Cel"),
306 }, opt...)...,
307 )
308 if err != nil {
309 return HostAmbientTemperature{noop.Int64Gauge{}}, err
310 }
311 return HostAmbientTemperature{i}, nil
312 }
313
314 // Inst returns the underlying metric instrument.
315 func (m HostAmbientTemperature) Inst() metric.Int64Gauge {
316 return m.Int64Gauge
317 }
318
319 // Name returns the semantic convention name of the instrument.
320 func (HostAmbientTemperature) Name() string {
321 return "hw.host.ambient_temperature"
322 }
323
324 // Unit returns the semantic convention unit of the instrument
325 func (HostAmbientTemperature) Unit() string {
326 return "Cel"
327 }
328
329 // Description returns the semantic convention description of the instrument
330 func (HostAmbientTemperature) Description() string {
331 return "Ambient (external) temperature of the physical host"
332 }
333
334 // Record records val to the current distribution.
335 //
336 // The id is the an identifier for the hardware component, unique within the
337 // monitored host
338 //
339 // All additional attrs passed are included in the recorded value.
340 func (m HostAmbientTemperature) Record(
341 ctx context.Context,
342 val int64,
343 id string,
344 attrs ...attribute.KeyValue,
345 ) {
346 o := recOptPool.Get().(*[]metric.RecordOption)
347 defer func() {
348 *o = (*o)[:0]
349 recOptPool.Put(o)
350 }()
351
352 *o = append(
353 *o,
354 metric.WithAttributes(
355 append(
356 attrs,
357 attribute.String("hw.id", id),
358 )...,
359 ),
360 )
361
362 m.Int64Gauge.Record(ctx, val, *o...)
363 }
364
365 // AttrName returns an optional attribute for the "hw.name" semantic convention.
366 // It represents an easily-recognizable name for the hardware component.
367 func (HostAmbientTemperature) AttrName(val string) attribute.KeyValue {
368 return attribute.String("hw.name", val)
369 }
370
371 // AttrParent returns an optional attribute for the "hw.parent" semantic
372 // convention. It represents the unique identifier of the parent component
373 // (typically the `hw.id` attribute of the enclosure, or disk controller).
374 func (HostAmbientTemperature) AttrParent(val string) attribute.KeyValue {
375 return attribute.String("hw.parent", val)
376 }
377
378 // HostEnergy is an instrument used to record metric values conforming to the
379 // "hw.host.energy" semantic conventions. It represents the total energy consumed
380 // by the entire physical host, in joules.
381 type HostEnergy struct {
382 metric.Int64Counter
383 }
384
385 // NewHostEnergy returns a new HostEnergy instrument.
386 func NewHostEnergy(
387 m metric.Meter,
388 opt ...metric.Int64CounterOption,
389 ) (HostEnergy, error) {
390 // Check if the meter is nil.
391 if m == nil {
392 return HostEnergy{noop.Int64Counter{}}, nil
393 }
394
395 i, err := m.Int64Counter(
396 "hw.host.energy",
397 append([]metric.Int64CounterOption{
398 metric.WithDescription("Total energy consumed by the entire physical host, in joules"),
399 metric.WithUnit("J"),
400 }, opt...)...,
401 )
402 if err != nil {
403 return HostEnergy{noop.Int64Counter{}}, err
404 }
405 return HostEnergy{i}, nil
406 }
407
408 // Inst returns the underlying metric instrument.
409 func (m HostEnergy) Inst() metric.Int64Counter {
410 return m.Int64Counter
411 }
412
413 // Name returns the semantic convention name of the instrument.
414 func (HostEnergy) Name() string {
415 return "hw.host.energy"
416 }
417
418 // Unit returns the semantic convention unit of the instrument
419 func (HostEnergy) Unit() string {
420 return "J"
421 }
422
423 // Description returns the semantic convention description of the instrument
424 func (HostEnergy) Description() string {
425 return "Total energy consumed by the entire physical host, in joules"
426 }
427
428 // Add adds incr to the existing count.
429 //
430 // The id is the an identifier for the hardware component, unique within the
431 // monitored host
432 //
433 // All additional attrs passed are included in the recorded value.
434 //
435 // The overall energy usage of a host MUST be reported using the specific
436 // `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic
437 // `hw.energy` and `hw.power` described in the previous section, to prevent
438 // summing up overlapping values.
439 func (m HostEnergy) Add(
440 ctx context.Context,
441 incr int64,
442 id string,
443 attrs ...attribute.KeyValue,
444 ) {
445 o := addOptPool.Get().(*[]metric.AddOption)
446 defer func() {
447 *o = (*o)[:0]
448 addOptPool.Put(o)
449 }()
450
451 *o = append(
452 *o,
453 metric.WithAttributes(
454 append(
455 attrs,
456 attribute.String("hw.id", id),
457 )...,
458 ),
459 )
460
461 m.Int64Counter.Add(ctx, incr, *o...)
462 }
463
464 // AttrName returns an optional attribute for the "hw.name" semantic convention.
465 // It represents an easily-recognizable name for the hardware component.
466 func (HostEnergy) AttrName(val string) attribute.KeyValue {
467 return attribute.String("hw.name", val)
468 }
469
470 // AttrParent returns an optional attribute for the "hw.parent" semantic
471 // convention. It represents the unique identifier of the parent component
472 // (typically the `hw.id` attribute of the enclosure, or disk controller).
473 func (HostEnergy) AttrParent(val string) attribute.KeyValue {
474 return attribute.String("hw.parent", val)
475 }
476
477 // HostHeatingMargin is an instrument used to record metric values conforming to
478 // the "hw.host.heating_margin" semantic conventions. It represents the by how
479 // many degrees Celsius the temperature of the physical host can be increased,
480 // before reaching a warning threshold on one of the internal sensors.
481 type HostHeatingMargin struct {
482 metric.Int64Gauge
483 }
484
485 // NewHostHeatingMargin returns a new HostHeatingMargin instrument.
486 func NewHostHeatingMargin(
487 m metric.Meter,
488 opt ...metric.Int64GaugeOption,
489 ) (HostHeatingMargin, error) {
490 // Check if the meter is nil.
491 if m == nil {
492 return HostHeatingMargin{noop.Int64Gauge{}}, nil
493 }
494
495 i, err := m.Int64Gauge(
496 "hw.host.heating_margin",
497 append([]metric.Int64GaugeOption{
498 metric.WithDescription("By how many degrees Celsius the temperature of the physical host can be increased, before reaching a warning threshold on one of the internal sensors"),
499 metric.WithUnit("Cel"),
500 }, opt...)...,
501 )
502 if err != nil {
503 return HostHeatingMargin{noop.Int64Gauge{}}, err
504 }
505 return HostHeatingMargin{i}, nil
506 }
507
508 // Inst returns the underlying metric instrument.
509 func (m HostHeatingMargin) Inst() metric.Int64Gauge {
510 return m.Int64Gauge
511 }
512
513 // Name returns the semantic convention name of the instrument.
514 func (HostHeatingMargin) Name() string {
515 return "hw.host.heating_margin"
516 }
517
518 // Unit returns the semantic convention unit of the instrument
519 func (HostHeatingMargin) Unit() string {
520 return "Cel"
521 }
522
523 // Description returns the semantic convention description of the instrument
524 func (HostHeatingMargin) Description() string {
525 return "By how many degrees Celsius the temperature of the physical host can be increased, before reaching a warning threshold on one of the internal sensors"
526 }
527
528 // Record records val to the current distribution.
529 //
530 // The id is the an identifier for the hardware component, unique within the
531 // monitored host
532 //
533 // All additional attrs passed are included in the recorded value.
534 func (m HostHeatingMargin) Record(
535 ctx context.Context,
536 val int64,
537 id string,
538 attrs ...attribute.KeyValue,
539 ) {
540 o := recOptPool.Get().(*[]metric.RecordOption)
541 defer func() {
542 *o = (*o)[:0]
543 recOptPool.Put(o)
544 }()
545
546 *o = append(
547 *o,
548 metric.WithAttributes(
549 append(
550 attrs,
551 attribute.String("hw.id", id),
552 )...,
553 ),
554 )
555
556 m.Int64Gauge.Record(ctx, val, *o...)
557 }
558
559 // AttrName returns an optional attribute for the "hw.name" semantic convention.
560 // It represents an easily-recognizable name for the hardware component.
561 func (HostHeatingMargin) AttrName(val string) attribute.KeyValue {
562 return attribute.String("hw.name", val)
563 }
564
565 // AttrParent returns an optional attribute for the "hw.parent" semantic
566 // convention. It represents the unique identifier of the parent component
567 // (typically the `hw.id` attribute of the enclosure, or disk controller).
568 func (HostHeatingMargin) AttrParent(val string) attribute.KeyValue {
569 return attribute.String("hw.parent", val)
570 }
571
572 // HostPower is an instrument used to record metric values conforming to the
573 // "hw.host.power" semantic conventions. It represents the instantaneous power
574 // consumed by the entire physical host in Watts (`hw.host.energy` is preferred).
575 type HostPower struct {
576 metric.Int64Gauge
577 }
578
579 // NewHostPower returns a new HostPower instrument.
580 func NewHostPower(
581 m metric.Meter,
582 opt ...metric.Int64GaugeOption,
583 ) (HostPower, error) {
584 // Check if the meter is nil.
585 if m == nil {
586 return HostPower{noop.Int64Gauge{}}, nil
587 }
588
589 i, err := m.Int64Gauge(
590 "hw.host.power",
591 append([]metric.Int64GaugeOption{
592 metric.WithDescription("Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred)"),
593 metric.WithUnit("W"),
594 }, opt...)...,
595 )
596 if err != nil {
597 return HostPower{noop.Int64Gauge{}}, err
598 }
599 return HostPower{i}, nil
600 }
601
602 // Inst returns the underlying metric instrument.
603 func (m HostPower) Inst() metric.Int64Gauge {
604 return m.Int64Gauge
605 }
606
607 // Name returns the semantic convention name of the instrument.
608 func (HostPower) Name() string {
609 return "hw.host.power"
610 }
611
612 // Unit returns the semantic convention unit of the instrument
613 func (HostPower) Unit() string {
614 return "W"
615 }
616
617 // Description returns the semantic convention description of the instrument
618 func (HostPower) Description() string {
619 return "Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred)"
620 }
621
622 // Record records val to the current distribution.
623 //
624 // The id is the an identifier for the hardware component, unique within the
625 // monitored host
626 //
627 // All additional attrs passed are included in the recorded value.
628 //
629 // The overall energy usage of a host MUST be reported using the specific
630 // `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic
631 // `hw.energy` and `hw.power` described in the previous section, to prevent
632 // summing up overlapping values.
633 func (m HostPower) Record(
634 ctx context.Context,
635 val int64,
636 id string,
637 attrs ...attribute.KeyValue,
638 ) {
639 o := recOptPool.Get().(*[]metric.RecordOption)
640 defer func() {
641 *o = (*o)[:0]
642 recOptPool.Put(o)
643 }()
644
645 *o = append(
646 *o,
647 metric.WithAttributes(
648 append(
649 attrs,
650 attribute.String("hw.id", id),
651 )...,
652 ),
653 )
654
655 m.Int64Gauge.Record(ctx, val, *o...)
656 }
657
658 // AttrName returns an optional attribute for the "hw.name" semantic convention.
659 // It represents an easily-recognizable name for the hardware component.
660 func (HostPower) AttrName(val string) attribute.KeyValue {
661 return attribute.String("hw.name", val)
662 }
663
664 // AttrParent returns an optional attribute for the "hw.parent" semantic
665 // convention. It represents the unique identifier of the parent component
666 // (typically the `hw.id` attribute of the enclosure, or disk controller).
667 func (HostPower) AttrParent(val string) attribute.KeyValue {
668 return attribute.String("hw.parent", val)
669 }
670
671 // Power is an instrument used to record metric values conforming to the
672 // "hw.power" semantic conventions. It represents the instantaneous power
673 // consumed by the component.
674 type Power struct {
675 metric.Int64Gauge
676 }
677
678 // NewPower returns a new Power instrument.
679 func NewPower(
680 m metric.Meter,
681 opt ...metric.Int64GaugeOption,
682 ) (Power, error) {
683 // Check if the meter is nil.
684 if m == nil {
685 return Power{noop.Int64Gauge{}}, nil
686 }
687
688 i, err := m.Int64Gauge(
689 "hw.power",
690 append([]metric.Int64GaugeOption{
691 metric.WithDescription("Instantaneous power consumed by the component"),
692 metric.WithUnit("W"),
693 }, opt...)...,
694 )
695 if err != nil {
696 return Power{noop.Int64Gauge{}}, err
697 }
698 return Power{i}, nil
699 }
700
701 // Inst returns the underlying metric instrument.
702 func (m Power) Inst() metric.Int64Gauge {
703 return m.Int64Gauge
704 }
705
706 // Name returns the semantic convention name of the instrument.
707 func (Power) Name() string {
708 return "hw.power"
709 }
710
711 // Unit returns the semantic convention unit of the instrument
712 func (Power) Unit() string {
713 return "W"
714 }
715
716 // Description returns the semantic convention description of the instrument
717 func (Power) Description() string {
718 return "Instantaneous power consumed by the component"
719 }
720
721 // Record records val to the current distribution.
722 //
723 // The id is the an identifier for the hardware component, unique within the
724 // monitored host
725 //
726 // The hwType is the type of the component
727 //
728 // All additional attrs passed are included in the recorded value.
729 //
730 // It is recommended to report `hw.energy` instead of `hw.power` when possible.
731 func (m Power) Record(
732 ctx context.Context,
733 val int64,
734 id string,
735 hwType TypeAttr,
736 attrs ...attribute.KeyValue,
737 ) {
738 o := recOptPool.Get().(*[]metric.RecordOption)
739 defer func() {
740 *o = (*o)[:0]
741 recOptPool.Put(o)
742 }()
743
744 *o = append(
745 *o,
746 metric.WithAttributes(
747 append(
748 attrs,
749 attribute.String("hw.id", id),
750 attribute.String("hw.type", string(hwType)),
751 )...,
752 ),
753 )
754
755 m.Int64Gauge.Record(ctx, val, *o...)
756 }
757
758 // AttrName returns an optional attribute for the "hw.name" semantic convention.
759 // It represents an easily-recognizable name for the hardware component.
760 func (Power) AttrName(val string) attribute.KeyValue {
761 return attribute.String("hw.name", val)
762 }
763
764 // AttrParent returns an optional attribute for the "hw.parent" semantic
765 // convention. It represents the unique identifier of the parent component
766 // (typically the `hw.id` attribute of the enclosure, or disk controller).
767 func (Power) AttrParent(val string) attribute.KeyValue {
768 return attribute.String("hw.parent", val)
769 }
770
771 // Status is an instrument used to record metric values conforming to the
772 // "hw.status" semantic conventions. It represents the operational status: `1`
773 // (true) or `0` (false) for each of the possible states.
774 type Status struct {
775 metric.Int64UpDownCounter
776 }
777
778 // NewStatus returns a new Status instrument.
779 func NewStatus(
780 m metric.Meter,
781 opt ...metric.Int64UpDownCounterOption,
782 ) (Status, error) {
783 // Check if the meter is nil.
784 if m == nil {
785 return Status{noop.Int64UpDownCounter{}}, nil
786 }
787
788 i, err := m.Int64UpDownCounter(
789 "hw.status",
790 append([]metric.Int64UpDownCounterOption{
791 metric.WithDescription("Operational status: `1` (true) or `0` (false) for each of the possible states"),
792 metric.WithUnit("1"),
793 }, opt...)...,
794 )
795 if err != nil {
796 return Status{noop.Int64UpDownCounter{}}, err
797 }
798 return Status{i}, nil
799 }
800
801 // Inst returns the underlying metric instrument.
802 func (m Status) Inst() metric.Int64UpDownCounter {
803 return m.Int64UpDownCounter
804 }
805
806 // Name returns the semantic convention name of the instrument.
807 func (Status) Name() string {
808 return "hw.status"
809 }
810
811 // Unit returns the semantic convention unit of the instrument
812 func (Status) Unit() string {
813 return "1"
814 }
815
816 // Description returns the semantic convention description of the instrument
817 func (Status) Description() string {
818 return "Operational status: `1` (true) or `0` (false) for each of the possible states"
819 }
820
821 // Add adds incr to the existing count.
822 //
823 // The id is the an identifier for the hardware component, unique within the
824 // monitored host
825 //
826 // The state is the the current state of the component
827 //
828 // The hwType is the type of the component
829 //
830 // All additional attrs passed are included in the recorded value.
831 //
832 // `hw.status` is currently specified as an *UpDownCounter* but would ideally be
833 // represented using a [*StateSet* as defined in OpenMetrics]. This semantic
834 // convention will be updated once *StateSet* is specified in OpenTelemetry. This
835 // planned change is not expected to have any consequence on the way users query
836 // their timeseries backend to retrieve the values of `hw.status` over time.
837 //
838 // [ [*StateSet* as defined in OpenMetrics]: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset
839 func (m Status) Add(
840 ctx context.Context,
841 incr int64,
842 id string,
843 state StateAttr,
844 hwType TypeAttr,
845 attrs ...attribute.KeyValue,
846 ) {
847 o := addOptPool.Get().(*[]metric.AddOption)
848 defer func() {
849 *o = (*o)[:0]
850 addOptPool.Put(o)
851 }()
852
853 *o = append(
854 *o,
855 metric.WithAttributes(
856 append(
857 attrs,
858 attribute.String("hw.id", id),
859 attribute.String("hw.state", string(state)),
860 attribute.String("hw.type", string(hwType)),
861 )...,
862 ),
863 )
864
865 m.Int64UpDownCounter.Add(ctx, incr, *o...)
866 }
867
868 // AttrName returns an optional attribute for the "hw.name" semantic convention.
869 // It represents an easily-recognizable name for the hardware component.
870 func (Status) AttrName(val string) attribute.KeyValue {
871 return attribute.String("hw.name", val)
872 }
873
874 // AttrParent returns an optional attribute for the "hw.parent" semantic
875 // convention. It represents the unique identifier of the parent component
876 // (typically the `hw.id` attribute of the enclosure, or disk controller).
877 func (Status) AttrParent(val string) attribute.KeyValue {
878 return attribute.String("hw.parent", val)
879 }