diff --git a/.chloggen/add_container_cpu_usage.yaml b/.chloggen/add_container_cpu_usage.yaml new file mode 100755 index 0000000000..c1c4706b97 --- /dev/null +++ b/.chloggen/add_container_cpu_usage.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: container + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add container.cpu.usage metric + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1128] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index b09b4102e4..8a7e8aee67 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -49,6 +49,7 @@ body: - area:gen-ai - area:go - area:graphql + - area:hardware - area:heroku - area:host - area:http diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index e30d0a4630..d924b6fe58 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -41,6 +41,7 @@ body: - area:gen-ai - area:go - area:graphql + - area:hardware - area:heroku - area:host - area:http diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 8301d9b1bc..ca0f864b07 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -50,6 +50,7 @@ body: - area:gen-ai - area:go - area:graphql + - area:hardware - area:heroku - area:host - area:http diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 003b21c5b4..f4a53171a0 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -61,6 +61,7 @@ Currently, the following namespaces exist: - [Gen AI](gen-ai.md) - [Go](go.md) - [GraphQL](graphql.md) +- [Hardware](hardware.md) - [Heroku](heroku.md) - [Host](host.md) - [HTTP](http.md) diff --git a/docs/attributes-registry/hardware.md b/docs/attributes-registry/hardware.md new file mode 100644 index 0000000000..84f4042f4c --- /dev/null +++ b/docs/attributes-registry/hardware.md @@ -0,0 +1,48 @@ + + + + + +# Hardware + +## Hardware Attributes + +Attributes for hardware. + +| Attribute | Type | Description | Examples | Stability | +| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------- | +| `hw.id` | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hw.name` | string | An easily-recognizable name for the hardware component | `eth0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hw.parent` | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hw.state` | string | The current state of the component | `ok`; `degraded`; `failed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hw.type` | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`. + +`hw.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `degraded` | Degraded | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failed` | Failed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ok` | Ok | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`hw.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------------- | --------------- | ---------------------------------------------------------------- | +| `battery` | Battery | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/README.md b/docs/database/README.md index 0225729a31..7fcb8d42a8 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -15,7 +15,7 @@ database metrics and logs. > **Warning** > Existing database instrumentations that are using > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/README.md) -> (or prior) SHOULD NOT change the version of the database conventions that they emit +> (or prior) SHOULD NOT change the version of the database conventions that they emit by default > until a transition plan to the (future) stable semantic conventions has been published. > Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index be65ba773e..18940ece55 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -12,7 +12,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a ## Attributes - + diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 593d42fb42..5b597c30ef 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -15,7 +15,7 @@ extend and override the [Database Semantic Conventions](database-spans.md). Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created. - + diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index f72458104b..6e2bf13444 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -12,7 +12,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o ## Attributes - + diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index a5fbffe387..7587bf0f1e 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -36,7 +36,7 @@ and attributes but more may be added in the future. > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) > (or prior): > -> * SHOULD NOT change the version of the database conventions that they emit +> * SHOULD NOT change the version of the database conventions that they emit by default > until the database semantic conventions are marked stable. > Conventions include, but are not limited to, attributes, > metric and span names, and unit of measure. @@ -91,7 +91,7 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. - + @@ -234,7 +234,7 @@ This metric is [required][MetricRequired]. - + @@ -280,7 +280,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -318,7 +318,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -356,7 +356,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -394,7 +394,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -432,7 +432,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -470,7 +470,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -508,7 +508,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -546,7 +546,7 @@ This metric is [recommended][MetricRecommended]. - + diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index f3240fbe3b..66e1b3c297 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -24,7 +24,7 @@ linkTitle: Client Calls > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) > (or prior): > -> * SHOULD NOT change the version of the database conventions that they emit +> * SHOULD NOT change the version of the database conventions that they emit by default > until the database semantic conventions are marked stable. > Conventions include, but are not limited to, attributes, > metric and span names, and unit of measure. @@ -81,7 +81,7 @@ For example, for an operation describing SQL query on an anonymous table like `S These attributes will usually be the same for all operations performed over the same database connection. - + diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 8ebadbaa4d..3fc7cae64c 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -16,7 +16,7 @@ The **span name** follows the [general database span name guidelines](database-s ## Attributes - + diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 1fc8c19d91..c6cac4340f 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -12,7 +12,7 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr ## Attributes - + diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index ff514fc0fe..6063a4678a 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -12,7 +12,7 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over ## Attributes - + diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 50460220d2..75ba20ccdf 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -12,7 +12,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the ## Attributes - + diff --git a/docs/database/redis.md b/docs/database/redis.md index 501a239ed5..f6441b7d8c 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -12,7 +12,7 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the ## Attributes - + diff --git a/docs/database/sql.md b/docs/database/sql.md index 7a2b57f3e0..bca96789ce 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -36,7 +36,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co ## Attributes - + diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md index 321abb8bf2..8674fe5127 100644 --- a/docs/dns/dns-metrics.md +++ b/docs/dns/dns-metrics.md @@ -44,7 +44,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 97670b2209..31ddd6d35e 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -53,7 +53,7 @@ All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter. - + @@ -112,7 +112,7 @@ Exceptions Metric is reported by the `Microsoft.AspNetCore.Diagnostics` meter. - + @@ -199,7 +199,7 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting - + @@ -247,7 +247,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -291,7 +291,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -339,7 +339,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -399,7 +399,7 @@ Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 - + diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 8135deddf7..d1503e3ccb 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -53,7 +53,7 @@ In case instrumentation does not recognize `EndPoint` implementation, it sets th - + @@ -133,7 +133,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. - + @@ -227,7 +227,7 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 - + @@ -303,7 +303,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. - + @@ -379,7 +379,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. - + @@ -463,7 +463,7 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 - + @@ -543,7 +543,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -630,7 +630,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. - + diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index d73605e843..65b1177694 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -42,7 +42,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. - + @@ -101,7 +101,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. - + diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 0c3aeb95f0..ca12e9f410 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -46,7 +46,7 @@ The following metrics are recorded by the FaaS instance. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -66,7 +66,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -99,7 +99,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -119,7 +119,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -168,7 +168,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -217,7 +217,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -266,7 +266,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -315,7 +315,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -364,7 +364,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -397,7 +397,7 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -417,7 +417,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -466,7 +466,7 @@ This metric is [recommended][MetricRecommended]. - + diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index d7003732a8..0feaa47af0 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -38,7 +38,7 @@ Span `name` should be set to the function name being executed. Depending on the If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). - + @@ -196,7 +196,7 @@ The values reported by the client for the attributes listed below SHOULD be equa the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], which the invoked FaaS instance reports about itself, if it's instrumented. - + @@ -248,7 +248,7 @@ This section describes how to handle the span creation and additional attributes A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write. FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes. - + diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index d680380b16..ca2de8ba31 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -62,7 +62,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64 - + @@ -152,7 +152,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [ 0.01, 0.02, - + @@ -252,7 +252,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of - + @@ -352,7 +352,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of - + @@ -439,7 +439,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of - + diff --git a/docs/general/attributes.md b/docs/general/attributes.md index cb3f3360ca..a1ce082ad6 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -208,7 +208,7 @@ Destination fields capture details about the receiver of a network exchange/pack Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed if they do not cause breaking changes to HTTP semantic conventions. - + @@ -306,7 +306,7 @@ Note that `network.local.*` attributes are not included in these examples since #### Network connection and carrier attributes - + diff --git a/docs/general/logs.md b/docs/general/logs.md index e96129e123..b43357fdaf 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -96,7 +96,7 @@ As such, these should be recorded as Log Record attributes when applicable. They **Description:** The I/O stream to which the log was emitted. - + diff --git a/docs/general/trace-compatibility.md b/docs/general/trace-compatibility.md index be01272f81..2aa617fc8f 100644 --- a/docs/general/trace-compatibility.md +++ b/docs/general/trace-compatibility.md @@ -24,7 +24,7 @@ with one of the accepted values, describing the direct causal relationships between a child Span and a parent Span, as defined by [OpenTracing](https://github.com/opentracing/specification/blob/master/specification.md). - + diff --git a/docs/graphql/graphql-spans.md b/docs/graphql/graphql-spans.md index ade0325cfc..ed193571b3 100644 --- a/docs/graphql/graphql-spans.md +++ b/docs/graphql/graphql-spans.md @@ -14,7 +14,7 @@ The **span name** MUST be of the format ` `. When `` is not available, `GraphQL Operation` MAY be used as span name. - + diff --git a/docs/hardware/README.md b/docs/hardware/README.md new file mode 100644 index 0000000000..6b7f098cbe --- /dev/null +++ b/docs/hardware/README.md @@ -0,0 +1,17 @@ + + +# Semantic Conventions for Hardware + +**Status**: [Experimental][DocumentStatus] + +This document describes instruments and attributes for common hardware level +metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) +when creating instruments not explicitly defined in the specification. + +Semantic conventions for hardware are defined as following: + +* [Common Hardware Metrics](common.md): Semantic Conventions for *common* hardware metrics. + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/hardware/common.md b/docs/hardware/common.md new file mode 100644 index 0000000000..050f91086d --- /dev/null +++ b/docs/hardware/common.md @@ -0,0 +1,362 @@ + + +# Semantic Conventions for Common Hardware Metrics + +**Status**: [Experimental][DocumentStatus] + + + +- [Common hardware metrics](#common-hardware-metrics) + - [Metric: `hw.energy`](#metric-hwenergy) + - [Metric: `hw.errors`](#metric-hwerrors) + - [Metric: `hw.power`](#metric-hwpower) + - [Metric: `hw.status`](#metric-hwstatus) + + + +Hardware metrics do not include attributes that identify the device, machine, or host they are reported for. This +information is expected to be provided via resource attributes configured by user applications. +Application developers are encouraged to configure [Host](/docs/resource/host.md) resource attributes. + +## Common hardware metrics + +The below metrics apply to any type of hardware component. + +These common `hw.` metrics include the below attributes to describe the +monitored component: + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`. + + + +`hw.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `battery` | Battery | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `hw.energy` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `hw.energy` | Counter | `J` | Energy consumed by the component | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`. + + + +`hw.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `battery` | Battery | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `hw.errors` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | The type of error encountered by the component [2] | `uncorrected`; `zero_buffer_credit`; `crc`; `bad_sector` | `Conditionally Required` if and only if an error has occurred | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`. + +**[2]:** The `error.type` SHOULD match the error code reported by the component, the canonical name of the error, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. + + + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`hw.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `battery` | Battery | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `hw.power` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `hw.power` | Gauge | `W` | Instantaneous power consumed by the component [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** It is recommended to report `hw.energy` instead of `hw.power` when possible. + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`. + + + +`hw.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `battery` | Battery | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `hw.status` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `hw.status` | UpDownCounter | `1` | Operational status: `1` (true) or `0` (false) for each of the possible states [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a [*StateSet* as defined in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.state`](/docs/attributes-registry/hardware.md) | string | The current state of the component | `ok`; `degraded`; `failed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`. + + + +`hw.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `degraded` | Degraded | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failed` | Failed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ok` | Ok | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +`hw.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `battery` | Battery | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/http/README.md b/docs/http/README.md index 4d344d1408..61c0beba0f 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -18,7 +18,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking conventions that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit by default > until the HTTP semantic conventions are marked stable (HTTP stabilization will > include stabilization of a core set of networking conventions which are also used > in HTTP instrumentations). Conventions include, but are not limited to, attributes, diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 648dd36fce..1a00e406cf 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -35,7 +35,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking conventions that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit by default > until the HTTP semantic conventions are marked stable (HTTP stabilization will > include stabilization of a core set of networking conventions which are also used > in HTTP instrumentations). Conventions include, but are not limited to, attributes, @@ -85,7 +85,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -209,7 +209,7 @@ This metric is optional. - + @@ -297,7 +297,7 @@ This metric is optional. - + @@ -425,7 +425,7 @@ This metric is optional. - + @@ -557,7 +557,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -654,7 +654,7 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro Instrumentations MAY allow users to enable additional experimental attributes. - + @@ -700,7 +700,7 @@ This metric is optional. - + @@ -819,7 +819,7 @@ This metric is optional. - + @@ -934,7 +934,7 @@ This metric is optional. - + @@ -997,7 +997,7 @@ This metric is optional. - + @@ -1049,7 +1049,7 @@ This metric is optional. - + diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index fff997646d..8ad95e8097 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -43,7 +43,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking conventions that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit by default > until the HTTP semantic conventions are marked stable (HTTP stabilization will > include stabilization of a core set of networking conventions which are also used > in HTTP instrumentations). Conventions include, but are not limited to, attributes, @@ -133,7 +133,7 @@ This span type represents an outbound HTTP request. There are two ways this can For an HTTP client span, `SpanKind` MUST be `Client`. - + @@ -276,7 +276,7 @@ and SHOULD be provided **at span creation time** (if provided at all): Instrumentations MAY allow users to enable additional experimental attributes. - + @@ -381,7 +381,7 @@ This span type represents an inbound HTTP request. For an HTTP server span, `SpanKind` MUST be `Server`. - + @@ -543,7 +543,7 @@ and SHOULD be provided **at span creation time** (if provided at all): Instrumentations MAY allow users to enable additional experimental attributes. - + diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index c9286a02b6..8077d03b5c 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -14,7 +14,7 @@ The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pub For Google Cloud Pub/Sub, the following additional attributes are defined: - + diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 2964be5d02..5890dcac3f 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -22,7 +22,7 @@ The Semantic Conventions for [Apache Kafka](https://kafka.apache.org/) extend an For Apache Kafka, the following additional attributes are defined: - + diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index f3fcc190c1..25c6a275ef 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -19,7 +19,7 @@ > **Warning** > Existing messaging instrumentations that are using > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-metrics.md) -> (or prior) SHOULD NOT change the version of the messaging conventions that they emit +> (or prior) SHOULD NOT change the version of the messaging conventions that they emit by default > until a transition plan to the (future) stable semantic conventions has been published. > Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. @@ -32,7 +32,7 @@ When this metric is reported alongside a messaging span, the metric value SHOULD This metric is [required][MetricRequired]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -56,7 +56,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + @@ -186,7 +186,7 @@ This metric is [required][MetricRequired]. - + @@ -297,7 +297,7 @@ The metric SHOULD be reported once per message delivery. For example, if receivi - + @@ -393,7 +393,7 @@ When this metric is reported alongside a messaging process span, the metric valu This metric is [required][MetricRequired] for push-based message delivery and is [recommended][MetricRecommended] for processing operations instrumented for pull-based scenarios. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -417,7 +417,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 - + diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 7ab86ffcda..7f5b431983 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -37,7 +37,7 @@ > **Warning** > Existing messaging instrumentations that are using > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-spans.md) -> (or prior) SHOULD NOT change the version of the messaging conventions that they emit +> (or prior) SHOULD NOT change the version of the messaging conventions that they emit by default > until a transition plan to the (future) stable semantic conventions has been published. > Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. @@ -286,7 +286,7 @@ Messaging attributes are organized into the following namespaces: Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace. - + diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 3648280e3e..20ad57d91c 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -15,7 +15,7 @@ The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and ov In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. `messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used. - + diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 6317f0cc3c..48741ebd08 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -14,7 +14,7 @@ The Semantic Conventions for [Apache RocketMQ](https://rocketmq.apache.org/) ext Specific attributes for Apache RocketMQ are defined below. - + diff --git a/docs/mobile/events.md b/docs/mobile/events.md index 32b8a9313f..55fa24d735 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -29,7 +29,7 @@ NOT be used together, each field MUST be used with its corresponding ### Event details - + diff --git a/docs/resource/README.md b/docs/resource/README.md index 245f66d0c2..78770202e6 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -180,7 +180,7 @@ service.name = Shop.shoppingcart **Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries. - + diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md index d0d7add6b1..df00ed8fad 100644 --- a/docs/resource/cloud-provider/aws/ecs.md +++ b/docs/resource/cloud-provider/aws/ecs.md @@ -6,7 +6,7 @@ **Description:** Resources used by AWS Elastic Container Service (ECS). - + diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index 8575d47771..4af0bb8176 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -6,7 +6,7 @@ **Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). - + diff --git a/docs/resource/host.md b/docs/resource/host.md index 135700eec9..77689d5ca1 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -9,7 +9,7 @@ The `host.*` namespace SHOULD be exclusively used to capture resource attributes. To report host metrics, the `system.*` namespace SHOULD be used. - + diff --git a/docs/resource/os.md b/docs/resource/os.md index 59ebd6f077..ec10c53b5e 100644 --- a/docs/resource/os.md +++ b/docs/resource/os.md @@ -8,7 +8,7 @@ In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host. - + diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 1832afff47..9cef88eba1 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -16,7 +16,7 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements. - + diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 84d25b0927..258f19ddea 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -16,7 +16,7 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server gRPC measurements. - + diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index 18788fd715..152c87bdba 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -14,7 +14,7 @@ described on this page. `rpc.system` MUST be set to `"jsonrpc"`. - + diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 1642389989..054ac58e9a 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -40,7 +40,7 @@ metrics can be filtered for finer grain analysis. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md) > (or prior): > -> * SHOULD NOT change the version of the networking conventions that they emit +> * SHOULD NOT change the version of the networking conventions that they emit by default > until the HTTP semantic conventions are marked stable (HTTP stabilization will > include stabilization of a core set of networking conventions which are also used > in RPC instrumentations). Conventions include, but are not limited to, attributes, @@ -346,7 +346,7 @@ This metric is [recommended][MetricRecommended]. Below is a table of attributes that SHOULD be included on client and server RPC measurements. - + diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 0595583160..c6ea777e00 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -29,7 +29,7 @@ This document defines how to describe remote procedure calls > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md) > (or prior): > -> * SHOULD NOT change the version of the networking conventions that they emit +> * SHOULD NOT change the version of the networking conventions that they emit by default > until the HTTP semantic conventions are marked stable (HTTP stabilization will > include stabilization of a core set of networking conventions which are also used > in RPC instrumentations). Conventions include, but are not limited to, attributes, @@ -94,7 +94,7 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service ### Client attributes - + @@ -171,7 +171,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ### Server attributes - + @@ -258,7 +258,7 @@ In the lifetime of an RPC stream, an event for each message sent/received on client and server spans SHOULD be created. In case of unary calls only one sent and one received message will be recorded for both client and server spans. - + diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index f39ec75aa9..a3c077dc6e 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -60,7 +60,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -114,7 +114,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -152,7 +152,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -190,7 +190,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -232,7 +232,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -274,7 +274,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -316,7 +316,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -358,7 +358,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -400,7 +400,7 @@ This metric is [recommended][MetricRecommended]. - + diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 5b111aad90..5355deee9e 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -67,7 +67,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle - + @@ -119,7 +119,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle - + @@ -171,7 +171,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle - + @@ -223,7 +223,7 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d - + @@ -286,7 +286,7 @@ of `[ 0.01, 0.1, 1, 10 ]`. - + @@ -345,7 +345,7 @@ Note that this is the number of platform threads (as opposed to virtual threads) - + @@ -403,7 +403,7 @@ This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](h - + @@ -438,7 +438,7 @@ This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](http - + @@ -473,7 +473,7 @@ This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https: - + @@ -516,7 +516,7 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https: - + @@ -552,7 +552,7 @@ Note that this is always an integer value (i.e. fractional or millicores are not - + @@ -593,7 +593,7 @@ Note that the JVM does not provide a definition of what "recent" means. - + @@ -634,7 +634,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle - + @@ -691,7 +691,7 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https:/ - + @@ -730,7 +730,7 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht - + @@ -765,7 +765,7 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o - + @@ -808,7 +808,7 @@ This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://doc - + @@ -851,7 +851,7 @@ This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle - + diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md index 60fcd283af..5d01a28341 100644 --- a/docs/runtime/nodejs-metrics.md +++ b/docs/runtime/nodejs-metrics.md @@ -59,7 +59,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -97,7 +97,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -135,7 +135,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -173,7 +173,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -211,7 +211,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -249,7 +249,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -287,7 +287,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -325,7 +325,7 @@ This metric is [recommended][MetricRecommended]. - + diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md index d8b4e07a65..32cf995059 100644 --- a/docs/runtime/v8js-metrics.md +++ b/docs/runtime/v8js-metrics.md @@ -56,7 +56,7 @@ of `[ 0.01, 0.1, 1, 10 ]`. - + @@ -108,7 +108,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -165,7 +165,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -222,7 +222,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -279,7 +279,7 @@ This metric is [recommended][MetricRecommended]. - + diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md index b0fb198f21..c9c6a4b2c7 100644 --- a/docs/system/container-metrics.md +++ b/docs/system/container-metrics.md @@ -8,6 +8,10 @@ linkTitle: Container ## Container Metrics +This document describes instruments and attributes for common container level +metrics in OpenTelemetry. These metrics are collected from technology-specific, +well-defined APIs (e.g. Kubelet's API or container runtimes). + ### Metric: `container.cpu.time` This metric is [opt-in][MetricOptIn]. @@ -33,7 +37,7 @@ This metric is [opt-in][MetricOptIn]. - + @@ -42,10 +46,74 @@ This metric is [opt-in][MetricOptIn]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Following states SHOULD be used: `user`, `system`, `kernel` +**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API. + + + +`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `container.cpu.usage` + +This metric is [opt-in][MetricOptIn]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `container.cpu.usage` | Gauge | `{cpu}` | Container's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** CPU usage of the specific container on all available CPU cores, averaged over the sample window + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Following states SHOULD be used: `user`, `system`, `kernel` + +**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API. + `cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -93,7 +161,7 @@ This metric is [opt-in][MetricOptIn]. - + @@ -131,7 +199,7 @@ This metric is [opt-in][MetricOptIn]. - + @@ -182,7 +250,7 @@ This metric is [opt-in][MetricOptIn]. - + diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index 76e69590ee..a7b7039cc1 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -10,11 +10,16 @@ This document describes instruments and attributes for common hardware level metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. - +This document is being converted to specific hardware metrics, parts of this document that have already been +converted are now located in the [Hardware] (/docs/hardware/README.md) folder and are no longer present in this file. -- [Common hardware attributes](#common-hardware-attributes) +Please note that this is an [ongoing process](https://github.com/open-telemetry/semantic-conventions/issues/1309) and may take some time to complete. + + + +- [Common hardware attributes](/docs/attributes-registry/hardware.md) - [Metric Instruments](#metric-instruments) - - [`hw.` - Common hardware metrics](#hw---common-hardware-metrics) + - [`hw.` - Common hardware metrics](/docs/hardware/common.md) - [`hw.host.` - Physical host metrics](#hwhost---physical-host-metrics) - [`hw.battery.` - Battery metrics](#hwbattery---battery-metrics) - [`hw.cpu.` - Physical processor metrics](#hwcpu---physical-processor-metrics) @@ -31,8 +36,6 @@ when creating instruments not explicitly defined in the specification. - [`hw.temperature.` - Temperature sensor metrics](#hwtemperature---temperature-sensor-metrics) - [`hw.voltage.` - Voltage sensor metrics](#hwvoltage---voltage-sensor-metrics) - - > **Warning** > Existing instrumentations and collector that are using > [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/hardware-metrics.md) @@ -44,43 +47,8 @@ when creating instruments not explicitly defined in the specification. > * SHOULD introduce a control mechanism to allow users to opt-in to the new > conventions once the migration plan is finalized. -## Common hardware attributes - -All metrics in `hw.` instruments should be attached to a [Host Resource](/docs/resource/host.md) -and therefore inherit its attributes, like `host.id` and `host.name`. - -Additionally, all metrics in `hw.` instruments have the following attributes: - -| Attribute Key | Description | Example | Requirement Level | -| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- | -| `id` | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | **Required** | -| `name` | An easily-recognizable name for the hardware component | `eth0` | Recommended | -| `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Recommended | - ## Metric Instruments -### `hw.` - Common hardware metrics - -The below metrics apply to any type of hardware component. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ----------- | ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | -------------------------- | -| `hw.energy` | Energy consumed by the component, in joules | J | Counter | Int64 | | | -| `hw.errors` | Number of errors encountered by the component | {error} | Counter | Int64 | `hw.error.type` (Recommended) | | -| `hw.power` | Instantaneous power consumed by the component, in Watts (`hw.energy` is preferred) | W | Gauge | Double | | | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | - -These common `hw.` metrics must include the below attributes to describe the -monitored component: - -| Attribute Key | Description | Example | Requirement Level | -| ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -| `hw.type` | Type of the component | `battery`, `cpu`, `disk_controller`, `enclosure`, `fan`, `gpu`, `logical_disk`, `memory`, `network`, `physical_disk`, `power_supply`, `tape_drive`, `temperature`, `voltage` | **Required** | - -> **Warning** -> -> `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a [*StateSet* as defined in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. - ### `hw.host.` - Physical host metrics **Description:** Physical system as opposed to a virtual system or a container. diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 6912ec1a93..4f9dfc41e9 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -67,7 +67,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -123,7 +123,7 @@ This metric is [opt-in][MetricOptIn]. - + @@ -179,7 +179,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -213,7 +213,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -247,7 +247,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -293,7 +293,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -339,7 +339,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -373,7 +373,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -407,7 +407,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -453,7 +453,7 @@ This metric is [recommended][MetricRecommended]. - + diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index cb11264f6e..a2c8633899 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -96,7 +96,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -153,7 +153,7 @@ This metric is [opt-in][MetricOptIn]. - + @@ -210,7 +210,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -244,7 +244,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -278,7 +278,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -326,7 +326,7 @@ available on the system, that is `system.memory.limit`. - + @@ -378,7 +378,7 @@ This metric is [opt-in][MetricOptIn]. - + @@ -417,7 +417,7 @@ This metric is [opt-in][MetricOptIn]. - + @@ -451,7 +451,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -503,7 +503,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -549,7 +549,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -595,7 +595,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -641,7 +641,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -700,7 +700,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -747,7 +747,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -803,7 +803,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -848,7 +848,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -895,7 +895,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -946,7 +946,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1009,7 +1009,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1084,7 +1084,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1131,7 +1131,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1186,7 +1186,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1233,7 +1233,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1280,7 +1280,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1361,7 +1361,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1409,7 +1409,7 @@ This metric is [recommended][MetricRecommended]. - + @@ -1508,7 +1508,7 @@ See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding- - + diff --git a/model/hardware-common.yaml b/model/hardware-common.yaml new file mode 100644 index 0000000000..6abf99809a --- /dev/null +++ b/model/hardware-common.yaml @@ -0,0 +1,12 @@ +groups: + - id: hardware.attributes.common + type: attribute_group + stability: experimental + brief: 'Common hardware attributes' + attributes: + - ref: hw.id + requirement_level: required + - ref: hw.name + requirement_level: recommended + - ref: hw.parent + requirement_level: recommended diff --git a/model/metrics/container.yaml b/model/metrics/container.yaml index 94adad2921..7db120f528 100644 --- a/model/metrics/container.yaml +++ b/model/metrics/container.yaml @@ -13,7 +13,24 @@ groups: - ref: cpu.mode brief: "The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels." note: "Following states SHOULD be used: `user`, `system`, `kernel`" - requirement_level: opt_in + requirement_level: + conditionally_required: Required if mode is available, i.e. metrics coming from the Docker Stats API. + + - id: metric.container.cpu.usage + type: metric + metric_name: container.cpu.usage + stability: experimental + brief: "Container's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs" + note: > + CPU usage of the specific container on all available CPU cores, averaged over the sample window + instrument: gauge + unit: "{cpu}" + attributes: + - ref: cpu.mode + brief: "The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels." + note: "Following states SHOULD be used: `user`, `system`, `kernel`" + requirement_level: + conditionally_required: Required if mode is available, i.e. metrics coming from the Docker Stats API. # container.memory.* metrics and attribute group - id: metric.container.memory.usage diff --git a/model/metrics/hardware/common.yaml b/model/metrics/hardware/common.yaml new file mode 100644 index 0000000000..b975f53e18 --- /dev/null +++ b/model/metrics/hardware/common.yaml @@ -0,0 +1,65 @@ +groups: + # COMMON METRICS + - id: metric.hardware.attributes + type: attribute_group + brief: "Attributes for hardware metrics" + extends: hardware.attributes.common + attributes: + - ref: hw.type + requirement_level: required + + - id: metric.hardware.energy + type: metric + metric_name: hw.energy + stability: experimental + brief: "Energy consumed by the component" + instrument: counter + unit: "J" + extends: metric.hardware.attributes + + - id: metric.hardware.errors + type: metric + metric_name: hw.errors + stability: experimental + brief: "Number of errors encountered by the component" + instrument: counter + unit: "{error}" + extends: metric.hardware.attributes + attributes: + - ref: error.type + brief: "The type of error encountered by the component" + examples: ['uncorrected', 'zero_buffer_credit', 'crc', 'bad_sector'] + requirement_level: + conditionally_required: if and only if an error has occurred + note: > + The `error.type` SHOULD match the error code reported by the component, the canonical name of the error, + or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. + + - id: metric.hardware.power + type: metric + metric_name: hw.power + stability: experimental + brief: "Instantaneous power consumed by the component" + note: > + It is recommended to report `hw.energy` instead of `hw.power` when possible. + instrument: gauge + unit: "W" + extends: metric.hardware.attributes + + - id: metric.hardware.status + type: metric + metric_name: hw.status + stability: experimental + brief: "Operational status: `1` (true) or `0` (false) for each of the possible states" + instrument: updowncounter + unit: "1" + extends: metric.hardware.attributes + note: > + `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a + [*StateSet* as defined in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset). + This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change + is not expected to have any consequence on the way users query their timeseries backend to retrieve the + values of `hw.status` over time. + attributes: + - ref: hw.state + requirement_level: required diff --git a/model/registry/hardware.yaml b/model/registry/hardware.yaml new file mode 100644 index 0000000000..248484b193 --- /dev/null +++ b/model/registry/hardware.yaml @@ -0,0 +1,108 @@ +groups: + - id: registry.hardware + type: attribute_group + brief: > + Attributes for hardware. + attributes: + - id: hw.id + type: string + stability: experimental + brief: > + An identifier for the hardware component, unique within the monitored host + examples: ['win32battery_battery_testsysa33_1'] + - id: hw.name + type: string + stability: experimental + brief: > + An easily-recognizable name for the hardware component + examples: ['eth0'] + - id: hw.parent + type: string + stability: experimental + brief: > + Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) + examples: ['dellStorage_perc_0'] + - id: hw.type + type: + members: + - id: battery + value: 'battery' + brief: "Battery" + stability: experimental + - id: cpu + value: 'cpu' + brief: 'CPU' + stability: experimental + - id: disk_controller + value: 'disk_controller' + brief: 'Disk controller' + stability: experimental + - id: enclosure + value: 'enclosure' + brief: 'Enclosure' + stability: experimental + - id: fan + value: 'fan' + brief: 'Fan' + stability: experimental + - id: gpu + value: 'gpu' + brief: 'GPU' + stability: experimental + - id: logical_disk + value: 'logical_disk' + brief: 'Logical disk' + stability: experimental + - id: memory + value: 'memory' + brief: 'Memory' + stability: experimental + - id: network + value: 'network' + brief: 'Network' + stability: experimental + - id: physical_disk + value: 'physical_disk' + brief: 'Physical disk' + stability: experimental + - id: power_supply + value: 'power_supply' + brief: 'Power supply' + stability: experimental + - id: tape_drive + value: 'tape_drive' + brief: 'Tape drive' + stability: experimental + - id: temperature + value: 'temperature' + brief: 'Temperature' + stability: experimental + - id: voltage + value: 'voltage' + brief: 'Voltage' + stability: experimental + stability: experimental + brief: > + Type of the component + note: > + Describes the category of the hardware component for which `hw.state` is being reported. For example, + `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware + component has been reported as `degraded`. + - id: hw.state + type: + members: + - id: ok + value: 'ok' + brief: "Ok" + stability: experimental + - id: degraded + value: 'degraded' + brief: 'Degraded' + stability: experimental + - id: failed + value: 'failed' + brief: 'Failed' + stability: experimental + stability: experimental + brief: > + The current state of the component diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index e57cd0f5ef..1bbfdf70a8 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -36,7 +36,6 @@ groups: Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. examples: ['MyQueue', 'MyTopic'] - tag: messaging-generic - id: messaging.destination.subscription.name type: string stability: experimental