# Copyright The OpenTelemetry Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from typing import (
Callable,
Final,
Generator,
Iterable,
Optional,
Sequence,
Union,
)
from opentelemetry.metrics import (
CallbackOptions,
Counter,
Meter,
ObservableGauge,
Observation,
UpDownCounter,
)
# pylint: disable=invalid-name
CallbackT = Union[
Callable[[CallbackOptions], Iterable[Observation]],
Generator[Iterable[Observation], CallbackOptions, None],
]
SYSTEM_CPU_FREQUENCY: Final = "system.cpu.frequency"
"""
Deprecated: Replaced by `cpu.frequency`.
"""
def create_system_cpu_frequency(
meter: Meter, callbacks: Optional[Sequence[CallbackT]]
) -> ObservableGauge:
"""Deprecated. Use `cpu.frequency` instead"""
return meter.create_observable_gauge(
name=SYSTEM_CPU_FREQUENCY,
callbacks=callbacks,
description="Deprecated. Use `cpu.frequency` instead.",
unit="{Hz}",
)
SYSTEM_CPU_LOGICAL_COUNT: Final = "system.cpu.logical.count"
"""
Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking
Instrument: updowncounter
Unit: {cpu}
Note: Calculated by multiplying the number of sockets by the number of cores per socket, and then by the number of threads per core.
"""
def create_system_cpu_logical_count(meter: Meter) -> UpDownCounter:
"""Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking"""
return meter.create_up_down_counter(
name=SYSTEM_CPU_LOGICAL_COUNT,
description="Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking",
unit="{cpu}",
)
SYSTEM_CPU_PHYSICAL_COUNT: Final = "system.cpu.physical.count"
"""
Reports the number of actual physical processor cores on the hardware
Instrument: updowncounter
Unit: {cpu}
Note: Calculated by multiplying the number of sockets by the number of cores per socket.
"""
def create_system_cpu_physical_count(meter: Meter) -> UpDownCounter:
"""Reports the number of actual physical processor cores on the hardware"""
return meter.create_up_down_counter(
name=SYSTEM_CPU_PHYSICAL_COUNT,
description="Reports the number of actual physical processor cores on the hardware",
unit="{cpu}",
)
SYSTEM_CPU_TIME: Final = "system.cpu.time"
"""
Deprecated: Replaced by `cpu.time`.
"""
def create_system_cpu_time(meter: Meter) -> Counter:
"""Deprecated. Use `cpu.time` instead"""
return meter.create_counter(
name=SYSTEM_CPU_TIME,
description="Deprecated. Use `cpu.time` instead.",
unit="s",
)
SYSTEM_CPU_UTILIZATION: Final = "system.cpu.utilization"
"""
Deprecated: Replaced by `cpu.utilization`.
"""
def create_system_cpu_utilization(
meter: Meter, callbacks: Optional[Sequence[CallbackT]]
) -> ObservableGauge:
"""Deprecated. Use `cpu.utilization` instead"""
return meter.create_observable_gauge(
name=SYSTEM_CPU_UTILIZATION,
callbacks=callbacks,
description="Deprecated. Use `cpu.utilization` instead.",
unit="1",
)
SYSTEM_DISK_IO: Final = "system.disk.io"
"""
Instrument: counter
Unit: By
"""
def create_system_disk_io(meter: Meter) -> Counter:
return meter.create_counter(
name=SYSTEM_DISK_IO,
description="",
unit="By",
)
SYSTEM_DISK_IO_TIME: Final = "system.disk.io_time"
"""
Time disk spent activated
Instrument: counter
Unit: s
Note: The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as:
- Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats)
- Windows: The complement of
["Disk\\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained)
performance counter: `uptime * (100 - "Disk\\% Idle Time") / 100`.
"""
def create_system_disk_io_time(meter: Meter) -> Counter:
"""Time disk spent activated"""
return meter.create_counter(
name=SYSTEM_DISK_IO_TIME,
description="Time disk spent activated",
unit="s",
)
SYSTEM_DISK_LIMIT: Final = "system.disk.limit"
"""
The total storage capacity of the disk
Instrument: updowncounter
Unit: By
"""
def create_system_disk_limit(meter: Meter) -> UpDownCounter:
"""The total storage capacity of the disk"""
return meter.create_up_down_counter(
name=SYSTEM_DISK_LIMIT,
description="The total storage capacity of the disk",
unit="By",
)
SYSTEM_DISK_MERGED: Final = "system.disk.merged"
"""
Instrument: counter
Unit: {operation}
"""
def create_system_disk_merged(meter: Meter) -> Counter:
return meter.create_counter(
name=SYSTEM_DISK_MERGED,
description="",
unit="{operation}",
)
SYSTEM_DISK_OPERATION_TIME: Final = "system.disk.operation_time"
"""
Sum of the time each operation took to complete
Instrument: counter
Unit: s
Note: Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as:
- Linux: Fields 7 & 11 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats)
- Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes).
"""
def create_system_disk_operation_time(meter: Meter) -> Counter:
"""Sum of the time each operation took to complete"""
return meter.create_counter(
name=SYSTEM_DISK_OPERATION_TIME,
description="Sum of the time each operation took to complete",
unit="s",
)
SYSTEM_DISK_OPERATIONS: Final = "system.disk.operations"
"""
Instrument: counter
Unit: {operation}
"""
def create_system_disk_operations(meter: Meter) -> Counter:
return meter.create_counter(
name=SYSTEM_DISK_OPERATIONS,
description="",
unit="{operation}",
)
SYSTEM_FILESYSTEM_LIMIT: Final = "system.filesystem.limit"
"""
The total storage capacity of the filesystem
Instrument: updowncounter
Unit: By
"""
def create_system_filesystem_limit(meter: Meter) -> UpDownCounter:
"""The total storage capacity of the filesystem"""
return meter.create_up_down_counter(
name=SYSTEM_FILESYSTEM_LIMIT,
description="The total storage capacity of the filesystem",
unit="By",
)
SYSTEM_FILESYSTEM_USAGE: Final = "system.filesystem.usage"
"""
Reports a filesystem's space usage across different states
Instrument: updowncounter
Unit: By
Note: The sum of all `system.filesystem.usage` values over the different `system.filesystem.state` attributes
SHOULD equal the total storage capacity of the filesystem, that is `system.filesystem.limit`.
"""
def create_system_filesystem_usage(meter: Meter) -> UpDownCounter:
"""Reports a filesystem's space usage across different states"""
return meter.create_up_down_counter(
name=SYSTEM_FILESYSTEM_USAGE,
description="Reports a filesystem's space usage across different states.",
unit="By",
)
SYSTEM_FILESYSTEM_UTILIZATION: Final = "system.filesystem.utilization"
"""
Instrument: gauge
Unit: 1
"""
def create_system_filesystem_utilization(
meter: Meter, callbacks: Optional[Sequence[CallbackT]]
) -> ObservableGauge:
return meter.create_observable_gauge(
name=SYSTEM_FILESYSTEM_UTILIZATION,
callbacks=callbacks,
description="",
unit="1",
)
SYSTEM_LINUX_MEMORY_AVAILABLE: Final = "system.linux.memory.available"
"""
An estimate of how much memory is available for starting new applications, without causing swapping
Instrument: updowncounter
Unit: By
Note: This is an alternative to `system.memory.usage` metric with `state=free`.
Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values.
This is supposed to be more accurate than just "free" memory.
For reference, see the calculations [here](https://superuser.com/a/980821).
See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
"""
def create_system_linux_memory_available(meter: Meter) -> UpDownCounter:
"""An estimate of how much memory is available for starting new applications, without causing swapping"""
return meter.create_up_down_counter(
name=SYSTEM_LINUX_MEMORY_AVAILABLE,
description="An estimate of how much memory is available for starting new applications, without causing swapping",
unit="By",
)
SYSTEM_LINUX_MEMORY_SLAB_USAGE: Final = "system.linux.memory.slab.usage"
"""
Reports the memory used by the Linux kernel for managing caches of frequently used objects
Instrument: updowncounter
Unit: By
Note: The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system.
Note that the total slab memory is not constant and may vary over time.
See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
"""
def create_system_linux_memory_slab_usage(meter: Meter) -> UpDownCounter:
"""Reports the memory used by the Linux kernel for managing caches of frequently used objects"""
return meter.create_up_down_counter(
name=SYSTEM_LINUX_MEMORY_SLAB_USAGE,
description="Reports the memory used by the Linux kernel for managing caches of frequently used objects.",
unit="By",
)
SYSTEM_MEMORY_LIMIT: Final = "system.memory.limit"
"""
Total memory available in the system
Instrument: updowncounter
Unit: By
Note: Its value SHOULD equal the sum of `system.memory.state` over all states.
"""
def create_system_memory_limit(meter: Meter) -> UpDownCounter:
"""Total memory available in the system"""
return meter.create_up_down_counter(
name=SYSTEM_MEMORY_LIMIT,
description="Total memory available in the system.",
unit="By",
)
SYSTEM_MEMORY_SHARED: Final = "system.memory.shared"
"""
Shared memory used (mostly by tmpfs)
Instrument: updowncounter
Unit: By
Note: Equivalent of `shared` from [`free` command](https://man7.org/linux/man-pages/man1/free.1.html) or
`Shmem` from [`/proc/meminfo`](https://man7.org/linux/man-pages/man5/proc.5.html)".
"""
def create_system_memory_shared(meter: Meter) -> UpDownCounter:
"""Shared memory used (mostly by tmpfs)"""
return meter.create_up_down_counter(
name=SYSTEM_MEMORY_SHARED,
description="Shared memory used (mostly by tmpfs).",
unit="By",
)
SYSTEM_MEMORY_USAGE: Final = "system.memory.usage"
"""
Reports memory in use by state
Instrument: updowncounter
Unit: By
Note: The sum over all `system.memory.state` values SHOULD equal the total memory
available on the system, that is `system.memory.limit`.
"""
def create_system_memory_usage(meter: Meter) -> UpDownCounter:
"""Reports memory in use by state"""
return meter.create_up_down_counter(
name=SYSTEM_MEMORY_USAGE,
description="Reports memory in use by state.",
unit="By",
)
SYSTEM_MEMORY_UTILIZATION: Final = "system.memory.utilization"
"""
Instrument: gauge
Unit: 1
"""
def create_system_memory_utilization(
meter: Meter, callbacks: Optional[Sequence[CallbackT]]
) -> ObservableGauge:
return meter.create_observable_gauge(
name=SYSTEM_MEMORY_UTILIZATION,
callbacks=callbacks,
description="",
unit="1",
)
SYSTEM_NETWORK_CONNECTIONS: Final = "system.network.connections"
"""
Instrument: updowncounter
Unit: {connection}
"""
def create_system_network_connections(meter: Meter) -> UpDownCounter:
return meter.create_up_down_counter(
name=SYSTEM_NETWORK_CONNECTIONS,
description="",
unit="{connection}",
)
SYSTEM_NETWORK_DROPPED: Final = "system.network.dropped"
"""
Count of packets that are dropped or discarded even though there was no error
Instrument: counter
Unit: {packet}
Note: Measured as:
- Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html))
- Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2)
from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2).
"""
def create_system_network_dropped(meter: Meter) -> Counter:
"""Count of packets that are dropped or discarded even though there was no error"""
return meter.create_counter(
name=SYSTEM_NETWORK_DROPPED,
description="Count of packets that are dropped or discarded even though there was no error",
unit="{packet}",
)
SYSTEM_NETWORK_ERRORS: Final = "system.network.errors"
"""
Count of network errors detected
Instrument: counter
Unit: {error}
Note: Measured as:
- Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)).
- Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2)
from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2).
"""
def create_system_network_errors(meter: Meter) -> Counter:
"""Count of network errors detected"""
return meter.create_counter(
name=SYSTEM_NETWORK_ERRORS,
description="Count of network errors detected",
unit="{error}",
)
SYSTEM_NETWORK_IO: Final = "system.network.io"
"""
Instrument: counter
Unit: By
"""
def create_system_network_io(meter: Meter) -> Counter:
return meter.create_counter(
name=SYSTEM_NETWORK_IO,
description="",
unit="By",
)
SYSTEM_NETWORK_PACKETS: Final = "system.network.packets"
"""
Instrument: counter
Unit: {packet}
"""
def create_system_network_packets(meter: Meter) -> Counter:
return meter.create_counter(
name=SYSTEM_NETWORK_PACKETS,
description="",
unit="{packet}",
)
SYSTEM_PAGING_FAULTS: Final = "system.paging.faults"
"""
Instrument: counter
Unit: {fault}
"""
def create_system_paging_faults(meter: Meter) -> Counter:
return meter.create_counter(
name=SYSTEM_PAGING_FAULTS,
description="",
unit="{fault}",
)
SYSTEM_PAGING_OPERATIONS: Final = "system.paging.operations"
"""
Instrument: counter
Unit: {operation}
"""
def create_system_paging_operations(meter: Meter) -> Counter:
return meter.create_counter(
name=SYSTEM_PAGING_OPERATIONS,
description="",
unit="{operation}",
)
SYSTEM_PAGING_USAGE: Final = "system.paging.usage"
"""
Unix swap or windows pagefile usage
Instrument: updowncounter
Unit: By
"""
def create_system_paging_usage(meter: Meter) -> UpDownCounter:
"""Unix swap or windows pagefile usage"""
return meter.create_up_down_counter(
name=SYSTEM_PAGING_USAGE,
description="Unix swap or windows pagefile usage",
unit="By",
)
SYSTEM_PAGING_UTILIZATION: Final = "system.paging.utilization"
"""
Instrument: gauge
Unit: 1
"""
def create_system_paging_utilization(
meter: Meter, callbacks: Optional[Sequence[CallbackT]]
) -> ObservableGauge:
return meter.create_observable_gauge(
name=SYSTEM_PAGING_UTILIZATION,
callbacks=callbacks,
description="",
unit="1",
)
SYSTEM_PROCESS_COUNT: Final = "system.process.count"
"""
Total number of processes in each state
Instrument: updowncounter
Unit: {process}
"""
def create_system_process_count(meter: Meter) -> UpDownCounter:
"""Total number of processes in each state"""
return meter.create_up_down_counter(
name=SYSTEM_PROCESS_COUNT,
description="Total number of processes in each state",
unit="{process}",
)
SYSTEM_PROCESS_CREATED: Final = "system.process.created"
"""
Total number of processes created over uptime of the host
Instrument: counter
Unit: {process}
"""
def create_system_process_created(meter: Meter) -> Counter:
"""Total number of processes created over uptime of the host"""
return meter.create_counter(
name=SYSTEM_PROCESS_CREATED,
description="Total number of processes created over uptime of the host",
unit="{process}",
)
SYSTEM_UPTIME: Final = "system.uptime"
"""
The time the system has been running
Instrument: gauge
Unit: s
Note: Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available.
The actual accuracy would depend on the instrumentation and operating system.
"""
def create_system_uptime(
meter: Meter, callbacks: Optional[Sequence[CallbackT]]
) -> ObservableGauge:
"""The time the system has been running"""
return meter.create_observable_gauge(
name=SYSTEM_UPTIME,
callbacks=callbacks,
description="The time the system has been running",
unit="s",
)
