open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Moved general semantic conventions markdown to a topic folder. (#143)

This commit is contained in:
Alexander Wert 2023-06-30 18:20:14 +02:00 committed by GitHub
parent 01312085ed
commit 2d1ea6bb64
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 519 additions and 526 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.github/CODEOWNERS vendored
View File

@ -20,8 +20,10 @@
/internal/tools/schema_check.sh @open-telemetry/specs-semconv-approvers @tigrannajaryan
# Logs semantic conventions
/semantic_conventions/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan
/specification/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan
/semantic_conventions/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan
/specification/general/events-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
/specification/general/logs-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
/specification/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan
# JVM semantic conventions approvers
/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers

7
README.md
View File

@ -9,12 +9,7 @@ This repository is currently using [this specification version][SpecificationVer
## Read the docs
The documentation currently resides in the previous folders, e.g.
- [Resource](specification/resource/semantic_conventions/README.md)
- [Trace](specification/trace/semantic_conventions/README.md)
- [Metrics](specification/metrics/semantic_conventions/README.md)
- [Logs](specification/logs/semantic_conventions/README.md)
The documentation currently resides in the [specification](specification/README.md) folder.
## TODOs

7
semantic_conventions/README.md
View File

@ -5,12 +5,7 @@ be used by the various OpenTelemetry language implementations to aid in automati
generation of semantics-related code.
⚠ If you want to read the semantic conventions and not edit them, please see
the generated markdown output under `/specification/*/semantic_conventions/`,
i.e.:
* [Trace semantic conventions](../specification/trace/semantic_conventions/README.md)
* [Metric semantic conventions](../specification/metrics/semantic_conventions/README.md)
* [Resource semantic conventions](../specification/resource/semantic_conventions/README.md)
the generated markdown output in the [specification](../specification/README.md) folder.
## Writing semantic conventions

2
semantic_conventions/resource/faas.yaml
View File

@ -14,7 +14,7 @@ groups:
This is the name of the function as configured/deployed on the FaaS
platform and is usually different from the name of the callback
function (which may be stored in the
[`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes)
[`code.namespace`/`code.function`](/specification/general/general-attributes.md#source-code-attributes)
span attributes).
For some cloud providers, the above definition is ambiguous. The following

2
semantic_conventions/trace/general.yaml
View File

@ -170,7 +170,7 @@ groups:
- id: service
type: string
brief: >
The [`service.name`](../../resource/semantic_conventions/README.md#service)
The [`service.name`](/specification/resource/semantic_conventions/README.md#service)
of the remote service. SHOULD be equal to the actual `service.name`
resource attribute of the remote service if any.
examples: "AuthTokenCache"

8
specification/README.md
View File

@ -6,12 +6,14 @@ The benefit to using Semantic Conventions is in following a common naming scheme
Semantic Conventions are defined for the following areas:
* [General](general/README.md): General Semantic Conventions.
* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
* *Other areas can be found in the signal specific Semantic Conventions below*
Semantic Conventions by signals:
* [Resource](resource/semantic_conventions/README.md): Semantic Conventions for resources.
* [Trace](trace/semantic_conventions/README.md): Semantic Conventions for traces and spans.
* [Metrics](metrics/semantic_conventions/README.md): Semantic Conventions for metrics.
* [Logs](logs/semantic_conventions/README.md): Semantic Conventions for logs and event data.
* [Trace](general/trace-general.md): Semantic Conventions for traces and spans.
* [Metrics](general/metrics-general.md): Semantic Conventions for metrics.
* [Logs](general/logs-general.md): Semantic Conventions for logs data.
* [Events](general/events-general.md): Semantic Conventions for event data.

20
specification/general/README.md Normal file
View File

@ -0,0 +1,20 @@
# General Semantic Conventions
This document defines general Semantic Conventions for spans, metrics, logs and events.
The following general Semantic Conventions are defined:
* [General attributes](general-attributes.md): General semantic attributes.
* [Spans](trace-general.md): General Semantic Conventions for traces / spans.
* [Metrics](metrics-general.md): General Semantic Conventions for metrics.
* [Logs](logs-general.md): General Semantic Conventions for logs.
* [Events](events-general.md): General Semantic Conventions for events.
## Event Name Reuse Prohibition
A new event MUST NOT be added with the same name as an event that existed in
the past but was renamed (with a corresponding schema file).
When introducing a new event name check all existing schema files to make sure
the name does not appear as a key of any "rename_events" section (keys denote
old event names in rename operations).

11
specification/logs/semantic_conventions/events.md → specification/general/events-general.md
View File

@ -3,7 +3,16 @@
**Status**: [Experimental][DocumentStatus]
This document describes the attributes of standalone Events that are represented
in the data model by `LogRecord`s. Events are recorded as LogRecords that are shaped
in the data model by `LogRecord`s.
The following semantic conventions for events are defined:
* [General](#general-event-attributes): General semantic attributes that may be used in describing Events.
* [Exceptions](/specification/logs/semantic_conventions/exceptions.md): Semantic attributes that may be used in describing exceptions as events.
## General event attributes
Events are recorded as LogRecords that are shaped
in a special way: Event LogRecords have the attributes `event.domain`
and `event.name` (and possibly other LogRecord attributes).

2
specification/trace/semantic_conventions/span-general.md → specification/general/general-attributes.md
View File

@ -282,7 +282,7 @@ Instrumentations SHOULD provide a way for users to configure this name.
<!-- semconv peer -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `peer.service` | string | The [`service.name`](../../resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended |
| `peer.service` | string | The [`service.name`](/specification/resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended |
<!-- endsemconv -->
Examples of `peer.service` that users may specify:

80
specification/general/logs-general.md Normal file
View File

@ -0,0 +1,80 @@
# General logs attributes
**Status**: [Experimental][DocumentStatus]
The attributes described in this section are rather generic.
They may be used in any Log Record they apply to.
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc -->
- [General log identification attributes](#general-log-identification-attributes)
- [Log Media](#log-media)
* [Log File](#log-file)
* [I/O Stream](#io-stream)
<!-- tocstop -->
The following semantic conventions for logs are defined:
* [General](#general-log-identification-attributes): General semantic attributes that may be used in describing Log Records.
* [Exceptions](/specification/logs/semantic_conventions/exceptions.md): Semantic attributes that may be used in describing exceptions in logs.
* [Feature Flags](/specification/logs/semantic_conventions/feature-flags.md): Semantic attributes that may be used in describing feature flag evaluations in logs.
Apart from semantic conventions for logs, [events](events-general.md), [traces](trace-general.md), and [metrics](metrics-general.md),
OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own
[Resource Semantic Conventions](/specification/resource/semantic_conventions/README.md).
## General log identification attributes
These attributes may be used for identifying a Log Record.
<!-- semconv log.record -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | Opt-In |
**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed.
<!-- endsemconv -->
## Log Media
This section describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log.
**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`.
The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission.
As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes.
### Log File
**Description:** A file to which log was emitted.
<!-- semconv attributes.log.file -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `log.file.name` | string | The basename of the file. | `audit.log` | Recommended |
| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | Opt-In |
| `log.file.name_resolved` | string | The basename of the file, with symlinks resolved. | `uuid.log` | Opt-In |
| `log.file.path_resolved` | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | Opt-In |
<!-- endsemconv -->
### I/O Stream
**Description:** The I/O stream to which the log was emitted.
<!-- semconv attributes.log -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `log.iostream` | string | The stream associated with the log. See below for a list of well-known values. | `stdout` | Opt-In |
`log.iostream` MUST be one of the following:
| Value | Description |
|---|---|
| `stdout` | Logs from stdout stream |
| `stderr` | Events from stderr stream |
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

220
specification/general/metrics-general.md Normal file
View File

@ -0,0 +1,220 @@
# Metrics Semantic Conventions
**Status**: [Mixed][DocumentStatus]
<!-- toc -->
- [General Guidelines](#general-guidelines)
* [Name Reuse Prohibition](#name-reuse-prohibition)
* [Units](#units)
* [Pluralization](#pluralization)
+ [Use `count` Instead of Pluralization](#use-count-instead-of-pluralization)
- [General Metric Semantic Conventions](#general-metric-semantic-conventions)
* [Instrument Naming](#instrument-naming)
* [Instrument Units](#instrument-units)
* [Instrument Types](#instrument-types)
* [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries)
<!-- tocstop -->
The following semantic conventions surrounding metrics are defined:
* [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics.
* [RPC](/specification/metrics/semantic_conventions/rpc-metrics.md): For RPC client and server metrics.
* [Database](/specification/metrics/semantic_conventions/database-metrics.md): For SQL and NoSQL client metrics.
* [System](/specification/metrics/semantic_conventions/system-metrics.md): For standard system metrics.
* [Process](/specification/metrics/semantic_conventions/process-metrics.md): For standard process metrics.
* [Runtime Environment](/specification/metrics/semantic_conventions/runtime-environment-metrics.md): For runtime environment metrics.
* [FaaS](/specification/metrics/semantic_conventions/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics.
* [Hardware](/specification/metrics/semantic_conventions/hardware-metrics.md): For hardware-related metrics.
Apart from semantic conventions for metrics, [traces](trace-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also
defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with
their own [Resource Semantic Conventions](/specification/resource/semantic_conventions/README.md).
## General Guidelines
**Status**: [Experimental][DocumentStatus]
Metric names and attributes exist within a single universe and a single
hierarchy. Metric names and attributes MUST be considered within the universe of
all existing metric names. When defining new metric names and attributes,
consider the prior art of existing standard metrics and metrics from
frameworks/libraries.
Associated metrics SHOULD be nested together in a hierarchy based on their
usage. Define a top-level hierarchy for common metric categories: for OS
metrics, like CPU and network; for app runtimes, like GC internals. Libraries
and frameworks should nest their metrics into a hierarchy as well. This aids
in discovery and adhoc comparison. This allows a user to find similar metrics
given a certain metric.
The hierarchical structure of metrics defines the namespacing. Supporting
OpenTelemetry artifacts define the metric structures and hierarchies for some
categories of metrics, and these can assist decisions when creating future
metrics.
Common attributes SHOULD be consistently named. This aids in discoverability and
disambiguates similar attributes to metric names.
["As a rule of thumb, **aggregations** over all the attributes of a given
metric **SHOULD** be
meaningful,"](https://prometheus.io/docs/practices/naming/#metric-names) as
Prometheus recommends.
Semantic ambiguity SHOULD be avoided. Use prefixed metric names in cases
where similar metrics have significantly different implementations across the
breadth of all existing metrics. For example, every garbage collected runtime
has slightly different strategies and measures. Using a single set of metric
names for GC, not divided by the runtime, could create dissimilar comparisons
and confusion for end users. (For example, prefer `process.runtime.java.gc*` over
`process.runtime.gc.*`.) Measures of many operating system metrics are similarly
ambiguous.
### Name Reuse Prohibition
A new metric MUST NOT be added with the same name as a metric that existed in
the past but was renamed (with a corresponding schema file).
When introducing a new metric name check all existing schema files to make sure
the name does not appear as a key of any "rename_metrics" section (keys denote
old metric names in rename operations).
### Units
Conventional metrics or metrics that have their units included in
OpenTelemetry metadata (e.g. `metric.WithUnit` in Go) SHOULD NOT include the
units in the metric name. Units may be included when it provides additional
meaning to the metric name. Metrics MUST, above all, be understandable and
usable.
When building components that interoperate between OpenTelemetry and a system
using the OpenMetrics exposition format, use the
[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/compatibility/prometheus_and_openmetrics.md).
### Pluralization
Metric names SHOULD NOT be pluralized, unless the value being recorded
represents discrete instances of a
[countable quantity](https://en.wikipedia.org/wiki/Count_noun).
Generally, the name SHOULD be pluralized only if the unit of the metric in
question is a non-unit (like `{fault}` or `{operation}`).
Examples:
* `system.filesystem.utilization`, `http.server.duration`, and `system.cpu.time`
should not be pluralized, even if many data points are recorded.
* `system.paging.faults`, `system.disk.operations`, and `system.network.packets`
should be pluralized, even if only a single data point is recorded.
#### Use `count` Instead of Pluralization
If the value being recorded represents the count of concepts signified
by the namespace then the metric should be named `count` (within its namespace).
The pluralization rule does not apply in this case.
For example if we have a namespace `system.processes` which contains all metrics related
to the processes then to represent the count of the processes we can have a metric named
`system.processes.count`. The suffix `count` here indicates that it is the count of
`system.processes`.
## General Metric Semantic Conventions
**Status**: [Mixed][DocumentStatus]
The following semantic conventions aim to keep naming consistent. They
provide guidelines for most of the cases in this specification and should be
followed for other instruments not explicitly defined in this document.
### Instrument Naming
**Status**: [Experimental][DocumentStatus]
- **limit** - an instrument that measures the constant, known total amount of
something should be called `entity.limit`. For example, `system.memory.limit`
for the total amount of memory on a system.
- **usage** - an instrument that measures an amount used out of a known total
(**limit**) amount should be called `entity.usage`. For example,
`system.memory.usage` with attribute `state = used | cached | free | ...` for the
amount of memory in a each state. Where appropriate, the sum of **usage**
over all attribute values SHOULD be equal to the **limit**.
A measure of the amount consumed of an unlimited resource, or of a resource
whose limit is unknowable, is differentiated from **usage**. For example, the
maximum possible amount of virtual memory that a process may consume may
fluctuate over time and is not typically known.
- **utilization** - an instrument that measures the *fraction* of **usage**
out of its **limit** should be called `entity.utilization`. For example,
`system.memory.utilization` for the fraction of memory in use. Utilization
values are in the range `[0, 1]`.
- **time** - an instrument that measures passage of time should be called
`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user
| system | ...`. **time** measurements are not necessarily wall time and can
be less than or greater than the real wall time between measurements.
**time** instruments are a special case of **usage** metrics, where the
**limit** can usually be calculated as the sum of **time** over all attribute
values. **utilization** for time instruments can be derived automatically
using metric event timestamps. For example, `system.cpu.utilization` is
defined as the difference in `system.cpu.time` measurements divided by the
elapsed time and number of CPUs.
- **io** - an instrument that measures bidirectional data flow should be
called `entity.io` and have attributes for direction. For example,
`system.network.io`.
- Other instruments that do not fit the above descriptions may be named more
freely. For example, `system.paging.faults` and `system.network.packets`.
Units do not need to be specified in the names since they are included during
instrument creation, but can be added if there is ambiguity.
### Instrument Units
**Status**: [Stable][DocumentStatus]
Units should follow the
[Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html).
- Instruments for **utilization** metrics (that measure the fraction out of a
total) are dimensionless and SHOULD use the default unit `1` (the unity).
- All non-units that use curly braces to annotate a quantity need to match the
grammatical number of the quantity it represent. For example if measuring the
number of individual requests to a process the unit would be `{request}`, not
`{requests}`.
- Instruments that measure an integer count of something SHOULD only use
[annotations](https://ucum.org/ucum.html#para-curly) with curly braces to
give additional meaning *without* the leading default unit (`1`). For example,
use `{packet}`, `{error}`, `{fault}`, etc.
- Instrument units other than `1` and those that use
[annotations](https://ucum.org/ucum.html#para-curly) SHOULD be specified using
the UCUM case sensitive ("c/s") variant.
For example, "Cel" for the unit with full name "degree Celsius".
- Instruments SHOULD use non-prefixed units (i.e. `By` instead of `MiBy`)
unless there is good technical reason to not do so.
- When instruments are measuring durations, seconds (i.e. `s`) SHOULD be used.
### Instrument Types
**Status**: [Stable][DocumentStatus]
The semantic metric conventions specification is written to use the names of the synchronous instrument types,
like `Counter` or `UpDownCounter`. However, compliant implementations MAY use the asynchronous equivalent instead,
like `Asynchronous Counter` or `Asynchronous UpDownCounter`.
Whether implementations choose the synchronous type or the asynchronous equivalent is considered to be an
implementation detail. Both choices are compliant with this specification.
### Consistent UpDownCounter timeseries
**Status**: [Experimental][DocumentStatus]
When recording `UpDownCounter` metrics, the same attribute values used to record an increment SHOULD be used to record
any associated decrement, otherwise those increments and decrements will end up as different timeseries.
For example, if you are tracking `active_requests` with an `UpDownCounter`, and you are incrementing it each time a
request starts and decrementing it each time a request ends, then any attributes which are not yet available when
incrementing the counter at request start should not be used when decrementing the counter at request end.
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

36
specification/general/trace-general.md Normal file
View File

@ -0,0 +1,36 @@
# Trace Semantic Conventions
**Status**: [Experimental][DocumentStatus]
In OpenTelemetry spans can be created freely and it’s up to the implementor to
annotate them with attributes specific to the represented operation. Spans
represent specific operations in and between systems. Some of these operations
represent calls that use well-known protocols like HTTP or database calls.
Depending on the protocol and the type of operation, additional information
is needed to represent and analyze a span correctly in monitoring systems. It is
also important to unify how this attribution is made in different languages.
This way, the operator will not need to learn specifics of a language and
telemetry collected from polyglot (multi-language) micro-service environments
can still be easily correlated and cross-analyzed.
The following semantic conventions for spans are defined:
* [General](general-attributes.md): General semantic attributes that may be used in describing different kinds of operations.
* [HTTP](/specification/http/http-spans.md): For HTTP client and server spans.
* [Database](/specification/trace/semantic_conventions/database.md): For SQL and NoSQL client call spans.
* [RPC/RMI](/specification/trace/semantic_conventions/rpc.md): For remote procedure call (e.g., gRPC) spans.
* [Messaging](/specification/trace/semantic_conventions/messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans.
* [FaaS](/specification/trace/semantic_conventions/faas.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans.
* [Exceptions](/specification/trace/semantic_conventions/exceptions.md): For recording exceptions associated with a span.
* [Compatibility](/specification/trace/semantic_conventions/compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer.
* [Feature Flags](/specification/trace/semantic_conventions/feature-flags.md): For recording feature flag evaluations associated with a span.
The following library-specific semantic conventions are defined:
* [AWS Lambda](/specification/trace/semantic_conventions/instrumentation/aws-lambda.md): For AWS Lambda spans.
* [AWS SDK](/specification/trace/semantic_conventions/instrumentation/aws-sdk.md): For AWS SDK spans.
* [GraphQL](/specification/trace/semantic_conventions/instrumentation/graphql.md): For GraphQL spans.
Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md),
OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own
[Resource Semantic Conventions](/specification/resource/semantic_conventions/README.md).

58
specification/http/http-metrics.md
View File

@ -77,10 +77,10 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In |
| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In |
| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
@ -153,8 +153,8 @@ This metric is optional.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In |
| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In |
| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
@ -224,10 +224,10 @@ This metric is optional.
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In |
| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In |
| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
@ -302,10 +302,10 @@ This metric is optional.
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In |
| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In |
| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
@ -387,11 +387,11 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
|---|---|---|---|---|
| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required |
| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@ -456,11 +456,11 @@ This metric is optional.
|---|---|---|---|---|
| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required |
| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@ -525,11 +525,11 @@ This metric is optional.
|---|---|---|---|---|
| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required |
| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)

42
specification/http/http-spans.md
View File

@ -96,10 +96,10 @@ sections below.
| `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
| `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
| [`network.protocol.name`](../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). |
| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended |
| [`network.transport`](../trace/semantic_conventions/span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] |
| [`network.type`](../trace/semantic_conventions/span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). |
| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended |
| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] |
| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended |
**[1]:** If and only if it's different than `http.request.method`.
@ -193,11 +193,11 @@ For an HTTP client span, `SpanKind` MUST be `Client`.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`server.socket.domain`](../trace/semantic_conventions/span-general.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. |
| [`server.socket.port`](../trace/semantic_conventions/span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required |
| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`server.socket.domain`](../general/general-attributes.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. |
| [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required |
**[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
@ -223,8 +223,8 @@ If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.
Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* [`server.address`](../trace/semantic_conventions/span-general.md)
* [`server.port`](../trace/semantic_conventions/span-general.md)
* [`server.address`](../general/general-attributes.md)
* [`server.port`](../general/general-attributes.md)
* `url.full`
<!-- endsemconv -->
@ -323,14 +323,14 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| [`client.address`](../trace/semantic_conventions/span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended |
| [`client.port`](../trace/semantic_conventions/span-general.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended |
| [`client.socket.address`](../trace/semantic_conventions/span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. |
| [`client.socket.port`](../trace/semantic_conventions/span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. |
| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended |
| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] |
| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In |
| [`server.socket.port`](../trace/semantic_conventions/span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In |
| [`client.address`](../general/general-attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended |
| [`client.port`](../general/general-attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended |
| [`client.socket.address`](../general/general-attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. |
| [`client.socket.port`](../general/general-attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. |
| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended |
| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] |
| [`server.socket.address`](../general/general-attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In |
| [`server.socket.port`](../general/general-attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In |
| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required |
| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
@ -367,8 +367,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* [`server.address`](../trace/semantic_conventions/span-general.md)
* [`server.port`](../trace/semantic_conventions/span-general.md)
* [`server.address`](../general/general-attributes.md)
* [`server.port`](../general/general-attributes.md)
* `url.path`
* `url.query`
* `url.scheme`

17
specification/logs/semantic_conventions/README.md
View File

@ -1,18 +1,3 @@
# Log Attribute Semantic Conventions
**Status**: [Experimental][DocumentStatus]
The following semantic conventions for logs are defined:
* [General](general.md): General semantic attributes that may be used in describing Log Records.
* [Log Media](media.md): Semantic attributes that may be used in describing the source of a log.
The following semantic conventions for events are defined:
* [Events](events.md): Semantic attributes that must be used to represent Events using log data model.
Apart from semantic conventions for logs, [traces](../../trace/semantic_conventions/README.md), and [metrics](../../metrics/semantic_conventions/README.md),
OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own
[Resource Semantic Conventions](../../resource/semantic_conventions/README.md).
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
This page [has been moved](/specification/general/logs-general.md).

29
specification/logs/semantic_conventions/general.md
View File

@ -1,29 +0,0 @@
# General attributes
**Status**: [Experimental][DocumentStatus]
The attributes described in this section are rather generic.
They may be used in any Log Record they apply to.
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc -->
- [General log identification attributes](#general-log-identification-attributes)
<!-- tocstop -->
## General log identification attributes
These attributes may be used for identifying a Log Record.
<!-- semconv log.record -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | Opt-In |
**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed.
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

58
specification/logs/semantic_conventions/media.md
View File

@ -1,58 +0,0 @@
# Semantic Conventions for Log Media
**Status**: [Experimental][DocumentStatus]
This document describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log.
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<details>
<summary>Table of Contents</summary>
<!-- toc -->
- [Log Media](#log-media)
* [Log File](#log-file)
* [I/O Stream](#io-stream)
<!-- tocstop -->
</details>
## Log Media
**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`.
The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission.
As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes.
### Log File
**Description:** A file to which log was emitted.
<!-- semconv attributes.log.file -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `log.file.name` | string | The basename of the file. | `audit.log` | Recommended |
| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | Opt-In |
| `log.file.name_resolved` | string | The basename of the file, with symlinks resolved. | `uuid.log` | Opt-In |
| `log.file.path_resolved` | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | Opt-In |
<!-- endsemconv -->
### I/O Stream
**Description:** The I/O stream to which the log was emitted.
<!-- semconv attributes.log -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `log.iostream` | string | The stream associated with the log. See below for a list of well-known values. | `stdout` | Opt-In |
`log.iostream` MUST be one of the following:
| Value | Description |
|---|---|
| `stdout` | Logs from stdout stream |
| `stderr` | Events from stderr stream |
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

221
specification/metrics/semantic_conventions/README.md
View File

@ -5,223 +5,4 @@ linkTitle: Semantic Conventions
<!-- omit in toc -->
# Metrics Semantic Conventions
**Status**: [Mixed][DocumentStatus]
<!-- toc -->
- [General Guidelines](#general-guidelines)
* [Name Reuse Prohibition](#name-reuse-prohibition)
* [Units](#units)
* [Pluralization](#pluralization)
+ [Use `count` Instead of Pluralization](#use-count-instead-of-pluralization)
- [General Metric Semantic Conventions](#general-metric-semantic-conventions)
* [Instrument Naming](#instrument-naming)
* [Instrument Units](#instrument-units)
* [Instrument Types](#instrument-types)
* [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries)
<!-- tocstop -->
The following semantic conventions surrounding metrics are defined:
* [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics.
* [RPC](rpc-metrics.md): For RPC client and server metrics.
* [Database](database-metrics.md): For SQL and NoSQL client metrics.
* [System](system-metrics.md): For standard system metrics.
* [Process](process-metrics.md): For standard process metrics.
* [Runtime Environment](runtime-environment-metrics.md): For runtime environment metrics.
* [FaaS](faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics.
* [Hardware](hardware-metrics.md): For hardware-related metrics.
Apart from semantic conventions for metrics and
[traces](../../trace/semantic_conventions/README.md), OpenTelemetry also
defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with
their own [Resource Semantic
Conventions](../../resource/semantic_conventions/README.md).
## General Guidelines
**Status**: [Experimental][DocumentStatus]
Metric names and attributes exist within a single universe and a single
hierarchy. Metric names and attributes MUST be considered within the universe of
all existing metric names. When defining new metric names and attributes,
consider the prior art of existing standard metrics and metrics from
frameworks/libraries.
Associated metrics SHOULD be nested together in a hierarchy based on their
usage. Define a top-level hierarchy for common metric categories: for OS
metrics, like CPU and network; for app runtimes, like GC internals. Libraries
and frameworks should nest their metrics into a hierarchy as well. This aids
in discovery and adhoc comparison. This allows a user to find similar metrics
given a certain metric.
The hierarchical structure of metrics defines the namespacing. Supporting
OpenTelemetry artifacts define the metric structures and hierarchies for some
categories of metrics, and these can assist decisions when creating future
metrics.
Common attributes SHOULD be consistently named. This aids in discoverability and
disambiguates similar attributes to metric names.
["As a rule of thumb, **aggregations** over all the attributes of a given
metric **SHOULD** be
meaningful,"](https://prometheus.io/docs/practices/naming/#metric-names) as
Prometheus recommends.
Semantic ambiguity SHOULD be avoided. Use prefixed metric names in cases
where similar metrics have significantly different implementations across the
breadth of all existing metrics. For example, every garbage collected runtime
has slightly different strategies and measures. Using a single set of metric
names for GC, not divided by the runtime, could create dissimilar comparisons
and confusion for end users. (For example, prefer `process.runtime.java.gc*` over
`process.runtime.gc.*`.) Measures of many operating system metrics are similarly
ambiguous.
### Name Reuse Prohibition
A new metric MUST NOT be added with the same name as a metric that existed in
the past but was renamed (with a corresponding schema file).
When introducing a new metric name check all existing schema files to make sure
the name does not appear as a key of any "rename_metrics" section (keys denote
old metric names in rename operations).
### Units
Conventional metrics or metrics that have their units included in
OpenTelemetry metadata (e.g. `metric.WithUnit` in Go) SHOULD NOT include the
units in the metric name. Units may be included when it provides additional
meaning to the metric name. Metrics MUST, above all, be understandable and
usable.
When building components that interoperate between OpenTelemetry and a system
using the OpenMetrics exposition format, use the
[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/compatibility/prometheus_and_openmetrics.md).
### Pluralization
Metric names SHOULD NOT be pluralized, unless the value being recorded
represents discrete instances of a
[countable quantity](https://en.wikipedia.org/wiki/Count_noun).
Generally, the name SHOULD be pluralized only if the unit of the metric in
question is a non-unit (like `{fault}` or `{operation}`).
Examples:
* `system.filesystem.utilization`, `http.server.duration`, and `system.cpu.time`
should not be pluralized, even if many data points are recorded.
* `system.paging.faults`, `system.disk.operations`, and `system.network.packets`
should be pluralized, even if only a single data point is recorded.
#### Use `count` Instead of Pluralization
If the value being recorded represents the count of concepts signified
by the namespace then the metric should be named `count` (within its namespace).
The pluralization rule does not apply in this case.
For example if we have a namespace `system.processes` which contains all metrics related
to the processes then to represent the count of the processes we can have a metric named
`system.processes.count`. The suffix `count` here indicates that it is the count of
`system.processes`.
## General Metric Semantic Conventions
**Status**: [Mixed][DocumentStatus]
The following semantic conventions aim to keep naming consistent. They
provide guidelines for most of the cases in this specification and should be
followed for other instruments not explicitly defined in this document.
### Instrument Naming
**Status**: [Experimental][DocumentStatus]
- **limit** - an instrument that measures the constant, known total amount of
something should be called `entity.limit`. For example, `system.memory.limit`
for the total amount of memory on a system.
- **usage** - an instrument that measures an amount used out of a known total
(**limit**) amount should be called `entity.usage`. For example,
`system.memory.usage` with attribute `state = used | cached | free | ...` for the
amount of memory in a each state. Where appropriate, the sum of **usage**
over all attribute values SHOULD be equal to the **limit**.
A measure of the amount consumed of an unlimited resource, or of a resource
whose limit is unknowable, is differentiated from **usage**. For example, the
maximum possible amount of virtual memory that a process may consume may
fluctuate over time and is not typically known.
- **utilization** - an instrument that measures the *fraction* of **usage**
out of its **limit** should be called `entity.utilization`. For example,
`system.memory.utilization` for the fraction of memory in use. Utilization
values are in the range `[0, 1]`.
- **time** - an instrument that measures passage of time should be called
`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user
| system | ...`. **time** measurements are not necessarily wall time and can
be less than or greater than the real wall time between measurements.
**time** instruments are a special case of **usage** metrics, where the
**limit** can usually be calculated as the sum of **time** over all attribute
values. **utilization** for time instruments can be derived automatically
using metric event timestamps. For example, `system.cpu.utilization` is
defined as the difference in `system.cpu.time` measurements divided by the
elapsed time and number of CPUs.
- **io** - an instrument that measures bidirectional data flow should be
called `entity.io` and have attributes for direction. For example,
`system.network.io`.
- Other instruments that do not fit the above descriptions may be named more
freely. For example, `system.paging.faults` and `system.network.packets`.
Units do not need to be specified in the names since they are included during
instrument creation, but can be added if there is ambiguity.
### Instrument Units
**Status**: [Stable][DocumentStatus]
Units should follow the
[Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html).
- Instruments for **utilization** metrics (that measure the fraction out of a
total) are dimensionless and SHOULD use the default unit `1` (the unity).
- All non-units that use curly braces to annotate a quantity need to match the
grammatical number of the quantity it represent. For example if measuring the
number of individual requests to a process the unit would be `{request}`, not
`{requests}`.
- Instruments that measure an integer count of something SHOULD only use
[annotations](https://ucum.org/ucum.html#para-curly) with curly braces to
give additional meaning *without* the leading default unit (`1`). For example,
use `{packet}`, `{error}`, `{fault}`, etc.
- Instrument units other than `1` and those that use
[annotations](https://ucum.org/ucum.html#para-curly) SHOULD be specified using
the UCUM case sensitive ("c/s") variant.
For example, "Cel" for the unit with full name "degree Celsius".
- Instruments SHOULD use non-prefixed units (i.e. `By` instead of `MiBy`)
unless there is good technical reason to not do so.
- When instruments are measuring durations, seconds (i.e. `s`) SHOULD be used.
### Instrument Types
**Status**: [Stable][DocumentStatus]
The semantic metric conventions specification is written to use the names of the synchronous instrument types,
like `Counter` or `UpDownCounter`. However, compliant implementations MAY use the asynchronous equivalent instead,
like `Asynchronous Counter` or `Asynchronous UpDownCounter`.
Whether implementations choose the synchronous type or the asynchronous equivalent is considered to be an
implementation detail. Both choices are compliant with this specification.
### Consistent UpDownCounter timeseries
**Status**: [Experimental][DocumentStatus]
When recording `UpDownCounter` metrics, the same attribute values used to record an increment SHOULD be used to record
any associated decrement, otherwise those increments and decrements will end up as different timeseries.
For example, if you are tracking `active_requests` with an `UpDownCounter`, and you are incrementing it each time a
request starts and decrementing it each time a request ends, then any attributes which are not yet available when
incrementing the counter at request start should not be used when decrementing the counter at request end.
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
This page [has been moved](/specification/general/metrics-general.md).

4
specification/metrics/semantic_conventions/database-metrics.md
View File

@ -29,7 +29,7 @@ and units.
Below is a table of database client connection pool metric instruments that MUST be used by connection pool
instrumentations:
| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
| Name | Instrument | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description |
|-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------|
| `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. |
@ -43,7 +43,7 @@ Instrumentation libraries for database client connection pools that collect data
following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments
MUST NOT be used.
| Name | Instrument ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
| Name | Instrument ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description |
|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------|
| `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. |
| `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. |

4
specification/metrics/semantic_conventions/faas-metrics.md
View File

@ -36,7 +36,7 @@ type and units.
Below is a table of FaaS invocation metric instruments.
| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description |
|------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------|
| `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation |
| `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start |
@ -47,7 +47,7 @@ Below is a table of FaaS invocation metric instruments.
Optionally, when applicable:
| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description |
|------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------|
| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation |
| `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of CPU usage per invocation |

34
specification/metrics/semantic_conventions/hardware-metrics.md
View File

@ -7,7 +7,7 @@ linkTitle: Hardware
**Status**: [Experimental][DocumentStatus]
This document describes instruments and attributes for common hardware level
metrics in OpenTelemetry. Consider the [general metric semantic conventions](README.md#general-metric-semantic-conventions)
metrics in OpenTelemetry. Consider the [general metric semantic conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions)
when creating instruments not explicitly defined in the specification.
<!-- toc -->
@ -52,7 +52,7 @@ Additionally, all metrics in `hw.` instruments have the following attributes:
The below metrics apply to any type of hardware component.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.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) | |
@ -75,7 +75,7 @@ monitored component:
**Description:** Physical system as opposed to a virtual system or a container.
Examples: physical server, switch or disk array.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ---------------- |
| `hw.host.ambient_temperature` | Ambient (external) temperature of the physical host | Cel | Gauge | Double | | |
| `hw.host.energy` | Total energy consumed by the entire physical host, in joules | J | Counter | Int64 | | |
@ -92,7 +92,7 @@ Examples: physical server, switch or disk array.
**Description:** A battery in a computer system or an UPS.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
| ------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------- | ----------------------------------------------------- |
| `hw.battery.charge` | Remaining fraction of battery charge | 1 | Gauge | Double | | |
| `hw.battery.charge.limit` | Lower limit of battery charge fraction to ensure proper operation | 1 | Gauge | Double | `limit_type` (Recommended) | `critical`, `throttled`, `degraded` |
@ -116,7 +116,7 @@ describe the characteristics of the monitored battery:
the operating system for multi-core systems). A physical processor may include
many individual cores.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| -------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------- |
| `hw.errors` | Total number of errors encountered and corrected by the CPU | {error} | Counter | Int64 | `hw.type` (**Required**) | `cpu` |
| `hw.cpu.speed` | CPU current frequency | Hz | Gauge | Int64 | | |
@ -136,7 +136,7 @@ Additional **Recommended** attributes:
**Description:** Controller that controls the physical disks and organize
them in RAID sets and logical disks that are exposed to the operating system.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- |
| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
| | | | | | `hw.type` (**Required**) | `disk_controller` |
@ -156,7 +156,7 @@ Additional **Recommended** attributes:
**Description:** Computer chassis (can be an expansion enclosure)
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | ---------------------------------- |
| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `open` |
| | | | | | `hw.type` (**Required**) | `enclosure` |
@ -176,7 +176,7 @@ Additional **Recommended** attributes:
**Description:** Fan that keeps the air flowing to maintain the internal
temperature of a computer
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| -------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------------ | ------------------------------------- |
| `hw.fan.speed` | Fan speed in revolutions per minute | rpm | Gauge | Int | | |
| `hw.fan.speed.limit` | Speed limit in rpm | rpm | Gauge | Int | `limit_type` (**Recommended**) | `low.critical`, `low.degraded`, `max` |
@ -194,7 +194,7 @@ Additional **Recommended** attributes:
**Description:** Graphics Processing Unit (discrete)
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| --------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | ----------------------------------------------- |
| `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `corrected`, `uncorrected` |
| | | | | | `hw.type` (**Required**) | `gpu` |
@ -223,7 +223,7 @@ Additional **Recommended** attributes:
controller to the operating system (e.g. a RAID 1 set made of 2 disks, and exposed
as /dev/hdd0 by the controller).
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ----------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- |
| `hw.errors` | Number of errors encountered on this logical disk | {error} | Counter | Int64 | `hw.type` (**Required**) | `logical_disk` |
| `hw.logical_disk.limit` | Size of the logical disk | By | UpDownCounter | Int64 | | |
@ -242,7 +242,7 @@ Additional **Recommended** attributes:
**Description:** A memory module in a computer system.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ---------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------- |
| `hw.errors` | Number of errors encountered on this memory module | {error} | Counter | Int64 | `hw.type` (**Required**) | `memory` |
| `hw.memory.size` | Size of the memory module | By | UpDownCounter | Int64 | | |
@ -265,7 +265,7 @@ Additional **Recommended** attributes:
physical network interface on a server, switch, router or firewall, an HBA, a
fiber channel port or a Wi-Fi adapter.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | ----------------------------- | --------------------------------- |
| `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `zero_buffer_credit`, `crc`, etc. |
| | | | | | `hw.type` (**Required**) | `network` |
@ -292,7 +292,7 @@ Additional **Recommended** attributes:
**Description:** Physical hard drive (HDD or SDD)
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ---------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- |
| `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `bad_sector`, `write`, etc. |
| | | | | | `hw.type` (**Required**) | `physical_disk` |
@ -317,7 +317,7 @@ Additional **Recommended** attributes:
**Description:** Power supply converting AC current to DC used by the
motherboard and the GPUs
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ----------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ------------------------------ |
| `hw.power_supply.limit` | Maximum power output of the power supply | W | UpDownCounter | Int64 | `limit_type` (Recommended) | `max`, `critical`, `throttled` |
| `hw.power_supply.utilization` | Utilization of the power supply as a fraction of its maximum output | 1 | Gauge | Double | | |
@ -337,7 +337,7 @@ Additional **Recommended** attributes:
**Description:** A tape drive in a computer or in a tape library (excluding
virtual tape libraries)
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| -------------------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------------------------- |
| `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.error.type` | `read`, `write`, `mount`, etc. |
| | | | | | `hw.type` (**Required**) | `tape_drive` |
@ -357,7 +357,7 @@ Additional **Recommended** attributes:
**Description:** A temperature sensor, either numeric or discrete
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ---------------------- | --------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- |
| `hw.temperature` | Temperature in degrees Celsius | Cel | Gauge | Double | | |
| `hw.temperature.limit` | Temperature limit in degrees Celsius | Cel | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` |
@ -374,7 +374,7 @@ Additional **Recommended** attributes:
**Description:** A voltage sensor, either numeric or discrete
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| -------------------- | ----------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- |
| `hw.voltage.limit` | Voltage limit in Volts | V | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` |
| `hw.voltage.nominal` | Nominal (expected) voltage | V | Gauge | Double | | |

6
specification/metrics/semantic_conventions/instrumentation/kafka.md
View File

@ -20,7 +20,7 @@ This document defines how to apply semantic conventions when instrumenting Kafka
**Description:** General Kafka metrics.
| Name | Instrument | Value type | Unit | Unit ([UCUM](../README.md#instrument-units)) | Description | Attribute Key | Attribute Values |
| Name | Instrument | Value type | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values |
| ---------------------------------------------| ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- |
| messaging.kafka.messages | Counter | Int64 | messages | `{message}` | The number of messages received by the broker. | | |
| messaging.kafka.requests.failed | Counter | Int64 | requests | `{request}` | The number of requests to the broker resulting in a failure. | `type` | `produce`, `fetch` |
@ -50,7 +50,7 @@ This document defines how to apply semantic conventions when instrumenting Kafka
**Description:** Kafka Producer level metrics.
| Name | Instrument | Value type | Unit | Unit ([UCUM](../README.md#instrument-units)) | Description | Attribute Key | Attribute Values |
| Name | Instrument | Value type | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values |
| --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- |
| messaging.kafka.producer.outgoing-bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of outgoing bytes sent per second to all servers. | `client-id` | `client-id` value |
| messaging.kafka.producer.responses.rate | Gauge | Double | responses per second | `{response}/s` | The average number of responses received per second. | `client-id` | `client-id` value |
@ -69,7 +69,7 @@ This document defines how to apply semantic conventions when instrumenting Kafka
**Description:** Kafka Consumer level metrics.
| Name | Instrument | Value type | Unit | Unit ([UCUM](../README.md#instrument-units)) | Description | Attribute Key | Attribute Values |
| Name | Instrument | Value type | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values |
| --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- |
| messaging.kafka.consumer.members | UpDownCounter | Int64 | members | `{member}` | Count of members in the consumer group | `group` | The ID (string) of a consumer group |
| messaging.kafka.consumer.offset | Gauge | Int64 | offset | `{offset}` | Current offset of the consumer group at partition of topic | `group` | The ID (string) of a consumer group |

4
specification/metrics/semantic_conventions/process-metrics.md
View File

@ -8,7 +8,7 @@ linkTitle: Process
This document describes instruments and attributes for common OS process level
metrics in OpenTelemetry. Also consider the [general metric semantic
conventions](README.md#general-metric-semantic-conventions) when creating
conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions) when creating
instruments not explicitly defined in this document. OS process metrics are
not related to the runtime environment of the program, and should take
measurements from the operating system. For runtime environment metrics see
@ -31,7 +31,7 @@ metrics](runtime-environment-metrics.md).
Below is a table of Process metric instruments.
| Name | Instrument Type ([\*](README.md#instrument-types)) | Unit | Description | Labels |
| Name | Instrument Type ([\*](/specification/general/metrics-general.md#instrument-types)) | Unit | Description | Labels |
|---------------------------------|----------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `process.cpu.time` | Counter | s | Total CPU seconds broken down by different states. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. |
| `process.cpu.utilization` | Gauge | 1 | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. |

22
specification/metrics/semantic_conventions/rpc-metrics.md
View File

@ -64,7 +64,7 @@ MUST be of the specified type and units.
Below is a table of RPC server metric instruments.
| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming |
| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Status | Streaming |
|------|------------|------|-------------------------------------------|-------------|--------|-----------|
| `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. |
| `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch |
@ -77,7 +77,7 @@ Below is a table of RPC server metric instruments.
Below is a table of RPC client metric instruments. These apply to traditional
RPC usage, not streaming RPCs.
| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming |
| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Status | Streaming |
|------|------------|------|-------------------------------------------|-------------|--------|-----------|
| `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. |
| `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch |
@ -96,12 +96,12 @@ measurements.
| [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
| [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended |
| [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended |
| [`network.transport`](../../trace/semantic_conventions/span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../../trace/semantic_conventions/span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below |
| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](../../trace/semantic_conventions/span-general.md) | int | Physical server port. | `16456` | Recommended: [4] |
| [`network.transport`](../../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../../general/general-attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
| [`server.port`](../../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below |
| [`server.socket.address`](../../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](../../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: [4] |
**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
@ -113,8 +113,8 @@ measurements.
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* [`server.socket.address`](../../trace/semantic_conventions/span-general.md)
* [`server.address`](../../trace/semantic_conventions/span-general.md)
* [`server.socket.address`](../../general/general-attributes.md)
* [`server.address`](../../general/general-attributes.md)
`rpc.system` 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.
@ -134,7 +134,7 @@ To avoid high cardinality, implementations should prefer the most stable of `ser
For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to).
For server-side spans `server.port` is optional (it describes the port the client is connecting from).
[network.transport]: ../../trace/semantic_conventions/span-general.md#network-attributes
[network.transport]: ../../general/general-attributes.md#network-attributes
### Service name

4
specification/metrics/semantic_conventions/runtime-environment-metrics.md
View File

@ -8,7 +8,7 @@ linkTitle: Runtime Environment
This document includes semantic conventions for runtime environment level
metrics in OpenTelemetry. Also consider the [general
metric](README.md#general-metric-semantic-conventions), [system
metric](/specification/general/metrics-general.md#general-metric-semantic-conventions), [system
metrics](system-metrics.md) and [OS Process metrics](process-metrics.md)
semantic conventions when instrumenting runtime environments.
@ -56,7 +56,7 @@ discussion.
Metrics specific to a certain runtime environment should be prefixed with
`process.runtime.{environment}.` and follow the semantic conventions outlined in
[general metric semantic
conventions](README.md#general-metric-semantic-conventions). Authors of
conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions). Authors of
runtime instrumentations are responsible for the choice of `{environment}` to
avoid ambiguity when interpreting a metric's name or values.

16
specification/metrics/semantic_conventions/system-metrics.md
View File

@ -8,7 +8,7 @@ linkTitle: System
This document describes instruments and attributes for common system level
metrics in OpenTelemetry. Consider the [general metric semantic
conventions](README.md#general-metric-semantic-conventions) when creating
conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions) when creating
instruments not explicitly defined in the specification.
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
@ -33,7 +33,7 @@ instruments not explicitly defined in the specification.
**Description:** System level processor metrics.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
| ---------------------- | -------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- |
| system.cpu.time | | s | Counter | Double | state | idle, user, system, interrupt, etc. |
| | | | | | cpu | CPU number [0..n-1] |
@ -45,7 +45,7 @@ instruments not explicitly defined in the specification.
**Description:** System level memory metrics. This does not include [paging/swap
memory](#systempaging---pagingswap-metrics).
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | ------------------------ |
| system.memory.usage | | By | UpDownCounter | Int64 | state | used, free, cached, etc. |
| system.memory.utilization | | 1 | Gauge | Double | state | used, free, cached, etc. |
@ -54,7 +54,7 @@ memory](#systempaging---pagingswap-metrics).
**Description:** System level paging/swap memory metrics.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
|---------------------------|-------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------|
| system.paging.usage | Unix swap or windows pagefile usage | By | UpDownCounter | Int64 | state | used, free |
| system.paging.utilization | | 1 | Gauge | Double | state | used, free |
@ -66,7 +66,7 @@ memory](#systempaging---pagingswap-metrics).
**Description:** System level disk performance metrics.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
|--------------------------------------------|-------------------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------|
| system.disk.io<!--notlink--> | | By | Counter | Int64 | device | (identifier) |
| | | | | | direction | read, write |
@ -101,7 +101,7 @@ perf counter (similar for Writes)
**Description:** System level filesystem metrics.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ----------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | -------------------- |
| system.filesystem.usage | | By | UpDownCounter | Int64 | device | (identifier) |
| | | | | | state | used, free, reserved |
@ -118,7 +118,7 @@ perf counter (similar for Writes)
**Description:** System level network metrics.
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
|----------------------------------------|-------------------------------------------------------------------------------|---------------|---------------------------------------------------|------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| system.network.dropped<sup>\[1\]</sup> | Count of packets that are dropped or discarded even though there was no error | {packet} | Counter | Int64 | device | (identifier) |
| | | | | | direction | transmit, receive |
@ -155,7 +155,7 @@ from
**Description:** System level aggregate process metrics. For metrics at the
individual process level, see [process metrics](process-metrics.md).
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ------------------------ | --------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- |
| system.processes.count | Total number of processes in each state | {process} | UpDownCounter | Int64 | status | running, sleeping, [etc.](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) |
| system.processes.created | Total number of processes created over uptime of the host | {process} | Counter | Int64 | - | - |

2
specification/resource/semantic_conventions/faas.md
View File

@ -25,7 +25,7 @@ See also:
**[1]:** This is the name of the function as configured/deployed on the FaaS
platform and is usually different from the name of the callback
function (which may be stored in the
[`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes)
[`code.namespace`/`code.function`](/specification/general/general-attributes.md#source-code-attributes)
span attributes).
For some cloud providers, the above definition is ambiguous. The following

47
specification/trace/semantic_conventions/README.md
View File

@ -1,48 +1,3 @@
# Trace Semantic Conventions
**Status**: [Experimental][DocumentStatus]
In OpenTelemetry spans can be created freely and it’s up to the implementor to
annotate them with attributes specific to the represented operation. Spans
represent specific operations in and between systems. Some of these operations
represent calls that use well-known protocols like HTTP or database calls.
Depending on the protocol and the type of operation, additional information
is needed to represent and analyze a span correctly in monitoring systems. It is
also important to unify how this attribution is made in different languages.
This way, the operator will not need to learn specifics of a language and
telemetry collected from polyglot (multi-language) micro-service environments
can still be easily correlated and cross-analyzed.
The following semantic conventions for spans are defined:
* [General](span-general.md): General semantic attributes that may be used in describing different kinds of operations.
* [HTTP](/specification/http/http-spans.md): For HTTP client and server spans.
* [Database](database.md): For SQL and NoSQL client call spans.
* [RPC/RMI](rpc.md): For remote procedure call (e.g., gRPC) spans.
* [Messaging](messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans.
* [FaaS](faas.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans.
* [Exceptions](exceptions.md): For recording exceptions associated with a span.
* [Compatibility](compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer.
* [Feature Flags](feature-flags.md): For recording feature flag evaluations associated with a span.
The following library-specific semantic conventions are defined:
* [AWS Lambda](instrumentation/aws-lambda.md): For AWS Lambda spans.
* [AWS SDK](instrumentation/aws-sdk.md): For AWS SDK spans.
* [Elasticsearch](instrumentation/elasticsearch.md): For Elasticsearch spans.
* [GraphQL](instrumentation/graphql.md): For GraphQL spans.
Apart from semantic conventions for traces and [metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/semantic_conventions/README.md),
OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own
[Resource Semantic Conventions](../../resource/semantic_conventions/README.md).
## Event Name Reuse Prohibition
A new event MUST NOT be added with the same name as an event that existed in
the past but was renamed (with a corresponding schema file).
When introducing a new event name check all existing schema files to make sure
the name does not appear as a key of any "rename_events" section (keys denote
old event names in rename operations).
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
This page [has been moved](/specification/general/trace-general.md).

16
specification/trace/semantic_conventions/database.md
View File

@ -69,19 +69,19 @@ Some database systems may allow a connection to switch to a different `db.user`,
| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required |
| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended |
| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](span-general.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] |
| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
| [`network.transport`](../../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../../general/general-attributes.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](../../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] |
| [`server.socket.address`](../../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](../../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
**[1]:** If using a port other than the default port for this DBMS and if `server.address` is set.
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* [`server.address`](span-general.md)
* [`server.socket.address`](span-general.md)
* [`server.address`](../../general/general-attributes.md)
* [`server.socket.address`](../../general/general-attributes.md)
`db.system` 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.

4
specification/trace/semantic_conventions/instrumentation/elasticsearch.md
View File

@ -34,8 +34,8 @@ in order to map the path part values to their names.
| [`db.operation`](../database.md) | string | The endpoint identifier for the request. [1] | `search`; `ml.close_job`; `cat.aliases` | Required |
| [`db.statement`](../database.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [2] |
| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
| [`server.address`](../span-general.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below |
| [`server.port`](../span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended |
| [`server.address`](../../../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below |
| [`server.port`](../../../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended |
| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required |
**[1]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.

22
specification/trace/semantic_conventions/messaging.md
View File

@ -224,14 +224,14 @@ The following operations related to messages are defined for these semantic conv
| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [11] |
| `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [12] |
| `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [13] |
| [`network.protocol.name`](span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended |
| [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended |
| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](span-general.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [15] | `example.com` | Conditionally Required: If available. |
| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [16] | `proxy.example.com` | Recommended: [17] |
| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
| [`network.protocol.name`](../../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended |
| [`network.protocol.version`](../../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended |
| [`network.transport`](../../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [15] | `example.com` | Conditionally Required: If available. |
| [`server.socket.address`](../../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`server.socket.domain`](../../general/general-attributes.md) | string | The domain name of an immediate peer. [16] | `proxy.example.com` | Recommended: [17] |
| [`server.socket.port`](../../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
**[1]:** If a custom value is used, it MUST be of low cardinality.
@ -295,8 +295,8 @@ Communication with broker is described with general [network attributes].
Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace
as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems).
[network attributes]: span-general.md#server-and-client-attributes
[`network.transport`]: span-general.md#network-attributes
[network attributes]: /specification/general/general-attributes.md#server-and-client-attributes
[`network.transport`]: /specification/general/general-attributes.md#network-attributes
[Hangfire]: https://www.hangfire.io/
### Consumer attributes
@ -356,7 +356,7 @@ For Apache Kafka, the following additional attributes are defined:
**[2]:** If value is `true`. When missing, the value is assumed to be `false`.
<!-- endsemconv -->
For Apache Kafka producers, [`peer.service`](./span-general.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to.
For Apache Kafka producers, [`peer.service`](/specification/general/general-attributes.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to.
The `service.name` of a Consumer's Resource SHOULD match the `peer.service` of the Producer, when the message is directly passed to another service.
If an intermediary broker is present, `service.name` and `peer.service` will not be the same.

34
specification/trace/semantic_conventions/rpc.md
View File

@ -91,12 +91,12 @@ Examples of span names:
| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended |
| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
| [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below |
| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: [4] |
| [`network.transport`](../../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../../general/general-attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
| [`server.port`](../../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below |
| [`server.socket.address`](../../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](../../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: [4] |
**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
@ -108,8 +108,8 @@ Examples of span names:
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* [`server.socket.address`](span-general.md)
* [`server.address`](span-general.md)
* [`server.socket.address`](../../general/general-attributes.md)
* [`server.address`](../../general/general-attributes.md)
`rpc.system` 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.
@ -136,16 +136,16 @@ This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc
In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute.
Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name.
[network attributes]: span-general.md#server-and-client-attributes
[network attributes]: /specification/general/general-attributes.md#server-and-client-attributes
[`service.name`]: ../../resource/semantic_conventions/README.md#service
[`peer.service`]: span-general.md#general-remote-service-attributes
[`peer.service`]: /specification/general/general-attributes.md#general-remote-service-attributes
### Client attributes
<!-- semconv rpc.client -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended: [2] |
| [`server.socket.domain`](../../general/general-attributes.md) | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended: [2] |
**[1]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.
@ -157,12 +157,12 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
<!-- semconv rpc.server -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`client.address`](span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended |
| [`client.port`](span-general.md) | int | Client port number [2] | `65123` | Recommended |
| [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. |
| [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. |
| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`client.address`](../../general/general-attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended |
| [`client.port`](../../general/general-attributes.md) | int | Client port number [2] | `65123` | Recommended |
| [`client.socket.address`](../../general/general-attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. |
| [`client.socket.port`](../../general/general-attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. |
| [`network.transport`](../../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available.