Debian Codegraph @

semconv/v1.36.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 for attrs.
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 if len(attrs) == 0 {
148 m.Int64Counter.Add(ctx, incr)
149 return
150 }
151
152 o := addOptPool.Get().(*[]metric.AddOption)
153 defer func() {
154 *o = (*o)[:0]
155 addOptPool.Put(o)
156 }()
157
158 *o = append(
159 *o,
160 metric.WithAttributes(
161 append(
162 attrs,
163 attribute.String("hw.id", id),
164 attribute.String("hw.type", string(hwType)),
165 )...,
166 ),
167 )
168
169 m.Int64Counter.Add(ctx, incr, *o...)
170 }
171
172 // AddSet adds incr to the existing count for set.
173 func (m Energy) AddSet(ctx context.Context, incr int64, set attribute.Set) {
174 if set.Len() == 0 {
175 m.Int64Counter.Add(ctx, incr)
176 return
177 }
178
179 o := addOptPool.Get().(*[]metric.AddOption)
180 defer func() {
181 *o = (*o)[:0]
182 addOptPool.Put(o)
183 }()
184
185 *o = append(*o, metric.WithAttributeSet(set))
186 m.Int64Counter.Add(ctx, incr, *o...)
187 }
188
189 // AttrName returns an optional attribute for the "hw.name" semantic convention.
190 // It represents an easily-recognizable name for the hardware component.
191 func (Energy) AttrName(val string) attribute.KeyValue {
192 return attribute.String("hw.name", val)
193 }
194
195 // AttrParent returns an optional attribute for the "hw.parent" semantic
196 // convention. It represents the unique identifier of the parent component
197 // (typically the `hw.id` attribute of the enclosure, or disk controller).
198 func (Energy) AttrParent(val string) attribute.KeyValue {
199 return attribute.String("hw.parent", val)
200 }
201
202 // Errors is an instrument used to record metric values conforming to the
203 // "hw.errors" semantic conventions. It represents the number of errors
204 // encountered by the component.
205 type Errors struct {
206 metric.Int64Counter
207 }
208
209 // NewErrors returns a new Errors instrument.
210 func NewErrors(
211 m metric.Meter,
212 opt ...metric.Int64CounterOption,
213 ) (Errors, error) {
214 // Check if the meter is nil.
215 if m == nil {
216 return Errors{noop.Int64Counter{}}, nil
217 }
218
219 i, err := m.Int64Counter(
220 "hw.errors",
221 append([]metric.Int64CounterOption{
222 metric.WithDescription("Number of errors encountered by the component"),
223 metric.WithUnit("{error}"),
224 }, opt...)...,
225 )
226 if err != nil {
227 return Errors{noop.Int64Counter{}}, err
228 }
229 return Errors{i}, nil
230 }
231
232 // Inst returns the underlying metric instrument.
233 func (m Errors) Inst() metric.Int64Counter {
234 return m.Int64Counter
235 }
236
237 // Name returns the semantic convention name of the instrument.
238 func (Errors) Name() string {
239 return "hw.errors"
240 }
241
242 // Unit returns the semantic convention unit of the instrument
243 func (Errors) Unit() string {
244 return "{error}"
245 }
246
247 // Description returns the semantic convention description of the instrument
248 func (Errors) Description() string {
249 return "Number of errors encountered by the component"
250 }
251
252 // Add adds incr to the existing count for attrs.
253 //
254 // The id is the an identifier for the hardware component, unique within the
255 // monitored host
256 //
257 // The hwType is the type of the component
258 //
259 // All additional attrs passed are included in the recorded value.
260 func (m Errors) Add(
261 ctx context.Context,
262 incr int64,
263 id string,
264 hwType TypeAttr,
265 attrs ...attribute.KeyValue,
266 ) {
267 if len(attrs) == 0 {
268 m.Int64Counter.Add(ctx, incr)
269 return
270 }
271
272 o := addOptPool.Get().(*[]metric.AddOption)
273 defer func() {
274 *o = (*o)[:0]
275 addOptPool.Put(o)
276 }()
277
278 *o = append(
279 *o,
280 metric.WithAttributes(
281 append(
282 attrs,
283 attribute.String("hw.id", id),
284 attribute.String("hw.type", string(hwType)),
285 )...,
286 ),
287 )
288
289 m.Int64Counter.Add(ctx, incr, *o...)
290 }
291
292 // AddSet adds incr to the existing count for set.
293 func (m Errors) AddSet(ctx context.Context, incr int64, set attribute.Set) {
294 if set.Len() == 0 {
295 m.Int64Counter.Add(ctx, incr)
296 return
297 }
298
299 o := addOptPool.Get().(*[]metric.AddOption)
300 defer func() {
301 *o = (*o)[:0]
302 addOptPool.Put(o)
303 }()
304
305 *o = append(*o, metric.WithAttributeSet(set))
306 m.Int64Counter.Add(ctx, incr, *o...)
307 }
308
309 // AttrErrorType returns an optional attribute for the "error.type" semantic
310 // convention. It represents the type of error encountered by the component.
311 func (Errors) AttrErrorType(val ErrorTypeAttr) attribute.KeyValue {
312 return attribute.String("error.type", string(val))
313 }
314
315 // AttrName returns an optional attribute for the "hw.name" semantic convention.
316 // It represents an easily-recognizable name for the hardware component.
317 func (Errors) AttrName(val string) attribute.KeyValue {
318 return attribute.String("hw.name", val)
319 }
320
321 // AttrParent returns an optional attribute for the "hw.parent" semantic
322 // convention. It represents the unique identifier of the parent component
323 // (typically the `hw.id` attribute of the enclosure, or disk controller).
324 func (Errors) AttrParent(val string) attribute.KeyValue {
325 return attribute.String("hw.parent", val)
326 }
327
328 // HostAmbientTemperature is an instrument used to record metric values
329 // conforming to the "hw.host.ambient_temperature" semantic conventions. It
330 // represents the ambient (external) temperature of the physical host.
331 type HostAmbientTemperature struct {
332 metric.Int64Gauge
333 }
334
335 // NewHostAmbientTemperature returns a new HostAmbientTemperature instrument.
336 func NewHostAmbientTemperature(
337 m metric.Meter,
338 opt ...metric.Int64GaugeOption,
339 ) (HostAmbientTemperature, error) {
340 // Check if the meter is nil.
341 if m == nil {
342 return HostAmbientTemperature{noop.Int64Gauge{}}, nil
343 }
344
345 i, err := m.Int64Gauge(
346 "hw.host.ambient_temperature",
347 append([]metric.Int64GaugeOption{
348 metric.WithDescription("Ambient (external) temperature of the physical host"),
349 metric.WithUnit("Cel"),
350 }, opt...)...,
351 )
352 if err != nil {
353 return HostAmbientTemperature{noop.Int64Gauge{}}, err
354 }
355 return HostAmbientTemperature{i}, nil
356 }
357
358 // Inst returns the underlying metric instrument.
359 func (m HostAmbientTemperature) Inst() metric.Int64Gauge {
360 return m.Int64Gauge
361 }
362
363 // Name returns the semantic convention name of the instrument.
364 func (HostAmbientTemperature) Name() string {
365 return "hw.host.ambient_temperature"
366 }
367
368 // Unit returns the semantic convention unit of the instrument
369 func (HostAmbientTemperature) Unit() string {
370 return "Cel"
371 }
372
373 // Description returns the semantic convention description of the instrument
374 func (HostAmbientTemperature) Description() string {
375 return "Ambient (external) temperature of the physical host"
376 }
377
378 // Record records val to the current distribution for attrs.
379 //
380 // The id is the an identifier for the hardware component, unique within the
381 // monitored host
382 //
383 // All additional attrs passed are included in the recorded value.
384 func (m HostAmbientTemperature) Record(
385 ctx context.Context,
386 val int64,
387 id string,
388 attrs ...attribute.KeyValue,
389 ) {
390 if len(attrs) == 0 {
391 m.Int64Gauge.Record(ctx, val)
392 return
393 }
394
395 o := recOptPool.Get().(*[]metric.RecordOption)
396 defer func() {
397 *o = (*o)[:0]
398 recOptPool.Put(o)
399 }()
400
401 *o = append(
402 *o,
403 metric.WithAttributes(
404 append(
405 attrs,
406 attribute.String("hw.id", id),
407 )...,
408 ),
409 )
410
411 m.Int64Gauge.Record(ctx, val, *o...)
412 }
413
414 // RecordSet records val to the current distribution for set.
415 func (m HostAmbientTemperature) RecordSet(ctx context.Context, val int64, set attribute.Set) {
416 if set.Len() == 0 {
417 m.Int64Gauge.Record(ctx, val)
418 return
419 }
420
421 o := recOptPool.Get().(*[]metric.RecordOption)
422 defer func() {
423 *o = (*o)[:0]
424 recOptPool.Put(o)
425 }()
426
427 *o = append(*o, metric.WithAttributeSet(set))
428 m.Int64Gauge.Record(ctx, val, *o...)
429 }
430
431 // AttrName returns an optional attribute for the "hw.name" semantic convention.
432 // It represents an easily-recognizable name for the hardware component.
433 func (HostAmbientTemperature) AttrName(val string) attribute.KeyValue {
434 return attribute.String("hw.name", val)
435 }
436
437 // AttrParent returns an optional attribute for the "hw.parent" semantic
438 // convention. It represents the unique identifier of the parent component
439 // (typically the `hw.id` attribute of the enclosure, or disk controller).
440 func (HostAmbientTemperature) AttrParent(val string) attribute.KeyValue {
441 return attribute.String("hw.parent", val)
442 }
443
444 // HostEnergy is an instrument used to record metric values conforming to the
445 // "hw.host.energy" semantic conventions. It represents the total energy consumed
446 // by the entire physical host, in joules.
447 type HostEnergy struct {
448 metric.Int64Counter
449 }
450
451 // NewHostEnergy returns a new HostEnergy instrument.
452 func NewHostEnergy(
453 m metric.Meter,
454 opt ...metric.Int64CounterOption,
455 ) (HostEnergy, error) {
456 // Check if the meter is nil.
457 if m == nil {
458 return HostEnergy{noop.Int64Counter{}}, nil
459 }
460
461 i, err := m.Int64Counter(
462 "hw.host.energy",
463 append([]metric.Int64CounterOption{
464 metric.WithDescription("Total energy consumed by the entire physical host, in joules"),
465 metric.WithUnit("J"),
466 }, opt...)...,
467 )
468 if err != nil {
469 return HostEnergy{noop.Int64Counter{}}, err
470 }
471 return HostEnergy{i}, nil
472 }
473
474 // Inst returns the underlying metric instrument.
475 func (m HostEnergy) Inst() metric.Int64Counter {
476 return m.Int64Counter
477 }
478
479 // Name returns the semantic convention name of the instrument.
480 func (HostEnergy) Name() string {
481 return "hw.host.energy"
482 }
483
484 // Unit returns the semantic convention unit of the instrument
485 func (HostEnergy) Unit() string {
486 return "J"
487 }
488
489 // Description returns the semantic convention description of the instrument
490 func (HostEnergy) Description() string {
491 return "Total energy consumed by the entire physical host, in joules"
492 }
493
494 // Add adds incr to the existing count for attrs.
495 //
496 // The id is the an identifier for the hardware component, unique within the
497 // monitored host
498 //
499 // All additional attrs passed are included in the recorded value.
500 //
501 // The overall energy usage of a host MUST be reported using the specific
502 // `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic
503 // `hw.energy` and `hw.power` described in the previous section, to prevent
504 // summing up overlapping values.
505 func (m HostEnergy) Add(
506 ctx context.Context,
507 incr int64,
508 id string,
509 attrs ...attribute.KeyValue,
510 ) {
511 if len(attrs) == 0 {
512 m.Int64Counter.Add(ctx, incr)
513 return
514 }
515
516 o := addOptPool.Get().(*[]metric.AddOption)
517 defer func() {
518 *o = (*o)[:0]
519 addOptPool.Put(o)
520 }()
521
522 *o = append(
523 *o,
524 metric.WithAttributes(
525 append(
526 attrs,
527 attribute.String("hw.id", id),
528 )...,
529 ),
530 )
531
532 m.Int64Counter.Add(ctx, incr, *o...)
533 }
534
535 // AddSet adds incr to the existing count for set.
536 //
537 // The overall energy usage of a host MUST be reported using the specific
538 // `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic
539 // `hw.energy` and `hw.power` described in the previous section, to prevent
540 // summing up overlapping values.
541 func (m HostEnergy) AddSet(ctx context.Context, incr int64, set attribute.Set) {
542 if set.Len() == 0 {
543 m.Int64Counter.Add(ctx, incr)
544 return
545 }
546
547 o := addOptPool.Get().(*[]metric.AddOption)
548 defer func() {
549 *o = (*o)[:0]
550 addOptPool.Put(o)
551 }()
552
553 *o = append(*o, metric.WithAttributeSet(set))
554 m.Int64Counter.Add(ctx, incr, *o...)
555 }
556
557 // AttrName returns an optional attribute for the "hw.name" semantic convention.
558 // It represents an easily-recognizable name for the hardware component.
559 func (HostEnergy) AttrName(val string) attribute.KeyValue {
560 return attribute.String("hw.name", val)
561 }
562
563 // AttrParent returns an optional attribute for the "hw.parent" semantic
564 // convention. It represents the unique identifier of the parent component
565 // (typically the `hw.id` attribute of the enclosure, or disk controller).
566 func (HostEnergy) AttrParent(val string) attribute.KeyValue {
567 return attribute.String("hw.parent", val)
568 }
569
570 // HostHeatingMargin is an instrument used to record metric values conforming to
571 // the "hw.host.heating_margin" semantic conventions. It represents the by how
572 // many degrees Celsius the temperature of the physical host can be increased,
573 // before reaching a warning threshold on one of the internal sensors.
574 type HostHeatingMargin struct {
575 metric.Int64Gauge
576 }
577
578 // NewHostHeatingMargin returns a new HostHeatingMargin instrument.
579 func NewHostHeatingMargin(
580 m metric.Meter,
581 opt ...metric.Int64GaugeOption,
582 ) (HostHeatingMargin, error) {
583 // Check if the meter is nil.
584 if m == nil {
585 return HostHeatingMargin{noop.Int64Gauge{}}, nil
586 }
587
588 i, err := m.Int64Gauge(
589 "hw.host.heating_margin",
590 append([]metric.Int64GaugeOption{
591 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"),
592 metric.WithUnit("Cel"),
593 }, opt...)...,
594 )
595 if err != nil {
596 return HostHeatingMargin{noop.Int64Gauge{}}, err
597 }
598 return HostHeatingMargin{i}, nil
599 }
600
601 // Inst returns the underlying metric instrument.
602 func (m HostHeatingMargin) Inst() metric.Int64Gauge {
603 return m.Int64Gauge
604 }
605
606 // Name returns the semantic convention name of the instrument.
607 func (HostHeatingMargin) Name() string {
608 return "hw.host.heating_margin"
609 }
610
611 // Unit returns the semantic convention unit of the instrument
612 func (HostHeatingMargin) Unit() string {
613 return "Cel"
614 }
615
616 // Description returns the semantic convention description of the instrument
617 func (HostHeatingMargin) Description() string {
618 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"
619 }
620
621 // Record records val to the current distribution for attrs.
622 //
623 // The id is the an identifier for the hardware component, unique within the
624 // monitored host
625 //
626 // All additional attrs passed are included in the recorded value.
627 func (m HostHeatingMargin) Record(
628 ctx context.Context,
629 val int64,
630 id string,
631 attrs ...attribute.KeyValue,
632 ) {
633 if len(attrs) == 0 {
634 m.Int64Gauge.Record(ctx, val)
635 return
636 }
637
638 o := recOptPool.Get().(*[]metric.RecordOption)
639 defer func() {
640 *o = (*o)[:0]
641 recOptPool.Put(o)
642 }()
643
644 *o = append(
645 *o,
646 metric.WithAttributes(
647 append(
648 attrs,
649 attribute.String("hw.id", id),
650 )...,
651 ),
652 )
653
654 m.Int64Gauge.Record(ctx, val, *o...)
655 }
656
657 // RecordSet records val to the current distribution for set.
658 func (m HostHeatingMargin) RecordSet(ctx context.Context, val int64, set attribute.Set) {
659 if set.Len() == 0 {
660 m.Int64Gauge.Record(ctx, val)
661 return
662 }
663
664 o := recOptPool.Get().(*[]metric.RecordOption)
665 defer func() {
666 *o = (*o)[:0]
667 recOptPool.Put(o)
668 }()
669
670 *o = append(*o, metric.WithAttributeSet(set))
671 m.Int64Gauge.Record(ctx, val, *o...)
672 }
673
674 // AttrName returns an optional attribute for the "hw.name" semantic convention.
675 // It represents an easily-recognizable name for the hardware component.
676 func (HostHeatingMargin) AttrName(val string) attribute.KeyValue {
677 return attribute.String("hw.name", val)
678 }
679
680 // AttrParent returns an optional attribute for the "hw.parent" semantic
681 // convention. It represents the unique identifier of the parent component
682 // (typically the `hw.id` attribute of the enclosure, or disk controller).
683 func (HostHeatingMargin) AttrParent(val string) attribute.KeyValue {
684 return attribute.String("hw.parent", val)
685 }
686
687 // HostPower is an instrument used to record metric values conforming to the
688 // "hw.host.power" semantic conventions. It represents the instantaneous power
689 // consumed by the entire physical host in Watts (`hw.host.energy` is preferred).
690 type HostPower struct {
691 metric.Int64Gauge
692 }
693
694 // NewHostPower returns a new HostPower instrument.
695 func NewHostPower(
696 m metric.Meter,
697 opt ...metric.Int64GaugeOption,
698 ) (HostPower, error) {
699 // Check if the meter is nil.
700 if m == nil {
701 return HostPower{noop.Int64Gauge{}}, nil
702 }
703
704 i, err := m.Int64Gauge(
705 "hw.host.power",
706 append([]metric.Int64GaugeOption{
707 metric.WithDescription("Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred)"),
708 metric.WithUnit("W"),
709 }, opt...)...,
710 )
711 if err != nil {
712 return HostPower{noop.Int64Gauge{}}, err
713 }
714 return HostPower{i}, nil
715 }
716
717 // Inst returns the underlying metric instrument.
718 func (m HostPower) Inst() metric.Int64Gauge {
719 return m.Int64Gauge
720 }
721
722 // Name returns the semantic convention name of the instrument.
723 func (HostPower) Name() string {
724 return "hw.host.power"
725 }
726
727 // Unit returns the semantic convention unit of the instrument
728 func (HostPower) Unit() string {
729 return "W"
730 }
731
732 // Description returns the semantic convention description of the instrument
733 func (HostPower) Description() string {
734 return "Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred)"
735 }
736
737 // Record records val to the current distribution for attrs.
738 //
739 // The id is the an identifier for the hardware component, unique within the
740 // monitored host
741 //
742 // All additional attrs passed are included in the recorded value.
743 //
744 // The overall energy usage of a host MUST be reported using the specific
745 // `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic
746 // `hw.energy` and `hw.power` described in the previous section, to prevent
747 // summing up overlapping values.
748 func (m HostPower) Record(
749 ctx context.Context,
750 val int64,
751 id string,
752 attrs ...attribute.KeyValue,
753 ) {
754 if len(attrs) == 0 {
755 m.Int64Gauge.Record(ctx, val)
756 return
757 }
758
759 o := recOptPool.Get().(*[]metric.RecordOption)
760 defer func() {
761 *o = (*o)[:0]
762 recOptPool.Put(o)
763 }()
764
765 *o = append(
766 *o,
767 metric.WithAttributes(
768 append(
769 attrs,
770 attribute.String("hw.id", id),
771 )...,
772 ),
773 )
774
775 m.Int64Gauge.Record(ctx, val, *o...)
776 }
777
778 // RecordSet records val to the current distribution for set.
779 //
780 // The overall energy usage of a host MUST be reported using the specific
781 // `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic
782 // `hw.energy` and `hw.power` described in the previous section, to prevent
783 // summing up overlapping values.
784 func (m HostPower) RecordSet(ctx context.Context, val int64, set attribute.Set) {
785 if set.Len() == 0 {
786 m.Int64Gauge.Record(ctx, val)
787 return
788 }
789
790 o := recOptPool.Get().(*[]metric.RecordOption)
791 defer func() {
792 *o = (*o)[:0]
793 recOptPool.Put(o)
794 }()
795
796 *o = append(*o, metric.WithAttributeSet(set))
797 m.Int64Gauge.Record(ctx, val, *o...)
798 }
799
800 // AttrName returns an optional attribute for the "hw.name" semantic convention.
801 // It represents an easily-recognizable name for the hardware component.
802 func (HostPower) AttrName(val string) attribute.KeyValue {
803 return attribute.String("hw.name", val)
804 }
805
806 // AttrParent returns an optional attribute for the "hw.parent" semantic
807 // convention. It represents the unique identifier of the parent component
808 // (typically the `hw.id` attribute of the enclosure, or disk controller).
809 func (HostPower) AttrParent(val string) attribute.KeyValue {
810 return attribute.String("hw.parent", val)
811 }
812
813 // Power is an instrument used to record metric values conforming to the
814 // "hw.power" semantic conventions. It represents the instantaneous power
815 // consumed by the component.
816 type Power struct {
817 metric.Int64Gauge
818 }
819
820 // NewPower returns a new Power instrument.
821 func NewPower(
822 m metric.Meter,
823 opt ...metric.Int64GaugeOption,
824 ) (Power, error) {
825 // Check if the meter is nil.
826 if m == nil {
827 return Power{noop.Int64Gauge{}}, nil
828 }
829
830 i, err := m.Int64Gauge(
831 "hw.power",
832 append([]metric.Int64GaugeOption{
833 metric.WithDescription("Instantaneous power consumed by the component"),
834 metric.WithUnit("W"),
835 }, opt...)...,
836 )
837 if err != nil {
838 return Power{noop.Int64Gauge{}}, err
839 }
840 return Power{i}, nil
841 }
842
843 // Inst returns the underlying metric instrument.
844 func (m Power) Inst() metric.Int64Gauge {
845 return m.Int64Gauge
846 }
847
848 // Name returns the semantic convention name of the instrument.
849 func (Power) Name() string {
850 return "hw.power"
851 }
852
853 // Unit returns the semantic convention unit of the instrument
854 func (Power) Unit() string {
855 return "W"
856 }
857
858 // Description returns the semantic convention description of the instrument
859 func (Power) Description() string {
860 return "Instantaneous power consumed by the component"
861 }
862
863 // Record records val to the current distribution for attrs.
864 //
865 // The id is the an identifier for the hardware component, unique within the
866 // monitored host
867 //
868 // The hwType is the type of the component
869 //
870 // All additional attrs passed are included in the recorded value.
871 //
872 // It is recommended to report `hw.energy` instead of `hw.power` when possible.
873 func (m Power) Record(
874 ctx context.Context,
875 val int64,
876 id string,
877 hwType TypeAttr,
878 attrs ...attribute.KeyValue,
879 ) {
880 if len(attrs) == 0 {
881 m.Int64Gauge.Record(ctx, val)
882 return
883 }
884
885 o := recOptPool.Get().(*[]metric.RecordOption)
886 defer func() {
887 *o = (*o)[:0]
888 recOptPool.Put(o)
889 }()
890
891 *o = append(
892 *o,
893 metric.WithAttributes(
894 append(
895 attrs,
896 attribute.String("hw.id", id),
897 attribute.String("hw.type", string(hwType)),
898 )...,
899 ),
900 )
901
902 m.Int64Gauge.Record(ctx, val, *o...)
903 }
904
905 // RecordSet records val to the current distribution for set.
906 //
907 // It is recommended to report `hw.energy` instead of `hw.power` when possible.
908 func (m Power) RecordSet(ctx context.Context, val int64, set attribute.Set) {
909 if set.Len() == 0 {
910 m.Int64Gauge.Record(ctx, val)
911 return
912 }
913
914 o := recOptPool.Get().(*[]metric.RecordOption)
915 defer func() {
916 *o = (*o)[:0]
917 recOptPool.Put(o)
918 }()
919
920 *o = append(*o, metric.WithAttributeSet(set))
921 m.Int64Gauge.Record(ctx, val, *o...)
922 }
923
924 // AttrName returns an optional attribute for the "hw.name" semantic convention.
925 // It represents an easily-recognizable name for the hardware component.
926 func (Power) AttrName(val string) attribute.KeyValue {
927 return attribute.String("hw.name", val)
928 }
929
930 // AttrParent returns an optional attribute for the "hw.parent" semantic
931 // convention. It represents the unique identifier of the parent component
932 // (typically the `hw.id` attribute of the enclosure, or disk controller).
933 func (Power) AttrParent(val string) attribute.KeyValue {
934 return attribute.String("hw.parent", val)
935 }
936
937 // Status is an instrument used to record metric values conforming to the
938 // "hw.status" semantic conventions. It represents the operational status: `1`
939 // (true) or `0` (false) for each of the possible states.
940 type Status struct {
941 metric.Int64UpDownCounter
942 }
943
944 // NewStatus returns a new Status instrument.
945 func NewStatus(
946 m metric.Meter,
947 opt ...metric.Int64UpDownCounterOption,
948 ) (Status, error) {
949 // Check if the meter is nil.
950 if m == nil {
951 return Status{noop.Int64UpDownCounter{}}, nil
952 }
953
954 i, err := m.Int64UpDownCounter(
955 "hw.status",
956 append([]metric.Int64UpDownCounterOption{
957 metric.WithDescription("Operational status: `1` (true) or `0` (false) for each of the possible states"),
958 metric.WithUnit("1"),
959 }, opt...)...,
960 )
961 if err != nil {
962 return Status{noop.Int64UpDownCounter{}}, err
963 }
964 return Status{i}, nil
965 }
966
967 // Inst returns the underlying metric instrument.
968 func (m Status) Inst() metric.Int64UpDownCounter {
969 return m.Int64UpDownCounter
970 }
971
972 // Name returns the semantic convention name of the instrument.
973 func (Status) Name() string {
974 return "hw.status"
975 }
976
977 // Unit returns the semantic convention unit of the instrument
978 func (Status) Unit() string {
979 return "1"
980 }
981
982 // Description returns the semantic convention description of the instrument
983 func (Status) Description() string {
984 return "Operational status: `1` (true) or `0` (false) for each of the possible states"
985 }
986
987 // Add adds incr to the existing count for attrs.
988 //
989 // The id is the an identifier for the hardware component, unique within the
990 // monitored host
991 //
992 // The state is the the current state of the component
993 //
994 // The hwType is the type of the component
995 //
996 // All additional attrs passed are included in the recorded value.
997 //
998 // `hw.status` is currently specified as an *UpDownCounter* but would ideally be
999 // represented using a [*StateSet* as defined in OpenMetrics]. This semantic
1000 // convention will be updated once *StateSet* is specified in OpenTelemetry. This
1001 // planned change is not expected to have any consequence on the way users query
1002 // their timeseries backend to retrieve the values of `hw.status` over time.
1003 //
1004 // [ [*StateSet* as defined in OpenMetrics]: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset
1005 func (m Status) Add(
1006 ctx context.Context,
1007 incr int64,
1008 id string,
1009 state StateAttr,
1010 hwType TypeAttr,
1011 attrs ...attribute.KeyValue,
1012 ) {
1013 if len(attrs) == 0 {
1014 m.Int64UpDownCounter.Add(ctx, incr)
1015 return
1016 }
1017
1018 o := addOptPool.Get().(*[]metric.AddOption)
1019 defer func() {
1020 *o = (*o)[:0]
1021 addOptPool.Put(o)
1022 }()
1023
1024 *o = append(
1025 *o,
1026 metric.WithAttributes(
1027 append(
1028 attrs,
1029 attribute.String("hw.id", id),
1030 attribute.String("hw.state", string(state)),
1031 attribute.String("hw.type", string(hwType)),
1032 )...,
1033 ),
1034 )
1035
1036 m.Int64UpDownCounter.Add(ctx, incr, *o...)
1037 }
1038
1039 // AddSet adds incr to the existing count for set.
1040 //
1041 // `hw.status` is currently specified as an *UpDownCounter* but would ideally be
1042 // represented using a [*StateSet* as defined in OpenMetrics]. This semantic
1043 // convention will be updated once *StateSet* is specified in OpenTelemetry. This
1044 // planned change is not expected to have any consequence on the way users query
1045 // their timeseries backend to retrieve the values of `hw.status` over time.
1046 //
1047 // [ [*StateSet* as defined in OpenMetrics]: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset
1048 func (m Status) AddSet(ctx context.Context, incr int64, set attribute.Set) {
1049 if set.Len() == 0 {
1050 m.Int64UpDownCounter.Add(ctx, incr)
1051 return
1052 }
1053
1054 o := addOptPool.Get().(*[]metric.AddOption)
1055 defer func() {
1056 *o = (*o)[:0]
1057 addOptPool.Put(o)
1058 }()
1059
1060 *o = append(*o, metric.WithAttributeSet(set))
1061 m.Int64UpDownCounter.Add(ctx, incr, *o...)
1062 }
1063
1064 // AttrName returns an optional attribute for the "hw.name" semantic convention.
1065 // It represents an easily-recognizable name for the hardware component.
1066 func (Status) AttrName(val string) attribute.KeyValue {
1067 return attribute.String("hw.name", val)
1068 }
1069
1070 // AttrParent returns an optional attribute for the "hw.parent" semantic
1071 // convention. It represents the unique identifier of the parent component
1072 // (typically the `hw.id` attribute of the enclosure, or disk controller).
1073 func (Status) AttrParent(val string) attribute.KeyValue {
1074 return attribute.String("hw.parent", val)
1075 }