From 21c636f88e6de2f9668c1cb50937bc7c5fcd389f Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Thu, 23 Mar 2023 11:43:14 -0500
Subject: [PATCH 01/36] Logging trace context compatibility document (#3331)
---
CHANGELOG.md | 2 +
.../compatibility/logging_trace_context.md | 70 +++++++++++++++++++
specification/logs/README.md | 63 +----------------
3 files changed, 75 insertions(+), 60 deletions(-)
create mode 100644 specification/compatibility/logging_trace_context.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 100c3278774..2684e7ef095 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ release.
([#3332](https://github.com/open-telemetry/opentelemetry-specification/pull/3332))
- Remove log readme document status.
([#3334](https://github.com/open-telemetry/opentelemetry-specification/pull/3334))
+- Break out compatibility document on recording trace context in non-OTLP Log Format
+ ([#3331](https://github.com/open-telemetry/opentelemetry-specification/pull/3331))
### Resource
diff --git a/specification/compatibility/logging_trace_context.md b/specification/compatibility/logging_trace_context.md
new file mode 100644
index 00000000000..c2c0349587b
--- /dev/null
+++ b/specification/compatibility/logging_trace_context.md
@@ -0,0 +1,70 @@
+# Trace Context in non-OTLP Log Formats
+
+**Status**: [Experimental](../document-status.md)
+
+
+Table of Contents
+
+
+
+- [Overview](#overview)
+ * [Syslog RFC5424](#syslog-rfc5424)
+ * [Plain Text Formats](#plain-text-formats)
+ * [JSON Formats](#json-formats)
+ * [Other Structured Formats](#other-structured-formats)
+
+
+
+
+
+## Overview
+
+OTLP Logs Records have top level fields
+representing [trace context](../logs/data-model.md#trace-context-fields). This
+document defines how trace context should be recorded in non-OTLP Log Formats.
+To summarize, the following field names should be used in legacy formats:
+
+- "trace_id" for [TraceId](../logs/data-model.md#field-traceid), hex-encoded.
+- "span_id" for [SpanId](../logs/data-model.md#field-spanid), hex-encoded.
+- "trace_flags" for [trace flags](../logs/data-model.md#field-traceflags), formatted
+ according to W3C traceflags format.
+
+All 3 fields are optional (see the [data model](../logs/data-model.md) for details of
+which combination of fields is considered valid).
+
+### Syslog RFC5424
+
+Trace id, span id and traceflags SHOULD be recorded via SD-ID "opentelemetry".
+
+For example:
+
+```
+[opentelemetry trace_id="102981ABCD2901" span_id="abcdef1010" trace_flags="01"]
+```
+
+### Plain Text Formats
+
+The fields SHOULD be recorded according to the customary approach used for a
+particular format (e.g. field:value format for LTSV). For example:
+
+```
+host:192.168.0.1trace_id:102981ABCD2901span_id:abcdef1010time:[01/Jan/2010:10:11:23 -0400]req:GET /health HTTP/1.0status:200
+```
+
+### JSON Formats
+
+The fields SHOULD be recorded as top-level fields in the JSON structure. For example:
+
+```json
+{
+ "timestamp":1581385157.14429,
+ "body":"Incoming request",
+ "trace_id":"102981ABCD2901",
+ "span_id":"abcdef1010"
+}
+```
+
+### Other Structured Formats
+
+The fields SHOULD be recorded as top-level structured attributes of the log
+record as it is customary for the particular format.
diff --git a/specification/logs/README.md b/specification/logs/README.md
index e9fe2996d6b..957ea604b03 100644
--- a/specification/logs/README.md
+++ b/specification/logs/README.md
@@ -25,11 +25,6 @@ aliases: [/docs/reference/specification/logs/overview]
- [OpenTelemetry Collector](#opentelemetry-collector)
- [Auto-Instrumenting Existing Logging](#auto-instrumenting-existing-logging)
- [Specifications](#specifications)
-- [Trace Context in Legacy Formats](#trace-context-in-legacy-formats)
- * [Syslog RFC5424](#syslog-rfc5424)
- * [Plain Text Formats](#plain-text-formats)
- * [JSON Formats](#json-formats)
- * [Other Structured Formats](#other-structured-formats)
@@ -329,7 +324,8 @@ The benefit of using an intermediary medium is that how logs are produced and
where they are written by the application requires no or minimal changes. The
downside is that it requires the often non-trivial log file reading and parsing
functionality. Parsing may also be not reliable if the output format is not
-well-defined.
+well-defined. For details on recording and parsing trace context,
+see [Trace Context in Non-OTLP Log Formats](../compatibility/logging_trace_context.md).
#### Direct to Collector
@@ -449,57 +445,4 @@ standard output.
* [Logs Data Model](./data-model.md)
* [Event API](./event-api.md)
* [Semantic Conventions](./semantic_conventions/README.md)
-
-## Trace Context in Legacy Formats
-
-Earlier we briefly mentioned that it is possible to modify existing applications
-so that they include the Request Context information in the emitted logs.
-
-[OTEP0114](https://github.com/open-telemetry/oteps/pull/114) defines how the
-trace context should be recorded in logs. To summarize, the following field
-names should be used in legacy formats:
-
-- "trace_id" for [TraceId](data-model.md#field-traceid), hex-encoded.
-- "span_id" for [SpanId](data-model.md#field-spanid), hex-encoded.
-- "trace_flags" for [trace flags](data-model.md#field-traceflags), formatted
- according to W3C traceflags format.
-
-All 3 fields are optional (see the [data model](data-model.md) for details of
-which combination of fields is considered valid).
-
-### Syslog RFC5424
-
-Trace id, span id and traceflags SHOULD be recorded via SD-ID "opentelemetry".
-
-For example:
-
-```
-[opentelemetry trace_id="102981ABCD2901" span_id="abcdef1010" trace_flags="01"]
-```
-
-### Plain Text Formats
-
-The fields should be recorded according to the customary approach used for a
-particular format (e.g. field:value format for LTSV). For example:
-
-```
-host:192.168.0.1trace_id:102981ABCD2901span_id:abcdef1010time:[01/Jan/2010:10:11:23 -0400]req:GET /health HTTP/1.0status:200
-```
-
-### JSON Formats
-
-The fields should be recorded as top-level fields in the JSON structure. For example:
-
-```json
-{
- "timestamp":1581385157.14429,
- "body":"Incoming request",
- "trace_id":"102981ABCD2901",
- "span_id":"abcdef1010"
-}
-```
-
-### Other Structured Formats
-
-The fields should be recorded as top-level structured attributes of the log
-record as it is customary for the particular format.
+* [Trace Context in non-OTLP Log Formats](../compatibility/logging_trace_context.md)
From 2f076fafb0dfa9c0a6fefb4068617e365b8068fa Mon Sep 17 00:00:00 2001
From: Reiley Yang
Date: Thu, 23 Mar 2023 10:53:50 -0700
Subject: [PATCH 02/36] Fix changelog (#3330)
Follow up #3097.
Co-authored-by: Cijo Thomas
---
CHANGELOG.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2684e7ef095..50ef6f91a45 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,6 +41,8 @@ release.
([#3271](https://github.com/open-telemetry/opentelemetry-specification/pull/3271))
- BREAKING: remove `messaging.destination.kind` and `messaging.source.kind`.
([#3214](https://github.com/open-telemetry/opentelemetry-specification/pull/3214))
+- Define attributes collected for `cosmosdb` by Cosmos DB SDK
+ ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
### Compatibility
@@ -114,8 +116,6 @@ release.
([#3190](https://github.com/open-telemetry/opentelemetry-specification/pull/3190))
- Expand the declaration of `pool.name`.
([#3050](https://github.com/open-telemetry/opentelemetry-specification/pull/3050))
-- Define attributes collected for `cosmosdb` by Cosmos DB SDK
- ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
### Compatibility
From 710cea75830179f553a2aa47dea1bc9ebac000cb Mon Sep 17 00:00:00 2001
From: Tristan Sloughter
Date: Fri, 24 Mar 2023 12:05:38 -0600
Subject: [PATCH 03/36] erlang/elixir: add stacktrace representation to table
(#3313)
Adds the functions to use for stacktrace representation in Erlang/Elixir
to the semantic conventions table for exceptions.
---
specification/trace/semantic_conventions/exceptions.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/specification/trace/semantic_conventions/exceptions.md b/specification/trace/semantic_conventions/exceptions.md
index 33d7e1f6f0c..234eb710fed 100644
--- a/specification/trace/semantic_conventions/exceptions.md
+++ b/specification/trace/semantic_conventions/exceptions.md
@@ -82,6 +82,8 @@ to adopt them if they see fit.
| Language | Format |
| ---------- | ------------------------------------------------------------------- |
| C# | the return value of [Exception.ToString()][csharp-stacktrace] |
+| Elixir | the return value of [Exception.format/3][elixir-stacktrace] |
+| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] |
| Go | the return value of [runtime.Stack][go-stacktrace] |
| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] |
| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 |
@@ -101,3 +103,5 @@ grained information from a stacktrace, if necessary.
[csharp-stacktrace]: https://docs.microsoft.com/en-us/dotnet/api/system.exception.tostring
[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack
[telemetry-sdk-resource]: ../../resource/semantic_conventions/README.md#telemetry-sdk
+[erlang-stacktrace]: https://www.erlang.org/doc/man/erl_error.html#format_exception-3
+[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3
From 68151ed4afbae29523468d2d20718564687a2db0 Mon Sep 17 00:00:00 2001
From: Bertrand Martin <32521698+bertysentry@users.noreply.github.com>
Date: Sat, 25 Mar 2023 01:29:20 +0100
Subject: [PATCH 04/36] Issue #3236 Update attribute requirement levels in
hardware metrics semconv (#3258)
Fixes #3236
## Changes
* Update attributes requirement levels in
`specification\metrics\semantic_conventions\hardware-metrics.md`
* Minor wording corrections
---
CHANGELOG.md | 4 +
.../semantic_conventions/hardware-metrics.md | 240 +++++++++---------
2 files changed, 125 insertions(+), 119 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 50ef6f91a45..8fb4679f105 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -116,6 +116,10 @@ release.
([#3190](https://github.com/open-telemetry/opentelemetry-specification/pull/3190))
- Expand the declaration of `pool.name`.
([#3050](https://github.com/open-telemetry/opentelemetry-specification/pull/3050))
+- Define attributes collected for `cosmosdb` by Cosmos DB SDK
+ ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
+- Fixed attributes requirement level in semantic conventions for hardware metrics
+ ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
### Compatibility
diff --git a/specification/metrics/semantic_conventions/hardware-metrics.md b/specification/metrics/semantic_conventions/hardware-metrics.md
index ed256fddf47..c6cc24e2729 100644
--- a/specification/metrics/semantic_conventions/hardware-metrics.md
+++ b/specification/metrics/semantic_conventions/hardware-metrics.md
@@ -38,14 +38,13 @@ when creating instruments not explicitly defined in the specification.
All metrics in `hw.` instruments should be attached to a [Host Resource](../../resource/semantic_conventions/host.md)
and therefore inherit its attributes, like `host.id` and `host.name`.
-Additionally, it is recommended that all metrics in `hw.` instruments have the
-below attributes:
+Additionally, all metrics in `hw.` instruments have the following attributes:
| Attribute Key | Description | Example | Requirement Level |
-| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |-------------------|
-| `id` | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | Required |
+| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- |
+| `id` | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | **Required** |
| `name` | An easily-recognizable name for the hardware component | `eth0` | Recommended |
-| `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Opt-In |
+| `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Recommended |
## Metric Instruments
@@ -53,19 +52,19 @@ below 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 |
-| ----------- | ---------------------------------------------------------------------------------- | -------- | ------------------------------------------------- | ---------- | ------------------ | -------------------------- |
-| `hw.energy` | Energy consumed by the component, in joules | J | Counter | Int64 | | |
-| `hw.errors` | Number of errors encountered by the component | {error} | Counter | Int64 | `type` (optional) | |
-| `hw.power` | Instantaneous power consumed by the component, in Watts (`hw.energy` is preferred) | W | Gauge | Double | | |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed` |
+| Name | Description | Units | Instrument Type ([*](README.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 | `type` (Recommended) | |
+| `hw.power` | Instantaneous power consumed by the component, in Watts (`hw.energy` is preferred) | W | Gauge | Double | | |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
These common `hw.` metrics must include the below attributes to describe the
monitored component:
| Attribute Key | Description | Example | Requirement Level |
| ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
-| `hw.type` | Type of the component | `battery`, `cpu`, `disk_controller`, `enclosure`, `fan`, `gpu`, `logical_disk`, `memory`, `network`, `physical_disk`, `power_supply`, `tape_drive`, `temperature`, `voltage` | Required |
+| `hw.type` | Type of the component | `battery`, `cpu`, `disk_controller`, `enclosure`, `fan`, `gpu`, `logical_disk`, `memory`, `network`, `physical_disk`, `power_supply`, `tape_drive`, `temperature`, `voltage` | **Required** |
> **Warning**
>
@@ -84,22 +83,25 @@ Examples: physical server, switch or disk array.
| `hw.host.power` | Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred) | W | Gauge | Double | | |
> **Note**
-> Host energy usage MUST be reported using the specific `hw.host.energy` and `hw.host.power` metrics only, instead of the generic `hw.energy` and `hw.power` described in the previous section, to prevent summing up overlapping values.
+> The overall energy usage of a host MUST be reported using the specific
+> `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic
+> `hw.energy` and `hw.power` described in the previous section, to prevent
+> summing up overlapping values.
### `hw.battery.` - Battery metrics
**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 |
-| ------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------------- |
-| `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` |
-| `hw.battery.time_left` | Time left before battery is completely charged or discharged | s | Gauge | Int | `state` (recommended) | `charging`, `discharging` |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed`, `charging`, `discharging` |
-| | | | | | `hw.type` | `battery` |
+| Name | Description | Units | Instrument Type ([*](README.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` |
+| `hw.battery.time_left` | Time left before battery is completely charged or discharged | s | Gauge | Int | `state` (Conditionally Required, if the battery is charging or discharging) | `charging`, `discharging` |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `charging`, `discharging` |
+| | | | | | `hw.type` | `battery` |
-All `hw.battery.` metrics may include the below **optional** attributes to describe the
-characteristics of the monitored battery:
+All `hw.battery.` metrics may include the below **Recommended** attributes to
+describe the characteristics of the monitored battery:
| Attribute Key | Description | Example |
| ------------- | --------------------------------------------- | --------------------------- |
@@ -114,15 +116,15 @@ 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 |
-| -------------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------- |
-| `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 | | |
-| `hw.cpu.speed.limit` | CPU maximum frequency | Hz | Gauge | Int64 | `limit_type` (recommended) | `throttled`, `max`, `turbo` |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed`, `predicted_failure` |
-| | | | | | `hw.type` (required) | `cpu` |
+| Name | Description | Units | Instrument Type ([*](README.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 | | |
+| `hw.cpu.speed.limit` | CPU maximum frequency | Hz | Gauge | Int64 | `limit_type` (Recommended) | `throttled`, `max`, `turbo` |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` |
+| | | | | | `hw.type` (**Required**) | `cpu` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ------------- | ---------------------- | ------- |
@@ -134,12 +136,12 @@ Additional **optional** 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 |
-| ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------- | -------------------------- |
-| `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` |
+| Name | Description | Units | Instrument Type ([*](README.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` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ------------------ | ------------------------- | ------- |
@@ -154,12 +156,12 @@ Additional **optional** attributes:
**Description:** Computer chassis (can be an expansion enclosure)
-| Name | Description | Units | Instrument Type ([*](README.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` |
+| Name | Description | Units | Instrument Type ([*](README.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` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| --------------- | -------------------------------------------------- | ------------------------- |
@@ -174,15 +176,15 @@ Additional **optional** 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 |
-| -------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ------------------------------------- |
-| `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` |
-| `hw.fan.speed_ratio` | Fan speed expressed as a fraction of its maximum speed | 1 | Gauge | Double | | |
-| `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) | `fan` |
+| Name | Description | Units | Instrument Type ([*](README.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` |
+| `hw.fan.speed_ratio` | Fan speed expressed as a fraction of its maximum speed | 1 | Gauge | Double | | |
+| `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**) | `fan` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ----------------- | --------------------------------------------- | ---------------- |
@@ -192,20 +194,20 @@ Additional **optional** attributes:
**Description:** Graphics Processing Unit (discrete)
-| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
-| --------------------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------- | ---------- | ---------------------- | ----------------------------------------------- |
-| `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `type` (recommended) | `corrected`, `all` |
-| | | | | | `hw.type` (required) | `gpu` |
-| `hw.gpu.io` | Received and transmitted bytes by the GPU | By | Counter | Int64 | `direction` (required) | `receive`, `transmit` |
-| `hw.gpu.memory.limit` | Size of the GPU memory | By | UpDownCounter | Int64 | | |
-| `hw.gpu.memory.utilization` | Fraction of GPU memory used | 1 | Gauge | Double | | |
-| `hw.gpu.memory.usage` | GPU memory used | By | UpDownCounter | Int64 | | |
-| `hw.gpu.power` | GPU instantaneous power consumption in Watts | W | Gauge | Double | | |
-| `hw.gpu.utilization` | Fraction of time spent in a specific task | 1 | Gauge | Double | `task` (recommended) | `decoder`, `encoder`, `general` |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed`, `predicted_failure` |
-| | | | | | `hw.type` (required) | `gpu` |
-
-Additional **optional** attributes:
+| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
+| --------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------- |
+| `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `type` (Recommended) | `corrected`, `all` |
+| | | | | | `hw.type` (**Required**) | `gpu` |
+| `hw.gpu.io` | Received and transmitted bytes by the GPU | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
+| `hw.gpu.memory.limit` | Size of the GPU memory | By | UpDownCounter | Int64 | | |
+| `hw.gpu.memory.utilization` | Fraction of GPU memory used | 1 | Gauge | Double | | |
+| `hw.gpu.memory.usage` | GPU memory used | By | UpDownCounter | Int64 | | |
+| `hw.gpu.power` | GPU instantaneous power consumption in Watts | W | Gauge | Double | | |
+| `hw.gpu.utilization` | Fraction of time spent in a specific task | 1 | Gauge | Double | `task` (Recommended) | `decoder`, `encoder`, `general` |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` |
+| | | | | | `hw.type` (**Required**) | `gpu` |
+
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ------------------ | ------------------------- | ------- |
@@ -221,16 +223,16 @@ Additional **optional** 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 |
-| ----------------------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------- | ---------- | -------------------- | -------------------------- |
-| `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 | | |
-| `hw.logical_disk.usage` | Logical disk space usage | By | UpDownCounter | Int64 | `state` (required) | `used`, `free` |
-| `hw.logical_disk.utilization` | Logical disk space utilization as a fraction | 1 | Gauge | Double | `state` (required) | `used`, `free` |
-| `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) | `logical_disk` |
+| Name | Description | Units | Instrument Type ([*](README.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 | | |
+| `hw.logical_disk.usage` | Logical disk space usage | By | UpDownCounter | Int64 | `state` (**Required**) | `used`, `free` |
+| `hw.logical_disk.utilization` | Logical disk space utilization as a fraction | 1 | Gauge | Double | `state` (**Required**) | `used`, `free` |
+| `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**) | `logical_disk` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ------------- | ----------- | --------- |
@@ -240,14 +242,14 @@ Additional **optional** attributes:
**Description:** A memory module in a computer system.
-| Name | Description | Units | Instrument Type ([*](README.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 | | |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed`, `predicted_failure` |
-| | | | | | `hw.type` (required) | `memory` |
+| Name | Description | Units | Instrument Type ([*](README.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 | | |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` |
+| | | | | | `hw.type` (**Required**) | `memory` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| --------------- | ------------------------- | ------- |
@@ -262,19 +264,19 @@ Additional **optional** attributes:
(NIC), excluding virtual adapters and loopbacks. Examples: an Ethernet adapter,
an HBA, an fiber channel port or a Wi-Fi adapter.
-| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------- | ---------- | ---------------------- | --------------------------- |
-| `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `type` (recommended) | `all`, `zero_buffer_credit` |
-| | | | | | `hw.type` (required) | `network` |
-| `hw.network.bandwidth.limit` | Link speed | By | UpDownCounter | Int64 | | |
-| `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | |
-| `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (required) | `receive`, `transmit` |
-| `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (required) | `receive`, `transmit` |
-| `hw.network.up` | Link status: `1` (up) or `0` (down) | | UpDownCounter | Int | | |
-| `hw.status` | Operational status, regardless of the link status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed` |
-| | | | | | `hw.type` (required) | `network` |
+| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | -------------------------- | --------------------------- |
+| `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `type` (Recommended) | `all`, `zero_buffer_credit` |
+| | | | | | `hw.type` (**Required**) | `network` |
+| `hw.network.bandwidth.limit` | Link speed | By | UpDownCounter | Int64 | | |
+| `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | |
+| `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
+| `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
+| `hw.network.up` | Link status: `1` (up) or `0` (down) | | UpDownCounter | Int | | |
+| `hw.status` | Operational status, regardless of the link status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
+| | | | | | `hw.type` (**Required**) | `network` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ------------------- | ----------------------------------------------------------- | --------------------------- |
@@ -288,16 +290,16 @@ Additional **optional** attributes:
**Description:** Physical hard drive (HDD or SDD)
-| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- |
-| `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.type` (required) | `physical_disk` |
-| `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk | 1 | Gauge | Double | `state` (required) | `remaining` |
-| `hw.physical_disk.size` | Size of the disk | By | UpDownCounter | Int64 | | |
-| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed`, `predicted_failure` |
-| | | | | | `hw.type` (required) | `physical_disk` |
+| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- |
+| `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.type` (**Required**) | `physical_disk` |
+| `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk | 1 | Gauge | Double | `state` (**Required**) | `remaining` |
+| `hw.physical_disk.size` | Size of the disk | By | UpDownCounter | Int64 | | |
+| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` |
+| | | | | | `hw.type` (**Required**) | `physical_disk` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ------------------ | ---------------------- | ------------------- |
@@ -314,12 +316,12 @@ motherboard and the GPUs
| Name | Description | Units | Instrument Type ([*](README.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.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 | | |
-| `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) | `power_supply` |
+| `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**) | `power_supply` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| --------------- | ---------------------- | ------- |
@@ -332,14 +334,14 @@ Additional **optional** 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 |
-| -------------------------- | ----------------------------------------------------------------------------- | ------------ | ------------------------------------------------- | ---------- | -------------------- | -------------------------------------------- |
-| `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.type` | `tape_drive` |
-| `hw.tape_drive.operations` | Operations performed by the tape drive | {operation} | Counter | Int64 | `type` (recommended) | `mount`, `unmount`, `clean` |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed`, `needs_cleaning` |
-| | | | | | `hw.type` (required) | `tape_drive` |
+| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
+| -------------------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------------------------- |
+| `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.type` | `tape_drive` |
+| `hw.tape_drive.operations` | Operations performed by the tape drive | {operation} | Counter | Int64 | `type` (Recommended) | `mount`, `unmount`, `clean` |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `needs_cleaning` |
+| | | | | | `hw.type` (**Required**) | `tape_drive` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| --------------- | ---------------------- | ------- |
@@ -354,11 +356,11 @@ Additional **optional** attributes:
| Name | Description | Units | Instrument Type ([*](README.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` |
-| `hw.status` | Whether the temperature is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed` |
-| | | | | | `hw.type` (required) | `temperature` |
+| `hw.temperature.limit` | Temperature limit in degrees Celsius | Cel | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` |
+| `hw.status` | Whether the temperature is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
+| | | | | | `hw.type` (**Required**) | `temperature` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ----------------- | ---------------------- | ---------- |
@@ -370,13 +372,13 @@ Additional **optional** attributes:
| Name | Description | Units | Instrument Type ([*](README.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.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 | | |
-| `hw.voltage` | Measured voltage by the sensor | V | Gauge | Double | | |
-| `hw.status` | Whether the voltage is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (required) | `ok`, `degraded`, `failed` |
-| | | | | | `hw.type` (required) | `voltage` |
+| `hw.voltage` | Voltage measured by the sensor | V | Gauge | Double | | |
+| `hw.status` | Whether the voltage is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
+| | | | | | `hw.type` (**Required**) | `voltage` |
-Additional **optional** attributes:
+Additional **Recommended** attributes:
| Attribute Key | Description | Example |
| ----------------- | ---------------------- | ---------- |
From feabaab98bd94b59abbe294c8f7e0294926e1fdd Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Mon, 27 Mar 2023 09:12:16 -0500
Subject: [PATCH 05/36] Ensure logs bridge API doesn't contain implementation
details (#3275)
Contributes to #3268.
@MrAlias did some good work in the metrics API / SDK recently in #3171
and #3067 to ensure that the metrics API spec doesn't contain SDK
implementation details.
This PR adopts similar language in the Logs Bridge API / SDK documents,
which includes breaking out a `noop.md` document.
---
CHANGELOG.md | 2 +
specification/logs/bridge-api.md | 114 +++++++++++++++----------------
specification/logs/event-api.md | 4 +-
specification/logs/noop.md | 57 ++++++++++++++++
specification/logs/sdk.md | 61 ++++++++++++-----
5 files changed, 161 insertions(+), 77 deletions(-)
create mode 100644 specification/logs/noop.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8fb4679f105..3a8d26f94c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,8 @@ release.
([#3334](https://github.com/open-telemetry/opentelemetry-specification/pull/3334))
- Break out compatibility document on recording trace context in non-OTLP Log Format
([#3331](https://github.com/open-telemetry/opentelemetry-specification/pull/3331))
+- Ensure Logs Bridge API doesn't contain SDK implementation details
+ ([#3275](https://github.com/open-telemetry/opentelemetry-specification/pull/3275))
### Resource
diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md
index dbbdaaf9791..869714420b3 100644
--- a/specification/logs/bridge-api.md
+++ b/specification/logs/bridge-api.md
@@ -16,6 +16,8 @@
* [Logger operations](#logger-operations)
+ [Emit LogRecord](#emit-logrecord)
- [LogRecord](#logrecord)
+- [Optional and required parameters](#optional-and-required-parameters)
+- [Concurrency requirements](#concurrency-requirements)
- [Usage](#usage)
* [How to Create Log4J Style Appender](#how-to-create-log4j-style-appender)
* [Implicit Context Injection](#implicit-context-injection)
@@ -53,13 +55,6 @@ Normally, the `LoggerProvider` is expected to be accessed from a central place.
Thus, the API SHOULD provide a way to set/register and access a global default
`LoggerProvider`.
-Notwithstanding any global `LoggerProvider`, some applications may want to or have
-to use multiple `LoggerProvider` instances, e.g. to have different configuration
-(like [LogRecordProcessors](sdk.md#logrecordprocessor)) for each (and
-consequently for the `Logger`s obtained from them), or because it's easier with
-dependency injection frameworks. Thus, implementations of `LoggerProvider` SHOULD
-allow creating an arbitrary number of instances.
-
### LoggerProvider operations
The `LoggerProvider` MUST provide the following functions:
@@ -70,57 +65,39 @@ The `LoggerProvider` MUST provide the following functions:
This API MUST accept the following parameters:
-- `name` (required): This name SHOULD uniquely identify the [instrumentation scope](../glossary.md#instrumentation-scope),
-such as the [instrumentation library](../glossary.md#instrumentation-library)
-(e.g. `io.opentelemetry.contrib.mongodb`), package, module or class name.
-If an application or library has built-in OpenTelemetry instrumentation, both
-[Instrumented library](../glossary.md#instrumented-library) and
-[Instrumentation library](../glossary.md#instrumentation-library) may refer to
-the same library. In that scenario, the `name` denotes a module name or component
-name within that library or application. In case an invalid name
-(null or empty string) is specified, a working Logger implementation MUST be
-returned as a fallback rather than returning null or throwing an exception, its
-`name` property SHOULD be set to an empty string, and a message reporting that
-the specified value is invalid SHOULD be logged. A library implementing the
-OpenTelemetry API may also ignore this name and return a default instance for
-all calls, if it does not support "named" functionality (e.g. an implementation
-which is not even observability-related). A `LoggerProvider` could also return a
-no-op `Logger` here if application owners configure the SDK to suppress telemetry
-produced by this library.
-- `version` (optional): Specifies the version of the instrumentation scope if
-the scope has a version (e.g. a library version). Example value: 1.0.0.
-- `schema_url` (optional): Specifies the Schema URL that should be recorded in
-the emitted telemetry.
-- `include_trace_context` (optional): Specifies whether the Trace Context should
- automatically be passed on to the `LogRecord`s emitted by the `Logger`. This
- SHOULD be true by default.
-- `attributes` (optional): Specifies the instrumentation scope attributes to
-associate with emitted telemetry.
+* `name`: This name uniquely identifies the [instrumentation scope](../glossary.md#instrumentation-scope),
+ such as the [instrumentation library](../glossary.md#instrumentation-library)
+ (e.g. `io.opentelemetry.contrib.mongodb`), package, module or class name.
+ If an application or library has built-in OpenTelemetry instrumentation, both
+ [Instrumented library](../glossary.md#instrumented-library) and
+ [Instrumentation library](../glossary.md#instrumentation-library) may refer to
+ the same library. In that scenario, the `name` denotes a module name or component
+ name within that library or application.
+
+* `version` (optional): Specifies the version of the instrumentation scope if
+ the scope has a version (e.g. a library version). Example value: 1.0.0.
+
+* `schema_url` (optional): Specifies the Schema URL that should be recorded in
+ the emitted telemetry.
+
+* `attributes` (optional): Specifies the instrumentation scope attributes to
+ associate with emitted telemetry. This API MUST be structured to accept a
+ variable number of attributes, including none.
+
+* `include_trace_context` (optional): Specifies whether the Trace Context should
+ automatically be passed on to the `LogRecord`s emitted by the `Logger`.
+ If `include_trace_context` is not specified, it SHOULD be `true` by default.
`Logger`s are identified by `name`, `version`, and `schema_url` fields. When more
than one `Logger` of the same `name`, `version`, and `schema_url` is created, it
is unspecified whether or under which conditions the same or different `Logger`
instances are returned. It is a user error to create Loggers with different
-attributes but the same identity.
+`include_trace_context` or `attributes` but the same identity.
The term *identical* applied to `Logger`s describes instances where all
identifying fields are equal. The term *distinct* applied to `Logger`s describes
instances where at least one identifying field has a different value.
-Implementations MUST NOT require users to repeatedly obtain a `Logger` again with
-the same name+version+schema_url+include_trace_context+attributes
-to pick up configuration changes. This can be achieved either by allowing to
-work with an outdated configuration or by ensuring that new configuration
-applies also to previously returned `Logger`s.
-
-Note: This could, for example, be implemented by storing any mutable
-configuration in the `LoggerProvider` and having `Logger` implementation objects
-have a reference to the `LoggerProvider` from which they were obtained.
-If configuration must be stored per-Logger (such as disabling a certain `Logger`),
-the `Logger` could, for example, do a look-up with its name+version+schema_url+include_trace_context+attributes
-in a map in the `LoggerProvider`, or the `LoggerProvider` could maintain a registry
-of all returned `Logger`s and actively update their configuration if it changes.
-
The effect of associating a Schema URL with a `Logger` MUST be that the telemetry
emitted using the `Logger` will be associated with the Schema URL, provided that
the emitted data format is capable of representing such association.
@@ -129,9 +106,6 @@ the emitted data format is capable of representing such association.
The `Logger` is responsible for emitting `LogRecord`s.
-Note that `Logger`s should not be responsible for configuration. This should be
-the responsibility of the `LoggerProvider` instead.
-
### Logger operations
The `Logger` MUST provide functions to:
@@ -151,7 +125,7 @@ This function MAY be named `logRecord`.
The API emits [LogRecords](#emit-logrecord) using the `LogRecord` [data model](data-model.md).
A function receiving this as an argument MUST be able to set the following
-fields:
+parameters:
- [Timestamp](./data-model.md#field-timestamp)
- [Observed Timestamp](./data-model.md#field-observedtimestamp)
@@ -162,20 +136,42 @@ fields:
- [Body](./data-model.md#field-body)
- [Attributes](./data-model.md#field-attributes)
+All parameters are optional.
+
+## Optional and required parameters
+
+The operations defined include various parameters, some of which are marked
+optional. Parameters not marked optional are required.
+
+For each optional parameter, the API MUST be structured to accept it, but MUST
+NOT obligate a user to provide it.
+
+For each required parameter, the API MUST be structured to obligate a user to
+provide it.
+
+## Concurrency requirements
+
+For languages which support concurrent execution the Logs Bridge APIs provide
+specific guarantees and safeties.
+
+**LoggerProvider** - all methods are safe to be called concurrently.
+
+**Logger** - all methods are safe to be called concurrently.
+
## Usage
### How to Create Log4J Style Appender
-An Appender implementation can be used to allow emitting logs via
+An Appender implementation can be used to bridge logs into the [Log SDK](./sdk.md)
OpenTelemetry [LogRecordExporters](sdk.md#logrecordexporter). This approach is
typically used for applications which are fine with changing the log transport
and is [one of the supported](README.md#direct-to-collector) log collection
approaches.
The Appender implementation will typically acquire a [Logger](#logger) from the
-global [LoggerProvider](#loggerprovider) at startup time, then construct
-`LogRecord`s for each log received from the application, and then call
-[Emit LogRecord](#emit-logrecord).
+global [LoggerProvider](#loggerprovider) at startup time, then
+call [Emit LogRecord](#emit-logrecord) for `LogRecord`s received from the
+application.
[Implicit Context Injection](#implicit-context-injection)
and [Explicit Context Injection](#explicit-context-injection) describe how an
@@ -198,9 +194,9 @@ popular logging library.
### Implicit Context Injection
-When Context is implicitly available (e.g. in Java) the log library extension
-can rely on automatic context propagation
-by [obtaining a Logger](#get-a-logger) with `include_trace_context=true`.
+When Context is implicitly available (e.g. in Java) the Appender can rely on
+automatic context propagation by [obtaining a Logger](#get-a-logger)
+with `include_trace_context=true`.
Some log libraries have mechanisms specifically tailored for injecting contextual
information into logs, such as MDC in Log4j. When available such mechanisms may
diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md
index b2e8f687904..f9075d16104 100644
--- a/specification/logs/event-api.md
+++ b/specification/logs/event-api.md
@@ -50,7 +50,7 @@ instrumentation authors are encouraged to call this API directly.
## EventLogger
The `EventLogger` is the entrypoint of the Event API, and is responsible for
-emitting `Events` as `LogRecords`.
+emitting `Events` as `LogRecord`s.
### EventLogger Operations
@@ -64,7 +64,7 @@ on `EventLogger`.
**Parameters:**
* `logger` - the delegate [Logger](./bridge-api.md#logger) used to emit `Events`
- as `LogRecords`.
+ as `LogRecord`s.
* `event_domain` - the domain of emitted events, used to set the `event.domain`
attribute.
diff --git a/specification/logs/noop.md b/specification/logs/noop.md
new file mode 100644
index 00000000000..896e11721f3
--- /dev/null
+++ b/specification/logs/noop.md
@@ -0,0 +1,57 @@
+
+
+# Logs Bridge API No-Op Implementation
+
+**Status**: [Experimental](../document-status.md)
+
+
+ Table of Contents
+
+
+
+- [LoggerProvider](#loggerprovider)
+ * [Logger Creation](#logger-creation)
+- [Logger](#logger)
+ * [Emit LogRecord](#emit-logrecord)
+
+
+
+
+
+Users of OpenTelemetry need a way to disable the API from actually
+performing any operations. The No-Op OpenTelemetry API implementation
+(henceforth referred to as the No-Op) provides users with this
+functionally. It implements the [OpenTelemetry Logs Bridge API](./bridge-api.md)
+so that no telemetry is produced and computation resources are minimized.
+
+All language implementations of OpenTelemetry MUST provide a No-Op.
+
+The [Logs Bridge API](./bridge-api.md) defines classes with various operations.
+All No-Op classes MUST NOT hold configuration or operational state. All No-op
+operations MUST accept all defined parameters, MUST NOT validate any arguments
+received, and MUST NOT return any non-empty error or log any message.
+
+## LoggerProvider
+
+The No-Op MUST allow the creation of multiple `LoggerProviders`s.
+
+Since all `LoggerProviders`s hold the same empty state, a No-Op MAY
+provide the same `LoggerProvider` instances to all creation requests.
+
+### Logger Creation
+
+New `Logger` instances are always created with a [LoggerProvider](./bridge-api.md#loggerprovider).
+Therefore, `LoggerProvider` MUST allow for the creation of `Logger`s.
+All `Logger`s created MUST be an instance of the [No-Op Logger](#logger).
+
+Since all `Logger`s will hold the same empty state, a `LoggerProvider` MAY
+return the same `Logger` instances to all creation requests.
+
+## Logger
+
+### Emit LogRecord
+
+The No-Op `Logger` MUST allow
+for [emitting LogRecords](./bridge-api.md#emit-logrecord).
diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md
index 9480efdd6ff..05d82d68e47 100644
--- a/specification/logs/sdk.md
+++ b/specification/logs/sdk.md
@@ -8,9 +8,11 @@
- [LoggerProvider](#loggerprovider)
+ * [LoggerProvider Creation](#loggerprovider-creation)
* [Logger Creation](#logger-creation)
* [Shutdown](#shutdown)
* [ForceFlush](#forceflush)
+- [Logger](#logger)
- [Additional LogRecord interfaces](#additional-logrecord-interfaces)
* [ReadableLogRecord](#readablelogrecord)
* [ReadWriteLogRecord](#readwritelogrecord)
@@ -33,20 +35,37 @@
+Users of OpenTelemetry need a way for instrumentation interactions with the
+OpenTelemetry API to actually produce telemetry. The OpenTelemetry Logging SDK
+(henceforth referred to as the SDK) is an implementation of the OpenTelemetry
+API that provides users with this functionally.
+
+All language implementations of OpenTelemetry MUST provide an SDK.
+
## LoggerProvider
A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md)
to be specified. If a `Resource` is specified, it SHOULD be associated with all
-the `LogRecords` produced by any `Logger` from the `LoggerProvider`.
+the `LogRecord`s produced by any `Logger` from the `LoggerProvider`.
+
+### LoggerProvider Creation
+
+The SDK SHOULD allow the creation of multiple independent `LoggerProviders`s.
### Logger Creation
New `Logger` instances are always created through a `LoggerProvider`
-(see [Bridge API](bridge-api.md)). The `name`, `version` (optional), and `attributes` (optional)
-supplied to the `LoggerProvider` must be used to create
+(see [Bridge API](bridge-api.md)). The `name`, `version` (optional),
+`schema_url` (optional), and `attributes` (optional) supplied to
+the `LoggerProvider` must be used to create
an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which
is stored on the created `Logger`.
+In the case where an invalid `name` (null or empty string) is specified, a
+working `Logger` MUST be returned as a fallback rather than returning null or
+throwing an exception, its `name` SHOULD keep the original invalid value, and a
+message reporting that the specified value is invalid SHOULD be logged.
+
Configuration (i.e. [LogRecordProcessors](#logrecordprocessor)) MUST be managed
solely by the `LoggerProvider` and the SDK MUST provide some way to configure
all options that are implemented by the SDK. This MAY be done at the time
@@ -54,7 +73,7 @@ of `LoggerProvider` creation if appropriate.
The `LoggerProvider` MAY provide methods to update the configuration. If
configuration is updated (e.g., adding a `LogRecordProcessor`), the updated
-configuration MUST also apply to all already returned `Loggers` (i.e. it MUST
+configuration MUST also apply to all already returned `Logger`s (i.e. it MUST
NOT matter whether a `Logger` was obtained from the `LoggerProvider` before or
after the configuration change). Note: Implementation-wise, this could mean
that `Logger` instances have a reference to their `LoggerProvider` and access
@@ -87,7 +106,7 @@ registered [LogRecordProcessors](#logrecordprocessor) to immediately export all
`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
failed or timed out. `ForceFlush` SHOULD return some **ERROR** status if there
-is an error condition; and if there is no error condition, it should return
+is an error condition; and if there is no error condition, it SHOULD return
some **NO ERROR** status, language implementations MAY decide how to model
**ERROR** and **NO ERROR**.
@@ -99,6 +118,15 @@ decide if they want to make the flush timeout configurable.
`ForceFlush` MUST invoke `ForceFlush` on all
registered [LogRecordProcessors](#logrecordprocessor).
+## Logger
+
+If a `Logger` was obtained with `include_trace_context=true`, the `LogRecord`s
+it [emits](./bridge-api.md#emit-logrecord) MUST automatically include the Trace
+Context from the active Context, if Context has not been explicitly set.
+
+Note that `Logger`s should not be responsible for configuration. This should be
+the responsibility of the `LoggerProvider` instead.
+
## Additional LogRecord interfaces
In addition to the [API-level definition for LogRecord](bridge-api.md#logrecord), the
@@ -130,7 +158,8 @@ that was added to the `LogRecord` (as with
## LogRecord Limits
-`LogRecord` attributes MUST adhere to the [common rules of attribute limits](../common/README.md#attribute-limits).
+`LogRecord` attributes MUST adhere to
+the [common rules of attribute limits](../common/README.md#attribute-limits).
If the SDK implements attribute limits it MUST provide a way to change these
limits, via a configuration to the `LoggerProvider`, by allowing users to
@@ -161,7 +190,7 @@ To prevent excessive logging, the message MUST be printed at most once per
`LogRecordProcessor` is an interface which allows hooks for `LogRecord`
emitting.
-Built-in processors are responsible for batching and conversion of `LogRecords`
+Built-in processors are responsible for batching and conversion of `LogRecord`s
to exportable representation and passing batches to exporters.
`LogRecordProcessors` can be registered directly on SDK `LoggerProvider` and
@@ -173,7 +202,7 @@ MUST allow each pipeline to end with an individual exporter.
The SDK MUST allow users to implement and configure custom processors and
decorate built-in processors for advanced scenarios such as enriching with
-attributes or filtering.
+attributes.
The following diagram shows `LogRecordProcessor`'s relationship to other
components in the SDK:
@@ -237,13 +266,13 @@ to make the shutdown timeout configurable.
#### ForceFlush
-This is a hint to ensure that any tasks associated with `LogRecords` for which
+This is a hint to ensure that any tasks associated with `LogRecord`s for which
the `LogRecordProcessor` had already received events prior to the call
to `ForceFlush` SHOULD be completed as soon as possible, preferably before
returning from this method.
In particular, if any `LogRecordProcessor` has any associated exporter, it
-SHOULD try to call the exporter's `Export` with all `LogRecords` for which this
+SHOULD try to call the exporter's `Export` with all `LogRecord`s for which this
was not already done and then invoke `ForceFlush` on it.
The [built-in LogRecordProcessors](#built-in-processors) MUST do so. If a
timeout is specified (see below), the `LogRecordProcessor` MUST prioritize
@@ -257,7 +286,7 @@ failed or timed out.
`ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
such as when using some FaaS providers that may suspend the process after an
invocation, but before the `LogRecordProcessor` exports the
-completed `LogRecords`.
+emitted `LogRecord`s.
`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be
implemented as a blocking API or an asynchronous API which notifies the caller
@@ -267,7 +296,7 @@ make the flush timeout configurable.
### Built-in processors
The standard OpenTelemetry SDK MUST implement both simple and batch processors,
-as described below. Other common processing scenarios should be first considered
+as described below. Other common processing scenarios SHOULD be first considered
for implementation out-of-process
in [OpenTelemetry Collector](../overview.md#collector).
@@ -280,17 +309,17 @@ finished.
**Configurable parameters:**
-* `exporter` - the exporter where the `LogRecords` are pushed.
+* `exporter` - the exporter where the `LogRecord`s are pushed.
#### Batching processor
This is an implementation of the `LogRecordProcessor` which create batches
-of `LogRecords` and passes the export-friendly `ReadableLogRecord`
+of `LogRecord`s and passes the export-friendly `ReadableLogRecord`
representations to the configured `LogRecordExporter`.
**Configurable parameters:**
-* `exporter` - the exporter where the `LogRecords` are pushed.
+* `exporter` - the exporter where the `LogRecord`s are pushed.
* `maxQueueSize` - the maximum queue size. After the size is reached logs are
dropped. The default value is `2048`.
* `scheduledDelayMillis` - the delay interval in milliseconds between two
@@ -385,7 +414,7 @@ Shuts down the exporter. Called when SDK is shut down. This is an opportunity
for exporter to do any cleanup required.
Shutdown SHOULD be called only once for each `LogRecordExporter` instance. After
-the call to `Shutdown` subsequent calls to `Export` are not allowed and should
+the call to `Shutdown` subsequent calls to `Export` are not allowed and SHOULD
return a Failure result.
`Shutdown` SHOULD NOT block indefinitely (e.g. if it attempts to flush the data
From a50c9bfeebe931b67364d02007dd6ee7a368c002 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Mon, 27 Mar 2023 10:13:38 -0500
Subject: [PATCH 06/36] Fix changelog (#3343)
---
CHANGELOG.md | 6 ++----
1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3a8d26f94c8..fbd2674d52d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,8 @@ release.
- Clarify that units should use UCUM case sensitive variant.
([#3306](https://github.com/open-telemetry/opentelemetry-specification/pull/3306))
+- Fixed attributes requirement level in semantic conventions for hardware metrics
+ ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
### Logs
@@ -118,10 +120,6 @@ release.
([#3190](https://github.com/open-telemetry/opentelemetry-specification/pull/3190))
- Expand the declaration of `pool.name`.
([#3050](https://github.com/open-telemetry/opentelemetry-specification/pull/3050))
-- Define attributes collected for `cosmosdb` by Cosmos DB SDK
- ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
-- Fixed attributes requirement level in semantic conventions for hardware metrics
- ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
### Compatibility
From 0d51a1db003b03fa8602a58acc10ab86ce537723 Mon Sep 17 00:00:00 2001
From: Medik
Date: Mon, 27 Mar 2023 21:16:40 +0100
Subject: [PATCH 07/36] Update JS environment variable compliance (#3226)
---
.gitignore | 3 +++
spec-compliance-matrix.md | 22 +++++++++++-----------
2 files changed, 14 insertions(+), 11 deletions(-)
diff --git a/.gitignore b/.gitignore
index 71d4b9f93cc..c9508b6a86a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,3 +28,6 @@ internal/tools/bin
# Node.js files for tools (e.g. markdown-toc)
node_modules/
package-lock.json
+
+# Visual Studio Code
+.vscode
\ No newline at end of file
diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
index 00dda0e71c2..62c83eb481d 100644
--- a/spec-compliance-matrix.md
+++ b/spec-compliance-matrix.md
@@ -274,28 +274,28 @@ Note: Support for environment variables is optional.
| OTEL_SERVICE_NAME | + | + | + | + | + | + | + | | | + | |
| OTEL_LOG_LEVEL | - | - | + | [-][py1059] | + | - | - | | - | - | - |
| OTEL_PROPAGATORS | - | + | | + | + | + | + | - | - | - | - |
-| OTEL_BSP_* | + | + | | + | + | + | + | + | - | - | - |
+| OTEL_BSP_* | + | + | + | + | + | + | + | + | - | - | - |
| OTEL_BLRP_* | | + | | | | | | | | | |
| OTEL_EXPORTER_OTLP_* | + | + | | + | + | + | + | + | + | + | - |
| OTEL_EXPORTER_JAEGER_* | + | + | | + | + | - | - | | - | + | - |
| OTEL_EXPORTER_ZIPKIN_* | - | + | | + | + | - | + | - | - | + | - |
-| OTEL_TRACES_EXPORTER | - | + | | + | + | + | + | - | - | - | |
+| OTEL_TRACES_EXPORTER | - | + | + | + | + | + | + | - | - | - | |
| OTEL_METRICS_EXPORTER | - | + | | + | - | - | + | - | - | - | - |
| OTEL_LOGS_EXPORTER | - | + | | + | | | | | | - | |
-| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | + | + | | + | + | + | + | + | - | - | |
-| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | + | + | | + | + | + | + | | | - | |
-| OTEL_SPAN_EVENT_COUNT_LIMIT | + | + | | + | + | + | + | + | - | - | |
-| OTEL_SPAN_LINK_COUNT_LIMIT | + | + | | + | + | + | + | + | - | - | |
+| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | + | + | + | + | + | + | + | + | - | - | |
+| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | + | + | + | + | + | + | + | | | - | |
+| OTEL_SPAN_EVENT_COUNT_LIMIT | + | + | + | + | + | + | + | + | - | - | |
+| OTEL_SPAN_LINK_COUNT_LIMIT | + | + | + | + | + | + | + | + | - | - | |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | + | - | | + | + | + | + | | | - | |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | + | - | | + | + | + | + | | | - | |
-| OTEL_TRACES_SAMPLER | + | + | | + | + | + | + | - | - | - | |
-| OTEL_TRACES_SAMPLER_ARG | + | + | | + | + | + | + | - | - | - | |
-| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | + | + | | + | + | - | + | | | - | |
-| OTEL_ATTRIBUTE_COUNT_LIMIT | + | + | | + | + | - | + | | | - | |
+| OTEL_TRACES_SAMPLER | + | + | + | + | + | + | + | - | - | - | |
+| OTEL_TRACES_SAMPLER_ARG | + | + | + | + | + | + | + | - | - | - | |
+| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | + | + | + | + | + | - | + | | | - | |
+| OTEL_ATTRIBUTE_COUNT_LIMIT | + | + | + | + | + | - | + | | | - | |
| OTEL_METRIC_EXPORT_INTERVAL | - | + | | | | | + | | | - | |
| OTEL_METRIC_EXPORT_TIMEOUT | - | - | | | | | + | | | - | |
| OTEL_METRICS_EXEMPLAR_FILTER | - | + | | | | | + | | | - | |
-| OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | - | + | | + | | | | | | - | |
+| OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | - | + | + | + | | | | | | - | |
| OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION | | + | | | | | | | | | |
## Exporters
From 4e5bc754a1fd7062ac7cdc6922cf01051eb3c214 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Tue, 28 Mar 2023 06:29:14 -0500
Subject: [PATCH 08/36] Add log appender / bridge to glossary (#3335)
Co-authored-by: Reiley Yang
Co-authored-by: Armin Ruech
---
CHANGELOG.md | 2 ++
specification/glossary.md | 9 +++++++++
specification/logs/README.md | 12 ++++++------
specification/logs/bridge-api.md | 13 +++++++------
4 files changed, 24 insertions(+), 12 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fbd2674d52d..3f10348fd7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,8 @@ release.
([#3331](https://github.com/open-telemetry/opentelemetry-specification/pull/3331))
- Ensure Logs Bridge API doesn't contain SDK implementation details
([#3275](https://github.com/open-telemetry/opentelemetry-specification/pull/3275))
+- Add log appender / bridge to glossary.
+ ([#3335](https://github.com/open-telemetry/opentelemetry-specification/pull/3335))
### Resource
diff --git a/specification/glossary.md b/specification/glossary.md
index f464a5efec2..8263a4658b3 100644
--- a/specification/glossary.md
+++ b/specification/glossary.md
@@ -38,6 +38,7 @@ Some other fundamental terms are documented in the [overview document](overview.
* [Log Attributes](#log-attributes)
* [Structured Logs](#structured-logs)
* [Flat File Logs](#flat-file-logs)
+ * [Log Appender / Bridge](#log-appender--bridge)
@@ -234,3 +235,11 @@ records are possible too). There is no common industry agreement whether
logs written to text files in more structured formats (e.g. JSON files)
are considered Flat File Logs or not. Where such distinction is important it is
recommended to call it out specifically.
+
+### Log Appender / Bridge
+
+A log appender or bridge is a component which bridges logs from an existing log
+API into OpenTelemetry using the [Log Bridge API](./logs/bridge-api.md). The
+terms "log bridge" and "log appender" are used interchangeably, reflecting that
+these components bridge data into OpenTelemetry, but are often called appenders
+in the logging domain.
diff --git a/specification/logs/README.md b/specification/logs/README.md
index 957ea604b03..bbab7393330 100644
--- a/specification/logs/README.md
+++ b/specification/logs/README.md
@@ -139,7 +139,7 @@ Given the above state of the logging space we took the following approach:
- OpenTelemetry defines a Logs Bridge API
for [emitting LogRecords](./bridge-api.md#emit-logrecord). Application developers are
NOT encouraged to call this API directly. It is provided for library authors
- to build [Appenders](./bridge-api.md#how-to-create-log4j-style-appender), which use
+ to build [log appender](../glossary.md#log-appender--bridge), which use
the API to bridge between existing logging libraries and the OpenTelemetry log
data model. Existing logging libraries generally provide a much richer set of
features than what is defined in OpenTelemetry. It is NOT a goal of
@@ -292,8 +292,8 @@ collected from all applications that can be instrumented in this manner.
Some logging libraries are designed to be extended in this manner relatively
easily. There is no need to actually modify the libraries, instead we can
-implement "appender" or "exporter" components for such libraries and implement
-the additional LogRecord enrichment in these components.
+implement "log appender" or "log bridge" components for such libraries and
+implement the additional LogRecord enrichment in these components.
There are typically 2 ways to collect logs from these applications.
@@ -358,7 +358,7 @@ To facilitate both approaches described above OpenTelemetry provides
a [Bridge API](./bridge-api.md) and [SDK](./sdk.md), which can be used together with existing
logging libraries to automatically inject the trace context in the emitted logs,
and provide an easy way to send the logs via OTLP. Instead of
-modifying each logging statement, [Appenders](./bridge-api.md#how-to-create-log4j-style-appender)
+modifying each logging statement, [log appenders](../glossary.md#log-appender--bridge)
use the API to bridge logs from existing logging libraries to the OpenTelemetry
data model, where the SDK controls how the logs are processed and exported.
Application developers only need to configure the Appender and SDK at
@@ -369,8 +369,8 @@ application startup.
These are greenfield developments. OpenTelemetry provides recommendations and
best practices about how to emit logs (along with traces and metrics) from these
applications. For applicable languages and frameworks the auto-instrumentation
-or simple configuration of a logging library to use an OpenTelemetry appender or
-extension will still be the easiest way to emit context-enriched logs. As
+or simple configuration of a logging library to use an OpenTelemetry log appender
+will still be the easiest way to emit context-enriched logs. As
already described earlier we provide extensions to some popular logging
libraries languages to support the manual instrumentation cases. The extensions
will support the inclusion of the trace context in the logs and allow to send
diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md
index 869714420b3..a72fa0cf8f9 100644
--- a/specification/logs/bridge-api.md
+++ b/specification/logs/bridge-api.md
@@ -19,7 +19,7 @@
- [Optional and required parameters](#optional-and-required-parameters)
- [Concurrency requirements](#concurrency-requirements)
- [Usage](#usage)
- * [How to Create Log4J Style Appender](#how-to-create-log4j-style-appender)
+ * [How to Create a Log4J Log Appender](#how-to-create-a-log4j-log-appender)
* [Implicit Context Injection](#implicit-context-injection)
* [Explicit Context Injection](#explicit-context-injection)
@@ -29,7 +29,7 @@
Note: this document defines a log *backend* API. The API is not intended to be called
by application developers directly. It is provided for logging library authors
-to build [Appenders](#how-to-create-log4j-style-appender), which use
+to build [log appenders](#how-to-create-a-log4j-log-appender), which use
this API to bridge between existing logging libraries and the OpenTelemetry log
data model.
@@ -160,15 +160,16 @@ specific guarantees and safeties.
## Usage
-### How to Create Log4J Style Appender
+### How to Create a Log4J Log Appender
-An Appender implementation can be used to bridge logs into the [Log SDK](./sdk.md)
+A [log appender](../glossary.md#log-appender--bridge) implementation can be used
+to can be used to bridge logs into the [Log SDK](./sdk.md)
OpenTelemetry [LogRecordExporters](sdk.md#logrecordexporter). This approach is
typically used for applications which are fine with changing the log transport
and is [one of the supported](README.md#direct-to-collector) log collection
approaches.
-The Appender implementation will typically acquire a [Logger](#logger) from the
+The log appender implementation will typically acquire a [Logger](#logger) from the
global [LoggerProvider](#loggerprovider) at startup time, then
call [Emit LogRecord](#emit-logrecord) for `LogRecord`s received from the
application.
@@ -186,7 +187,7 @@ This same approach can be also used for example for:
there is no implicit Context in Go it is not possible to get and use the
active Span.
-Appenders can be created in OpenTelemetry language libraries by OpenTelemetry
+Log appenders can be created in OpenTelemetry language libraries by OpenTelemetry
maintainers, or by 3rd parties for any logging library that supports a similar
extension mechanism. This specification recommends each OpenTelemetry language
library to include out-of-the-box Appender implementation for at least one
From 294f58bac25b444e0c14ee13f39eb9ffb5238dea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20Kie=C5=82kowicz?=
Date: Tue, 28 Mar 2023 18:14:27 +0200
Subject: [PATCH 09/36] AWS Lambda - remove references to
messaging.destination.kind and messaging.source.kind (#3348)
---
CHANGELOG.md | 3 ++-
.../trace/semantic_conventions/instrumentation/aws-lambda.md | 1 -
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3f10348fd7b..ae4d3d93dd6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,7 +46,8 @@ release.
- Metric requirement levels are now stable
([#3271](https://github.com/open-telemetry/opentelemetry-specification/pull/3271))
- BREAKING: remove `messaging.destination.kind` and `messaging.source.kind`.
- ([#3214](https://github.com/open-telemetry/opentelemetry-specification/pull/3214))
+ ([#3214](https://github.com/open-telemetry/opentelemetry-specification/pull/3214),
+ [#3348](https://github.com/open-telemetry/opentelemetry-specification/pull/3348))
- Define attributes collected for `cosmosdb` by Cosmos DB SDK
([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md
index 16914ea0870..9c2eb2ae99f 100644
--- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md
+++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md
@@ -126,7 +126,6 @@ added as a link to the span.
- [`faas.trigger`][faas] MUST be set to `pubsub`.
- [`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`.
- [`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`.
-- [`messaging.destination.kind` or `messaging.source.kind`](../messaging.md#messaging-attributes) MUST be set to `queue`.
Other [Messaging attributes](../messaging.md#messaging-attributes) SHOULD be set based on the available information in the SQS message
event.
From 5b17de11418dceab372515ecab801fb7340eb428 Mon Sep 17 00:00:00 2001
From: Sourabh Jain
Date: Wed, 29 Mar 2023 22:14:40 +0530
Subject: [PATCH 10/36] Cosmos DB attributes: fixes UserAgent description
(#3338)
---
semantic_conventions/trace/database.yaml | 13 +++++++++++++
.../trace/semantic_conventions/database.md | 8 ++++++--
2 files changed, 19 insertions(+), 2 deletions(-)
diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml
index 36c4c31f168..af9ed4c3cb1 100644
--- a/semantic_conventions/trace/database.yaml
+++ b/semantic_conventions/trace/database.yaml
@@ -451,6 +451,19 @@ groups:
requirement_level:
conditionally_required: when performing one of the operations in this list
- ref: user_agent.original
+ brief: 'Full user-agent string is generated by Cosmos DB SDK'
+ note: >
+ The user-agent value is generated by SDK which is a combination of
+ `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
+ `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
+ `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
+ `type_of_machine_architecture` : Machine architecture. e.g. 'X64'
+ `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
+ `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
+ `failover_information` : Generated key to determine if region failover enabled.
+ Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it).
+ Default value is "NS".
+ examples: ['cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|']
- id: connection_mode
type:
allow_custom_values: false
diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md
index 9d3f0e46672..b3da889e4be 100644
--- a/specification/trace/semantic_conventions/database.md
+++ b/specification/trace/semantic_conventions/database.md
@@ -232,12 +232,16 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net
| `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received |
| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] |
| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available |
-| `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 |
+| `user_agent.original` | string | Full user-agent string is generated by Cosmos DB SDK [3] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | Recommended |
**[1]:** when performing one of the operations in this list
**[2]:** when response was received and contained sub-code.
+**[3]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled.
+ Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it).
+ Default value is "NS".
+
`db.cosmosdb.operation_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
@@ -336,7 +340,7 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an
| `net.peer.name` | `"account.documents.azure.com"` |
| `db.cosmosdb.client_id` | `3ba4827d-4422-483f-b59f-85b74211c11d` |
| `db.cosmosdb.operation_type` | `Read` |
-| `user_agent.original` | `cosmos-netstandard-sdk/3.31.2|1|X64|Linux 5.4.0-1095-azure 101 18|.NET 6.0.2|N|appname` |
+| `user_agent.original` | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` |
| `db.cosmosdb.connection_mode` | `"Direct"` |
| `db.cosmosdb.container` | `"container name"` |
| `db.cosmosdb.request_content_length` | `20` |
From 9352c2524ac03b31f4b845323b351d32ab3adb43 Mon Sep 17 00:00:00 2001
From: Tyler Yahn
Date: Wed, 29 Mar 2023 10:16:47 -0700
Subject: [PATCH 11/36] Fix units in the Kafka metric semantic conventions
(#3300)
Co-authored-by: Armin Ruech
---
.../metrics/semantic_conventions/instrumentation/kafka.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/specification/metrics/semantic_conventions/instrumentation/kafka.md b/specification/metrics/semantic_conventions/instrumentation/kafka.md
index b1114056094..db4b21ac322 100644
--- a/specification/metrics/semantic_conventions/instrumentation/kafka.md
+++ b/specification/metrics/semantic_conventions/instrumentation/kafka.md
@@ -25,13 +25,13 @@ This document defines how to apply semantic conventions when instrumenting Kafka
| 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` |
| messaging.kafka.requests.queue | UpDownCounter | Int64 | requests | `{request}` | The number of requests in the request queue. | | |
-| messaging.kafka.network.io | Counter | Int64 | bytes | `by` | The bytes received or sent by the broker. | `state` | `in`, `out` |
+| messaging.kafka.network.io | Counter | Int64 | bytes | `By` | The bytes received or sent by the broker. | `state` | `in`, `out` |
| messaging.kafka.purgatory.size | UpDownCounter | Int64 | requests | `{request}` | The number of requests waiting in the purgatory. | `type` | `produce`, `fetch` |
| messaging.kafka.partitions.all | UpDownCounter | Int64 | partitions | `{partition}` | The number of partitions in the broker. | | |
| messaging.kafka.partitions.offline | UpDownCounter | Int64 | partitions | `{partition}` | The number of offline partitions. | | |
| messaging.kafka.partitions.under-replicated | UpDownCounter | Int64 | partition | `{partition}` | The number of under replicated partitions. | | |
| messaging.kafka.isr.operations | Counter | Int64 | operations | `{operation}` | The number of in-sync replica shrink and expand operations. | `operation` | `shrink`, `expand` |
-| messaging.kafka.lag_max | Gauge | Int64 | lag max | `{lag max}` | Max lag in messages between follower and leader replicas. | | |
+| messaging.kafka.lag_max | Gauge | Int64 | lag max | `{message}` | Max lag in messages between follower and leader replicas. | | |
| messaging.kafka.controllers.active | UpDownCounter | Int64 | controllers | `{controller}` | The number of active controllers in the broker. | | |
| messaging.kafka.leader.elections | Counter | Int64 | elections | `{election}` | Leader election rate (increasing values indicates broker failures). | | |
| messaging.kafka.leader.unclean-elections | Counter | Int64 | elections | `{election}` | Unclean leader election rate (increasing values indicates broker failures). | | |
@@ -52,9 +52,9 @@ This document defines how to apply semantic conventions when instrumenting Kafka
| Name | Instrument | Value type | Unit | Unit ([UCUM](../README.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.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 |
-| messaging.kafka.producer.bytes.rate | Gauge | Double | bytes per second | `by/s` | The average number of bytes sent per second for a specific topic. | `client-id` | `client-id` value |
+| messaging.kafka.producer.bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of bytes sent per second for a specific topic. | `client-id` | `client-id` value |
| | | | | | | `topic` | topic name |
| messaging.kafka.producer.compression-ratio | Gauge | Double | compression ratio | `{compression}` | The average compression ratio of record batches for a specific topic. | `client-id` | `client-id` value |
| | | | | | | `topic` | topic name |
From d25734a47e6534a1bc8a52cb2bd51d42e987024b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20Neum=C3=BCller?=
Date: Thu, 30 Mar 2023 20:06:20 +0200
Subject: [PATCH 12/36] Clarify SDK ReadableSpan's parent Context (fix
accidentally requiring full parent chain) (#3257)
Resolves
https://github.com/open-telemetry/oteps/pull/182#discussion_r971857784
---
CHANGELOG.md | 4 ++++
specification/trace/api.md | 3 +++
specification/trace/sdk.md | 17 +++++++++++++----
3 files changed, 20 insertions(+), 4 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae4d3d93dd6..d245b19650c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,10 @@ release.
### Traces
+* Clarify required parent information in ReadableSpan. Technically a relaxation,
+ but previously it was easy to overlook certain properties were required.
+ [#3257](https://github.com/open-telemetry/opentelemetry-specification/pull/3257)
+
### Metrics
- Clarify that units should use UCUM case sensitive variant.
diff --git a/specification/trace/api.md b/specification/trace/api.md
index d27cbacc9f7..59a4b390a97 100644
--- a/specification/trace/api.md
+++ b/specification/trace/api.md
@@ -224,6 +224,9 @@ specification](https://www.w3.org/TR/trace-context/#tracestate-header). For
specific OTel values in `TraceState`, see the [TraceState Handling](tracestate-handling.md)
document.
+`IsRemote`, a boolean indicating whether the SpanContext was received from somewhere
+else or locally generated, see [IsRemote](#isremote).
+
The API MUST implement methods to create a `SpanContext`. These methods SHOULD be the only way to
create a `SpanContext`. This functionality MUST be fully implemented in the API, and SHOULD NOT be
overridable.
diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md
index 2e5b0dd46dc..ec69c39b8fd 100644
--- a/specification/trace/sdk.md
+++ b/specification/trace/sdk.md
@@ -120,14 +120,19 @@ Thus, the SDK specification defines sets of possible requirements for
* **Readable span**: A function receiving this as argument MUST be able to
access all information that was added to the span, as listed
- [in the API spec](api.md#span). In particular, it MUST also be
- able to access the `InstrumentationScope` [since 1.10.0] and `Resource`
- information (implicitly) associated with the span. For backwards compatibility
+ in the API spec for [Span](api.md#span). Note: Below, a few particular properties
+ are called out for clarity, but for the complete list of required properties,
+ the [Span API spec](api.md#span) is authoritative.
+
+ A function receiving this as argument MUST be able to access
+ the `InstrumentationScope` [since 1.10.0] and `Resource` information
+ (implicitly) associated with the span. For backwards compatibility
it MUST also be able to access the `InstrumentationLibrary`
[deprecated since 1.10.0] having the same name and version values as the
`InstrumentationScope`.
- It must also be able to reliably determine whether the Span has ended
+ A function receiving this as argument MUST must be able to reliably determine
+ whether the Span has ended
(some languages might implement this by having an end timestamp of `null`,
others might have an explicit `hasEnded` boolean).
@@ -135,6 +140,10 @@ Thus, the SDK specification defines sets of possible requirements for
available for exporters to report as described in the [exporters](../common/mapping-to-non-otlp.md#dropped-attributes-count)
specification.
+ As an exception to the authoritative set of span properties defined in the API spec,
+ implementations MAY choose not to expose (and store) the full parent [Context](../context/README.md)
+ of the Span but they MUST expose at least the full parent [SpanContext](api.md#spancontext).
+
A function receiving this as argument might not be able to modify the Span.
Note: Typically this will be implemented with a new interface or
From 713ae0d9b21eee623a20d6082b1115be080da842 Mon Sep 17 00:00:00 2001
From: Josh Suereth
Date: Mon, 3 Apr 2023 12:28:07 -0400
Subject: [PATCH 13/36] Provide clear guidance on what semconv actually
enforces (#3225)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Fixes #2864
Fixes #2883
## Changes
- Explicitly define what is "enforced" by stability guarantees from
Semantic conventions.
- We enforce attribute key names + types, across resource, span, metric
and log
- We enforce span names
- We enforce metric names, units
- Expand allowed changes to semconv to include metric attributes that do
not increase timeseries count for a given metric.
## Context
Sig discussion thread/doc
[here](https://docs.google.com/document/d/1Nvcf1wio7nDUVcrXxVUN_f8MNmcs0OzVAZLvlth1lYY/edit?usp=sharing).
---------
Co-authored-by: Trask Stalnaker
Co-authored-by: Johannes Tax
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
Co-authored-by: Patrice Chalin
Co-authored-by: Sergey Kanzhelev
Co-authored-by: Carlos Alberto Cortez
Co-authored-by: Tyler Benson
Co-authored-by: Joshua Carpeggiani <32605850+joshcarp@users.noreply.github.com>
Co-authored-by: Armin Ruech
Co-authored-by: Yuri Shkuro
Co-authored-by: Asaf Mesika
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com>
Co-authored-by: Antoine Toulme
Co-authored-by: Christian Neumüller
Co-authored-by: Liudmila Molkova
Co-authored-by: Reiley Yang
Co-authored-by: Joshua MacDonald
---
CHANGELOG.md | 2 +
specification/versioning-and-stability.md | 71 ++++++++++++++++++++++-
2 files changed, 71 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d245b19650c..f4a63defd60 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,8 @@ release.
[#3348](https://github.com/open-telemetry/opentelemetry-specification/pull/3348))
- Define attributes collected for `cosmosdb` by Cosmos DB SDK
([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
+- Clarify stability requirements of semantic conventions
+ ([#3225](https://github.com/open-telemetry/opentelemetry-specification/pull/3225))
### Compatibility
diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md
index 15115529750..586aee693f3 100644
--- a/specification/versioning-and-stability.md
+++ b/specification/versioning-and-stability.md
@@ -155,12 +155,78 @@ A new, incompatible version of an integration SHOULD be released as a separate c
#### Semantic Conventions Stability
+Semantic conventions define a contract between the signals that instrumentation
+will provide and analysis tools that consumes the instrumentation (e.g.
+dashboards, alerts, queries, etc.).
+
Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid
breaking analysis tools, such as dashboards and alerts. To achieve this, while
allowing the evolution of telemetry and semantic conventions, OpenTelemetry
relies on the concept of
[Telemetry Schemas](schemas/README.md).
+Semantic Conventions defines breaking changes as those that would break the
+common usage of tooling written against the telemetry it produces. That is, the
+portions of telemetry where specialized tooling (alerts, dashboards, e.g.)
+interact are expected to remain stable for that tooling *after schema
+transformations are applied*. These also assume no user interventions in the
+default configuration, e.g. Samplers, Views, etc.
+
+Semantic Conventions defines the set of fields in the OTLP data model:
+
+- [Resource](resource/sdk.md)
+ - attribute keys. (The key section of attributes key value pairs)
+- InstrumentationScope
+ - Attribute keys
+ - provided to [get a tracer](trace/api.md#get-a-tracer)
+ - provided to [get a meter](metrics/api.md#get-a-meter)
+- [Trace](trace/api.md)
+ - The following data on [span](trace/api.md#span):
+ - The span name
+ - The span kind
+ - The attribute keys provided to the span
+ - Whether these attributes must be provided at span start time, due to
+ sampling concerns.
+ - The following data provided on [span events](trace/api.md#add-events)
+ - The event name
+ - The attribute keys provided for the event
+- [Metrics](metrics/api.md)
+ - The following portions of a Metric
+ (passed when constructing [an instrument](metrics/api.md#instrument)):
+ - The name of the metric (defaults to instrument name).
+ - The kind of metric data (Gauge, Sum, Histogram, ExponentialHistogram)
+ - For `Counter` and `UpDownCounter` instruments, it is
+ acceptable to change between asynchronous and synchronous instruments,
+ as this preserves the metric kind.
+ - The unit of the metric (defaults to instrument unit).
+ - The attribute keys on any `*DataPoint`.
+ - These are provided in the API when recording a measurement, for
+ both synchronous and asynchronous instruments.
+ - These exist on `NumberDataPoint`, `HistogramDataPoint`,
+ `ExponentialHistogramDataPoint` and `SummaryDataPoint`.
+- [Log Records](logs/bridge-api.md#logrecord)
+ - The attribute keys provided on the LogRecord
+ - For log records that are [Log Events](logs/event-api.md)
+ - The following data provided to [emit event](logs/event-api.md#emit-event):
+ - The event name (the value of the `event.name` attribute)
+ - The event domain (the value of the `event.domain` attribute)
+
+Things not listed in the above are not expected to remain stable via semantic
+convention and are allowed (or expected) to change. A few examples:
+
+- The values of attributes
+ - Specifically for `enums` the list of allowed values is expected to change
+ overtime.
+ - Even for `enums` that limit allowed values to semconv, some may need to
+ updated values in the future. Tooling should expect unknown values.
+- The links attached to a span
+- The recorded measurement type (float or integer) of a metric is not enforced and allowed to change.
+- The description of a metric instrument.
+- The values being recorded by an instrument.
+
+The list of telemetry fields which are covered by stability guarantees MAY be
+extended.
+
Changes to semantic conventions in this specification are allowed, provided that
the changes can be described by schema files. The following changes can be
currently described and are allowed:
@@ -181,8 +247,9 @@ that are always allowed. Such changes do not need to be described (and are not
described) by schema files. Here is the list of such changes:
- Adding new attributes to the existing semantic conventions for resources,
- spans, span events or log records. Note that adding attributes to existing metrics is
- considered to be a breaking change.
+ spans, span events or log records.
+- Adding new attributes to existing metrics that do not "break apart" existing
+ timeseries, such that alert thresholds would break / need to change.
- Adding semantic conventions for new types of resources, spans, span events,
metrics or log records.
From f5a269fd3de948656c085c25d83342c78c8dc99c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Paj=C4=85k?=
Date: Mon, 3 Apr 2023 19:27:56 +0200
Subject: [PATCH 14/36] BREAKING: Change span statuses for gRPC server spans
(#3333)
Fixes https://github.com/open-telemetry/opentelemetry-specification/issues/3110
## Changes
The idea behind the PR is to make the spam statuses gRPC convention
similar to HTTP semantic conventions.
The gRPC statuses -> HTTP status codes mapping is not anywhere strictly
defined.
However, there is are some approximations which can be found:
-
https://github.com/grpc/grpc/commit/bb04e070b3177d7bd8e69c4086dc420f662b8f28#diff-c94ff143c8f378e6925a985fa18528a8254a6d7fc34bc855e1de13f1e7f3e464
-
https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
I got confused if we should treat `INTERNAL` as `Error` for
`SpanKind.SERVER` because of:
-
https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md
-
https://github.com/grpc/grpc-go/blob/a02aae6168aa683a1f106e285ec10eb6bc1f6ded/internal/transport/handler_server.go#L90C8-L92
-
https://github.com/grpc/grpc-go/blob/a02aae6168aa683a1f106e285ec10eb6bc1f6ded/internal/transport/http_util.go#L73
On the other hand, [the
description](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md)
of `INTERNAL` says:
> Internal errors. This means that some invariants expected by the
underlying system have been broken. This error code is reserved for
serious errors.
Therefore, I decided to leave it as `Error`. Also because this is
backwards compatible (at least for this gRPC status).
---------
Co-authored-by: Tyler Yahn
---
CHANGELOG.md | 2 ++
.../trace/semantic_conventions/rpc.md | 26 ++++++++++++++++++-
2 files changed, 27 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4a63defd60..09c20979e87 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,6 +56,8 @@ release.
([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
- Clarify stability requirements of semantic conventions
([#3225](https://github.com/open-telemetry/opentelemetry-specification/pull/3225))
+- BREAKING: Change span statuses for gRPC server spans.
+ ([#3333](https://github.com/open-telemetry/opentelemetry-specification/pull/3333))
### Compatibility
diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md
index f5d6e823457..b70a97fa77b 100644
--- a/specification/trace/semantic_conventions/rpc.md
+++ b/specification/trace/semantic_conventions/rpc.md
@@ -206,7 +206,31 @@ For remote procedure calls via [gRPC][], additional conventions are described in
### gRPC Status
-The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC status code, and set to `Error` for all others.
+The table below describes when
+the [Span Status](../api.md#set-status) MUST be set
+to `Error` or remain unset
+depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md)
+and [Span Kind](../api.md#spankind).
+
+| gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status |
+|---|---|---|
+| OK | unset | unset |
+| CANCELLED | unset | `Error` |
+| UNKNOWN | `Error` | `Error` |
+| INVALID_ARGUMENT | unset | `Error` |
+| DEADLINE_EXCEEDED | `Error` | `Error` |
+| NOT_FOUND | unset | `Error` |
+| ALREADY_EXISTS | unset | `Error` |
+| PERMISSION_DENIED | unset | `Error` |
+| RESOURCE_EXHAUSTED | unset| `Error` |
+| FAILED_PRECONDITION | unset | `Error` |
+| ABORTED | unset | `Error` |
+| OUT_OF_RANGE | unset | `Error` |
+| UNIMPLEMENTED | `Error` | `Error` |
+| INTERNAL | `Error` | `Error` |
+| UNAVAILABLE | `Error` | `Error` |
+| DATA_LOSS | `Error` | `Error` |
+| UNAUTHENTICATED | unset | `Error` |
### gRPC Request and Response Metadata
From 12fcec1ff255b1535db75708e52a3a21f86f0fae Mon Sep 17 00:00:00 2001
From: Josh Suereth
Date: Mon, 3 Apr 2023 22:40:12 -0400
Subject: [PATCH 15/36] Mark `service` and `telemetry.sdk` resource attributes
as stable. (#3202)
## Changes
This PR marks the set of resource semantic conventions, which a relied
upon in stable API / SDK specification, as stable themselves.
- Add a caveat that changing `service.*` and `telemetry.*` names need
MORE than just schema file changes.
- Mark core Resource attribute semconv document as MIXED stability
- Update key sections for Resource attribute semconv as stable
- Mark `telemetry.sdk` and `service` attribute groups as stable.
- Move `telemetry.auto` and `service.*` "contentious" attributes into
`{section}_experimental.yaml` file. This retains the reserved name, but
does not mark the convention as stable, allowing us to ensure stable
portions of our specification refer to stable semconv.
- Update examples for `service.instance.id` to include an example of the
preferred style instance id before the fallback.
Related issues #3177
## Usage in the Specification
One reason we should mark these attributes as stable is because they are
referenced from numerous stable portions of our specification, and they
are also leveraged from newly stabilizing portions of our specification.
- [Resource
SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#sdk-provided-resource-attributes)
- stable
- [Environment
Variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#general-sdk-configuration)
- stable
- [Jaeger
Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/jaeger.md#resource)
- stable
- [Zipkin
Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md#service-name)
- Stable
- [Log
DataModel](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#rfc5424-syslog)
- Stable
- [Prometheus
compatibility](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md#resource-attributes)
- still experimental
- [Performance Benchmark
Guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/performance-benchmark.md)
## A note on ECS compatibility
Here's [ECS service
definition](https://www.elastic.co/guide/en/ecs/current/ecs-service.html).
They include more attributes than we do. The only possible conflict
between us is `service.instance.id` vs. `service.node.name`. In this
case, our `service.instance.id` has a fallback of generating UUID which
is inconsistent w/ `service.node.name` which requires a user-generated
name if another name cannot be provided.
There's an opportunity for us to unify here. However, I don't think
there's appetite in OTEL to require user-specified names in lieu of some
algorithm or generative specification.
---
CHANGELOG.md | 3 +
semantic_conventions/resource/service.yaml | 35 ---------
.../resource/service_experimental.yaml | 42 +++++++++++
semantic_conventions/resource/telemetry.yaml | 8 +--
.../resource/telemetry_experimental.yaml | 12 ++++
.../resource/semantic_conventions/README.md | 72 +++++++++++++++----
specification/versioning-and-stability.md | 6 ++
7 files changed, 126 insertions(+), 52 deletions(-)
create mode 100644 semantic_conventions/resource/service_experimental.yaml
create mode 100644 semantic_conventions/resource/telemetry_experimental.yaml
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 09c20979e87..f34a2ed1de2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -58,6 +58,9 @@ release.
([#3225](https://github.com/open-telemetry/opentelemetry-specification/pull/3225))
- BREAKING: Change span statuses for gRPC server spans.
([#3333](https://github.com/open-telemetry/opentelemetry-specification/pull/3333))
+- Stabilize key components of `service.*` and `telemetry.sdk.*` resource
+ semantic conventions.
+ ([#3202](https://github.com/open-telemetry/opentelemetry-specification/pull/3202))
### Compatibility
diff --git a/semantic_conventions/resource/service.yaml b/semantic_conventions/resource/service.yaml
index 9c60099f463..3765345bac1 100644
--- a/semantic_conventions/resource/service.yaml
+++ b/semantic_conventions/resource/service.yaml
@@ -16,38 +16,3 @@ groups:
with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`.
If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
examples: ["shoppingcart"]
- - id: namespace
- type: string
- brief: >
- A namespace for `service.name`.
- note: >
- A string value having a meaning that helps to distinguish a group of services,
- for example the team name that owns a group of services.
- `service.name` is expected to be unique within the same namespace.
- If `service.namespace` is not specified in the Resource then `service.name`
- is expected to be unique for all services that have no explicit namespace defined
- (so the empty/unspecified namespace is simply one more valid namespace).
- Zero-length namespace string is assumed equal to unspecified namespace.
- examples: ["Shop"]
- - id: instance.id
- type: string
- brief: >
- The string ID of the service instance.
- note: >
- MUST be unique for each instance of the same `service.namespace,service.name` pair
- (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique).
- The ID helps to distinguish instances of the same service that exist at the same time
- (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent
- and stay the same for the lifetime of the service instance, however it is acceptable that
- the ID is ephemeral and changes during important lifetime events for the service
- (e.g. service restarts).
- If the service has no inherent unique ID that can be used as the value of this attribute
- it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID
- (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122
- for more recommendations).
- examples: ["627cc493-f310-47de-96bd-71410b7dec09"]
- - id: version
- type: string
- brief: >
- The version string of the service API or implementation.
- examples: ["2.0.0"]
diff --git a/semantic_conventions/resource/service_experimental.yaml b/semantic_conventions/resource/service_experimental.yaml
new file mode 100644
index 00000000000..4ad790d16ab
--- /dev/null
+++ b/semantic_conventions/resource/service_experimental.yaml
@@ -0,0 +1,42 @@
+groups:
+ - id: service_experimental
+ prefix: service
+ type: resource
+ brief: >
+ A service instance.
+ attributes:
+ - id: namespace
+ type: string
+ brief: >
+ A namespace for `service.name`.
+ note: >
+ A string value having a meaning that helps to distinguish a group of services,
+ for example the team name that owns a group of services.
+ `service.name` is expected to be unique within the same namespace.
+ If `service.namespace` is not specified in the Resource then `service.name`
+ is expected to be unique for all services that have no explicit namespace defined
+ (so the empty/unspecified namespace is simply one more valid namespace).
+ Zero-length namespace string is assumed equal to unspecified namespace.
+ examples: ["Shop"]
+ - id: instance.id
+ type: string
+ brief: >
+ The string ID of the service instance.
+ note: >
+ MUST be unique for each instance of the same `service.namespace,service.name` pair
+ (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique).
+ The ID helps to distinguish instances of the same service that exist at the same time
+ (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent
+ and stay the same for the lifetime of the service instance, however it is acceptable that
+ the ID is ephemeral and changes during important lifetime events for the service
+ (e.g. service restarts).
+ If the service has no inherent unique ID that can be used as the value of this attribute
+ it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID
+ (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122
+ for more recommendations).
+ examples: ["my-k8s-pod-deployment-1", "627cc493-f310-47de-96bd-71410b7dec09"]
+ - id: version
+ type: string
+ brief: >
+ The version string of the service API or implementation.
+ examples: ["2.0.0"]
diff --git a/semantic_conventions/resource/telemetry.yaml b/semantic_conventions/resource/telemetry.yaml
index fc80b853895..979566f8414 100644
--- a/semantic_conventions/resource/telemetry.yaml
+++ b/semantic_conventions/resource/telemetry.yaml
@@ -7,6 +7,7 @@ groups:
attributes:
- id: sdk.name
type: string
+ requirement_level: required
brief: >
The name of the telemetry SDK as defined above.
examples: ["opentelemetry"]
@@ -36,15 +37,12 @@ groups:
value: "webjs"
- id: swift
value: "swift"
+ requirement_level: required
brief: >
The language of the telemetry SDK.
- id: sdk.version
type: string
+ requirement_level: required
brief: >
The version string of the telemetry SDK.
examples: ["1.2.3"]
- - id: auto.version
- type: string
- brief: >
- The version string of the auto instrumentation agent, if used.
- examples: ["1.2.3"]
diff --git a/semantic_conventions/resource/telemetry_experimental.yaml b/semantic_conventions/resource/telemetry_experimental.yaml
new file mode 100644
index 00000000000..63137055173
--- /dev/null
+++ b/semantic_conventions/resource/telemetry_experimental.yaml
@@ -0,0 +1,12 @@
+groups:
+ - id: telemetry_experimental
+ prefix: telemetry
+ type: resource
+ brief: >
+ The telemetry SDK used to capture data recorded by the instrumentation libraries.
+ attributes:
+ - id: auto.version
+ type: string
+ brief: >
+ The version string of the auto instrumentation agent, if used.
+ examples: ["1.2.3"]
diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md
index b025f789fe6..ee9eacc597a 100644
--- a/specification/resource/semantic_conventions/README.md
+++ b/specification/resource/semantic_conventions/README.md
@@ -1,6 +1,6 @@
# Resource Semantic Conventions
-**Status**: [Experimental](../../document-status.md)
+**Status**: [Mixed](../../document-status.md)
This document defines standard attributes for resources. These attributes are typically used in the [Resource](../sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
[OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md).
@@ -15,7 +15,9 @@ This document defines standard attributes for resources. These attributes are ty
* [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable)
- [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value)
- [Service](#service)
+- [Service (Experimental)](#service-experimental)
- [Telemetry SDK](#telemetry-sdk)
+- [Telemetry SDK (Experimental)](#telemetry-sdk-experimental)
- [Compute Unit](#compute-unit)
- [Compute Instance](#compute-instance)
- [Environment](#environment)
@@ -34,12 +36,17 @@ This document defines standard attributes for resources. These attributes are ty
## Document Conventions
+**Status**: [Stable](../../document-status.md)
+
Attributes are grouped logically by the type of the concept that they described. Attributes in the same group have a common prefix that ends with a dot. For example all attributes that describe Kubernetes properties start with "k8s."
-Certain attribute groups in this document have a **Required** column. For these groups if any attribute from the particular group is present in the Resource then all attributes that are marked as Required MUST be also present in the Resource. However it is also valid if the entire attribute group is omitted (i.e. none of the attributes from the particular group are present even though some of them are marked as Required in this document).
+See [Attribute Requirement Levels](../../common/attribute-requirement-level.md) for details on when attributes
+should be included.
## Attributes with Special Handling
+**Status**: [Stable](../../document-status.md)
+
Given their significance some resource attributes are treated specifically as described below.
### Semantic Attributes with Dedicated Environment Variable
@@ -55,9 +62,12 @@ These are the attributes which MUST be provided by the SDK
as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource-attributes):
- [`service.name`](#service)
+- [`telemetry.sdk` group](#telemetry-sdk)
## Service
+**Status**: [Stable](../../document-status.md)
+
**type:** `service`
**Description:** A service instance.
@@ -66,15 +76,28 @@ as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Required |
-| `service.namespace` | string | A namespace for `service.name`. [2] | `Shop` | Recommended |
-| `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | Recommended |
-| `service.version` | string | The version string of the service API or implementation. | `2.0.0` | Recommended |
**[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
+
+
+## Service (Experimental)
-**[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
+**Status**: [Experimental](../../document-status.md)
+
+**type:** `service`
-**[3]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent and stay the same for the lifetime of the service instance, however it is acceptable that the ID is ephemeral and changes during important lifetime events for the service (e.g. service restarts). If the service has no inherent unique ID that can be used as the value of this attribute it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 for more recommendations).
+**Description:** Additions to service instance.
+
+
+| Attribute | Type | Description | Examples | Requirement Level |
+|---|---|---|---|---|
+| `service.namespace` | string | A namespace for `service.name`. [1] | `Shop` | Recommended |
+| `service.instance.id` | string | The string ID of the service instance. [2] | `my-k8s-pod-deployment-1`; `627cc493-f310-47de-96bd-71410b7dec09` | Recommended |
+| `service.version` | string | The version string of the service API or implementation. | `2.0.0` | Recommended |
+
+**[1]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
+
+**[2]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent and stay the same for the lifetime of the service instance, however it is acceptable that the ID is ephemeral and changes during important lifetime events for the service (e.g. service restarts). If the service has no inherent unique ID that can be used as the value of this attribute it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 for more recommendations).
Note: `service.namespace` and `service.name` are not intended to be concatenated for the purpose of forming a single globally unique name for the service. For example the following 2 sets of attributes actually describe 2 different services (despite the fact that the concatenation would result in the same string):
@@ -93,6 +116,8 @@ service.name = Shop.shoppingcart
## Telemetry SDK
+**Status**: [Stable](../../document-status.md)
+
**type:** `telemetry.sdk`
**Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries.
@@ -104,15 +129,14 @@ If another SDK, like a fork or a vendor-provided implementation, is used, this S
`telemetry.sdk.name` to the fully-qualified class or module name of this SDK's main entry point
or another suitable identifier depending on the language.
The identifier `opentelemetry` is reserved and MUST NOT be used in this case.
-The identifier SHOULD be stable across different versions of an implementation.
+All custom identifiers SHOULD be stable across different versions of an implementation.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
-| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. | `opentelemetry` | Recommended |
-| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Recommended |
-| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Recommended |
-| `telemetry.auto.version` | string | The version string of the auto instrumentation agent, if used. | `1.2.3` | Recommended |
+| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. | `opentelemetry` | Required |
+| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Required |
+| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Required |
`telemetry.sdk.language` 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.
@@ -131,8 +155,24 @@ The identifier SHOULD be stable across different versions of an implementation.
| `swift` | swift |
+## Telemetry SDK (Experimental)
+
+**Status**: [Experimental](../../document-status.md)
+
+**type:** `telemetry.sdk`
+
+**Description:** Additions to the telemetry SDK.
+
+
+| Attribute | Type | Description | Examples | Requirement Level |
+|---|---|---|---|---|
+| `telemetry.auto.version` | string | The version string of the auto instrumentation agent, if used. | `1.2.3` | Recommended |
+
+
## Compute Unit
+**Status**: [Experimental](../../document-status.md)
+
Attributes defining a compute unit (e.g. Container, Process, Function as a Service):
- [Container](./container.md)
@@ -142,12 +182,16 @@ Attributes defining a compute unit (e.g. Container, Process, Function as a Servi
## Compute Instance
+**Status**: [Experimental](../../document-status.md)
+
Attributes defining a computing instance (e.g. host):
- [Host](./host.md)
## Environment
+**Status**: [Experimental](../../document-status.md)
+
Attributes defining a running environment (e.g. Operating System, Cloud, Data Center, Deployment Service):
- [Operating System](./os.md)
@@ -160,12 +204,16 @@ Attributes defining a running environment (e.g. Operating System, Cloud, Data Ce
## Version attributes
+**Status**: [Stable](../../document-status.md)
+
Version attributes, such as `service.version`, are values of type `string`. They are
the exact version used to identify an artifact. This may be a semantic version, e.g., `1.2.3`, git hash, e.g.,
`8ae73a`, or an arbitrary version string, e.g., `0.1.2.20210101`, whatever was used when building the artifact.
## Cloud-Provider-Specific Attributes
+**Status**: [Experimental](../../document-status.md)
+
Attributes that are only applicable to resources from a specific cloud provider. Currently, these
resources can only be defined for providers listed as a valid `cloud.provider` in
[Cloud](./cloud.md) and below. Provider-specific attributes all reside in the `cloud_provider` directory.
diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md
index 586aee693f3..a0a5b8da7b1 100644
--- a/specification/versioning-and-stability.md
+++ b/specification/versioning-and-stability.md
@@ -242,6 +242,12 @@ For details see [how OpenTelemetry Schemas are published](schemas/README.md#open
See the [Telemetry Stability](telemetry-stability.md) document for details on how
instrumentations can use schemas to change the instrumentation they produce.
+**Exception:** Some resource attributes are embedded in various locations of the
+Specification, e.g. the `service.*` attributes which are required by SDKs to be
+produced and have corresponding [environment variables defined in general SDK configuration](sdk-environment-variables.md#general-sdk-configuration). These resource
+attributes MUST NOT be ever changed. They are considered a hard-coded part of
+this specification.
+
In addition to the 3 types of changes described above there are certain types
that are always allowed. Such changes do not need to be described (and are not
described) by schema files. Here is the list of such changes:
From 6ba4a82d9415f3a278f77e3c2519ef574b6302a7 Mon Sep 17 00:00:00 2001
From: Tyler Yahn
Date: Mon, 3 Apr 2023 20:23:42 -0700
Subject: [PATCH 16/36] Remove No-Op instrument and Meter creation restrictions
(#3322)
The current No-Op requires all instruments to be created from a Meter
and a Meter to be created from a MeterProvider. This was inherited from
the SDK specification, but it is not necessary. The No-Op performs no
operations and hold no state, therefore creating these objects directly
should not have logical or processing consequences. If there are
consequences of doing this in a language implementation, they are still
permitted to keep this restriction.
This change is desired by the Go SIG. We want to export these No-Op
types so users can create them directly. This will allow them to embed
these No-Op types in their SDKs to define default behaviour, and allow
them to use them directly for testing (instead of having to go through
the creation chain all starting with a MeterProvider).
---------
Co-authored-by: Reiley Yang
Co-authored-by: Joshua MacDonald
---
CHANGELOG.md | 2 ++
specification/metrics/noop.md | 24 ------------------------
2 files changed, 2 insertions(+), 24 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f34a2ed1de2..7c8fda8ee12 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,8 @@ release.
- Clarify that units should use UCUM case sensitive variant.
([#3306](https://github.com/open-telemetry/opentelemetry-specification/pull/3306))
+- Remove No-Op instrument and Meter creation requirements.
+ ([#3322](https://github.com/open-telemetry/opentelemetry-specification/pull/3322))
- Fixed attributes requirement level in semantic conventions for hardware metrics
([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
diff --git a/specification/metrics/noop.md b/specification/metrics/noop.md
index 94e72b70325..7400c978676 100644
--- a/specification/metrics/noop.md
+++ b/specification/metrics/noop.md
@@ -82,9 +82,6 @@ any argument it receives.
## Meter
-A Meter is always created by a MeterProvider. The No-Op MUST NOT provide
-a way for a user to create a Meter other than by a No-Op MeterProvider.
-
The Meters created by the No-Op need to hold as small a memory
footprint as possible. Therefore, all Meters created MUST NOT hold
configuration or operational state.
@@ -190,9 +187,6 @@ telemetry.
### Counter
-Counters are always created by a Meter, the No-Op MUST NOT provide a way
-for a user to create a Counter other than by a No-Op Meter.
-
Counters MUST NOT return a non-empty error or log any message for any
operations they perform.
@@ -206,9 +200,6 @@ state about the arguments it receives.
### UpDownCounter
-UpDownCounters are always created by a Meter, the No-Op MUST NOT provide
-a way for a user to create a UpDownCounter other than by a No-Op Meter.
-
UpDownCounters MUST NOT return a non-empty error or log any message for
any operations they perform.
@@ -223,9 +214,6 @@ state about the arguments it receives.
### Histogram
-Histograms are always created by a Meter, the No-Op MUST NOT provide a
-way for a user to create a Histogram other than by a No-Op Meter.
-
Histograms MUST NOT return a non-empty error or log any message for any
operations they perform.
@@ -239,10 +227,6 @@ any state about the arguments it receives.
### Asynchronous Counter
-Asynchronous Counters are always created by a Meter, the No-Op MUST NOT
-provide a way for a user to create a Asynchronous Counter other than by
-a No-Op Meter.
-
Asynchronous Counters MUST NOT return a non-empty error or log any
message for any operations they perform.
@@ -256,10 +240,6 @@ about observations made for the instrument.
### Asynchronous UpDownCounter
-Asynchronous UpDownCounters are always created by a Meter, the No-Op
-MUST NOT provide a way for a user to create a Asynchronous UpDownCounter
-other than by a No-Op Meter.
-
Asynchronous UpDownCounters MUST NOT return a non-empty error or log any
message for any operations they perform.
@@ -273,10 +253,6 @@ state about observations made for the instrument.
### Asynchronous Gauge
-Asynchronous Gauges are always created by a Meter, the No-Op MUST NOT
-provide a way for a user to create a Asynchronous Gauge other than by a
-No-Op Meter.
-
Asynchronous Gauges MUST NOT return a non-empty error or log any message
for any operations they perform.
From 02d378a0586296b98daec2babcc6d57847c670ba Mon Sep 17 00:00:00 2001
From: Brett McBride
Date: Wed, 5 Apr 2023 02:43:44 +1000
Subject: [PATCH 17/36] Add php logs compliance (#3340)
Adds php logs compliance items, as well as two missing env vars from the
matrix.
---------
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
---
spec-compliance-matrix.md | 27 ++++++++++++++-------------
1 file changed, 14 insertions(+), 13 deletions(-)
diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
index 62c83eb481d..836bad53ca4 100644
--- a/spec-compliance-matrix.md
+++ b/spec-compliance-matrix.md
@@ -215,20 +215,19 @@ Disclaimer: this list of features is still a work in progress, please refer to t
| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
|----------------------------------------------|----------|-----|------|-----|--------|------|--------|-----|------|-----|------|-------|
| **[Logging SDK](specification/logs/sdk.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
-| LoggerProvider.Get Logger | | | + | | | | | | | | - | |
-| LoggerProvider.Get Logger accepts attributes | | | | | | | | | | | | |
-| LoggerProvider.Shutdown | | | + | | | | | | | | - | |
-| LoggerProvider.ForceFlush | | | + | | | | | | | | - | |
-| Logger.Emit(LogRecord) | | | + | | | | | | | | - | |
-| SimpleLogRecordProcessor | | | + | | | | | | | | | |
-| BatchLogRecordProcessor | | | + | | | | | | | | | |
-| Can plug custom LogRecordProcessor | | | + | | | | | | | | | |
-| OTLP/gRPC exporter | | | + | | + | | | | | | + | |
-| OTLP/HTTP exporter | | | + | | + | | | | | | + | |
+| LoggerProvider.Get Logger | | | + | | | | | + | | | - | |
+| LoggerProvider.Get Logger accepts attributes | | | | | | | | + | | | | |
+| LoggerProvider.Shutdown | | | + | | | | | + | | | - | |
+| LoggerProvider.ForceFlush | | | + | | | | | + | | | - | |
+| Logger.Emit(LogRecord) | | | + | | | | | + | | | - | |
+| SimpleLogRecordProcessor | | | + | | | | | + | | | | |
+| BatchLogRecordProcessor | | | + | | | | | + | | | | |
+| Can plug custom LogRecordProcessor | | | + | | | | | + | | | | |
+| OTLP/gRPC exporter | | | + | | + | | | + | | | + | |
+| OTLP/HTTP exporter | | | + | | + | | | + | | | + | |
| OTLP File exporter | | | - | | - | | | | | | - | |
-| Can plug custom LogRecordExporter | | | + | | | | | | | | | |
-| Implicit Context Injection | | | - | | + | | | | | | + | |
-| Explicit Context | | | + | | - | | | | | | - | |
+| Can plug custom LogRecordExporter | | | + | | | | | + | | | | |
+| Trace Context Injection | | | + | | + | | | + | | | + | |
## Resource
@@ -288,6 +287,8 @@ Note: Support for environment variables is optional.
| OTEL_SPAN_LINK_COUNT_LIMIT | + | + | + | + | + | + | + | + | - | - | |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | + | - | | + | + | + | + | | | - | |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | + | - | | + | + | + | + | | | - | |
+| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | | | | | | | + | | | | |
+| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | | | | | | | + | | | | |
| OTEL_TRACES_SAMPLER | + | + | + | + | + | + | + | - | - | - | |
| OTEL_TRACES_SAMPLER_ARG | + | + | + | + | + | + | + | - | - | - | |
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | + | + | + | + | + | - | + | | | - | |
From f07efeaef87807611b2b81fcafc7214d0731a398 Mon Sep 17 00:00:00 2001
From: David Phillips
Date: Wed, 5 Apr 2023 12:07:06 -0700
Subject: [PATCH 18/36] Add Trino to db.system semantic conventions (#3347)
---
CHANGELOG.md | 2 ++
semantic_conventions/trace/database.yaml | 3 +++
specification/trace/semantic_conventions/database.md | 1 +
3 files changed, 6 insertions(+)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7c8fda8ee12..fd46eb80347 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -63,6 +63,8 @@ release.
- Stabilize key components of `service.*` and `telemetry.sdk.*` resource
semantic conventions.
([#3202](https://github.com/open-telemetry/opentelemetry-specification/pull/3202))
+- Add Trino to Database specific conventions
+ ([#3347](https://github.com/open-telemetry/opentelemetry-specification/pull/3347))
### Compatibility
diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml
index af9ed4c3cb1..e89f5eadf3c 100644
--- a/semantic_conventions/trace/database.yaml
+++ b/semantic_conventions/trace/database.yaml
@@ -166,6 +166,9 @@ groups:
- id: spanner
value: 'spanner'
brief: 'Cloud Spanner'
+ - id: trino
+ value: 'trino'
+ brief: 'Trino'
- id: connection_string
tag: connection-level
type: string
diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md
index b3da889e4be..22705196e3e 100644
--- a/specification/trace/semantic_conventions/database.md
+++ b/specification/trace/semantic_conventions/database.md
@@ -121,6 +121,7 @@ Some database systems may allow a connection to switch to a different `db.user`,
| `opensearch` | OpenSearch |
| `clickhouse` | ClickHouse |
| `spanner` | Cloud Spanner |
+| `trino` | Trino |
### Notes and well-known identifiers for `db.system`
From 8e6bea5d9e7e290021d2530590ba690f958f0788 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Thu, 6 Apr 2023 08:55:01 -0500
Subject: [PATCH 19/36] Add Log Bridge API artifact naming guidance (#3346)
Resolves #3301.
---------
Co-authored-by: Armin Ruech
---
CHANGELOG.md | 2 ++
specification/logs/bridge-api.md | 10 ++++++++++
2 files changed, 12 insertions(+)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fd46eb80347..57557e3daa4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,8 @@ release.
([#3331](https://github.com/open-telemetry/opentelemetry-specification/pull/3331))
- Ensure Logs Bridge API doesn't contain SDK implementation details
([#3275](https://github.com/open-telemetry/opentelemetry-specification/pull/3275))
+- Add Log Bridge API artifact naming guidance
+ ([#3346](https://github.com/open-telemetry/opentelemetry-specification/pull/3346))
- Add log appender / bridge to glossary.
([#3335](https://github.com/open-telemetry/opentelemetry-specification/pull/3335))
diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md
index a72fa0cf8f9..25c3a210e07 100644
--- a/specification/logs/bridge-api.md
+++ b/specification/logs/bridge-api.md
@@ -18,6 +18,7 @@
- [LogRecord](#logrecord)
- [Optional and required parameters](#optional-and-required-parameters)
- [Concurrency requirements](#concurrency-requirements)
+- [Artifact Naming](#artifact-naming)
- [Usage](#usage)
* [How to Create a Log4J Log Appender](#how-to-create-a-log4j-log-appender)
* [Implicit Context Injection](#implicit-context-injection)
@@ -158,6 +159,15 @@ specific guarantees and safeties.
**Logger** - all methods are safe to be called concurrently.
+## Artifact Naming
+
+The Logs Bridge API is not intended to be called by application developers
+directly, and SHOULD include documentation that discourages direct use. However,
+in the event OpenTelemetry were to add a user facing API, the Logs Bridge API would
+be a natural starting point. Therefore, Log Bridge API artifact, package, and class
+names MUST NOT include the terms "bridge", "appender", or any other qualifier
+that would prevent evolution into a user facing API.
+
## Usage
### How to Create a Log4J Log Appender
From 2604c7808a1e710686b13f07bc29ddb3ad4027a5 Mon Sep 17 00:00:00 2001
From: Trask Stalnaker
Date: Thu, 6 Apr 2023 07:05:07 -0700
Subject: [PATCH 20/36] Add warning about net.* attributes which are used by
HTTP semconv (#3278)
Fixes #3260
(a first try at least)
## Changes
Splits `net.*` attributes into two sections, and adds this warning to
the attributes in the first section:
> **Warning** Most of the attributes in this section are in use by the
HTTP semantic conventions.
Once the HTTP semantic conventions are declared stable, changes to the
attributes in this section will only be allowed
if they do not cause breaking changes to HTTP semantic conventions.
Co-authored-by: Liudmila Molkova
Co-authored-by: Carlos Alberto Cortez
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
---
semantic_conventions/trace/general.yaml | 8 ++++-
semantic_conventions/trace/messaging.yaml | 2 --
semantic_conventions/trace/rpc.yaml | 1 -
.../semantic_conventions/span-general.md | 31 +++++++++++++------
4 files changed, 29 insertions(+), 13 deletions(-)
diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml
index 61dac0f0ea3..206a5987a3d 100644
--- a/semantic_conventions/trace/general.yaml
+++ b/semantic_conventions/trace/general.yaml
@@ -1,5 +1,5 @@
groups:
- - id: network
+ - id: network-core
prefix: net
type: attribute_group
brief: >
@@ -108,6 +108,12 @@ groups:
requirement_level:
conditionally_required: If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. In other cases, it is still recommended to set this.
examples: 35555
+ - id: network-connection-and-carrier
+ prefix: net
+ type: attribute_group
+ brief: >
+ These attributes may be used for any network related operation.
+ attributes:
- id: host.connection.type
type:
allow_custom_values: true
diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml
index 4002ddd98ac..4b22ee96326 100644
--- a/semantic_conventions/trace/messaging.yaml
+++ b/semantic_conventions/trace/messaging.yaml
@@ -152,8 +152,6 @@ groups:
- ref: net.protocol.name
examples: ['amqp', 'mqtt']
- ref: net.protocol.version
- constraints:
- - include: network
- id: messaging.producer
prefix: messaging
diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml
index d1993312a92..d79e67d5bf0 100644
--- a/semantic_conventions/trace/rpc.yaml
+++ b/semantic_conventions/trace/rpc.yaml
@@ -77,7 +77,6 @@ groups:
- any_of:
- net.sock.peer.addr
- net.peer.name
- - include: network
- id: rpc.server
prefix: rpc
diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md
index 73e151dea56..04cff6cedac 100644
--- a/specification/trace/semantic_conventions/span-general.md
+++ b/specification/trace/semantic_conventions/span-general.md
@@ -12,6 +12,7 @@ Particular operations may refer to or require some of these attributes.
- [General network connection attributes](#general-network-connection-attributes)
* [Network transport attributes](#network-transport-attributes)
+ * [`net.host.connection.*` and `net.host.carrier.*` attributes](#nethostconnection-and-nethostcarrier-attributes)
* [`net.peer.name` and `net.host.name` attributes](#netpeername-and-nethostname-attributes)
+ [`net.peer.name`](#netpeername)
+ [`net.host.name`](#nethostname)
@@ -37,7 +38,12 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
### Network transport attributes
-
+> **Warning**
+> Most of the attributes in this section are in use by the HTTP semantic conventions.
+Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed
+if they do not cause breaking changes to HTTP semantic conventions.
+
+
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | Recommended |
@@ -53,12 +59,6 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
| `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | Recommended |
| `net.sock.host.addr` | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended |
| `net.sock.host.port` | int | Local socket port number. | `35555` | Conditionally Required: [6] |
-| `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended |
-| `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended |
-| `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended |
-| `net.host.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended |
-| `net.host.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended |
-| `net.host.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended |
**[1]:** `net.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
@@ -91,6 +91,21 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
| `inet` | IPv4 address |
| `inet6` | IPv6 address |
| `unix` | Unix domain socket path |
+
+
+For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `net.peer.name` is the only attribute that usually makes sense (see description of `net.peer.name` below).
+
+### `net.host.connection.*` and `net.host.carrier.*` attributes
+
+
+| Attribute | Type | Description | Examples | Requirement Level |
+|---|---|---|---|---|
+| `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended |
+| `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended |
+| `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended |
+| `net.host.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended |
+| `net.host.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended |
+| `net.host.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended |
`net.host.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
@@ -129,8 +144,6 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
| `lte_ca` | LTE CA |
-For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `net.peer.name` is the only attribute that usually makes sense (see description of `net.peer.name` below).
-
### `net.peer.name` and `net.host.name` attributes
`net.peer.name` and `net.host.name` represent logical host names. Semantic conventions that refer to these attributes SHOULD
From b124b1c77be0a831c3b42ba7f75cb95ec267e614 Mon Sep 17 00:00:00 2001
From: Severin Neumann
Date: Thu, 6 Apr 2023 19:14:26 +0200
Subject: [PATCH 21/36] Add semantic conventions for log record ID (#3047)
Fixes #597
## Changes
- Add a section for "generic attributes" to the log semconv
- Add an attribute `log_record.id` making use of ULID as discussed in
#597
Some additional notes:
- I kept the PR small, so I left out some other potential attributes,
e.g. something for pre-existing ID (like windows event logs) or for
storing the used logging/eventing system or even something like a
"signature" that might be worth discussing, etc.
- I followed the structure of "generic attributes" from the spans
semconv
- I took some of the existing wording from #597 &
https://github.com/open-telemetry/oteps/pull/97#discussion_r421865344 to
describe the field
---------
Signed-off-by: svrnm
Co-authored-by: Joao Grassi
Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com>
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
---
semantic_conventions/logs/general.yaml | 18 +++++++++++++
.../logs/semantic_conventions/README.md | 1 +
.../logs/semantic_conventions/general.md | 27 +++++++++++++++++++
3 files changed, 46 insertions(+)
create mode 100644 semantic_conventions/logs/general.yaml
create mode 100644 specification/logs/semantic_conventions/general.md
diff --git a/semantic_conventions/logs/general.yaml b/semantic_conventions/logs/general.yaml
new file mode 100644
index 00000000000..fc4af35678a
--- /dev/null
+++ b/semantic_conventions/logs/general.yaml
@@ -0,0 +1,18 @@
+groups:
+ - id: log.record
+ prefix: log.record
+ brief: >
+ The attributes described in this section are rather generic. They may be used in any Log Record they apply to.
+ attributes:
+ - id: uid
+ type: string
+ requirement_level: opt_in
+ brief: >
+ A unique identifier for the Log Record.
+ note: >
+ 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.
+ examples: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"]
diff --git a/specification/logs/semantic_conventions/README.md b/specification/logs/semantic_conventions/README.md
index 931e1a7af27..4df36b93317 100644
--- a/specification/logs/semantic_conventions/README.md
+++ b/specification/logs/semantic_conventions/README.md
@@ -4,6 +4,7 @@
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:
diff --git a/specification/logs/semantic_conventions/general.md b/specification/logs/semantic_conventions/general.md
new file mode 100644
index 00000000000..80b679a0bc0
--- /dev/null
+++ b/specification/logs/semantic_conventions/general.md
@@ -0,0 +1,27 @@
+# General attributes
+
+**Status**: [Experimental](../../document-status.md)
+
+The attributes described in this section are rather generic.
+They may be used in any Log Record they apply to.
+
+
+
+
+
+- [General log identification attributes](#general-log-identification-attributes)
+
+
+
+## General log identification attributes
+
+These attributes may be used for identifying a 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.
+
From 10f79bd39615c4ef77f96627bc2308c6ad8289ad Mon Sep 17 00:00:00 2001
From: avzis <107620508+avzis@users.noreply.github.com>
Date: Thu, 6 Apr 2023 20:35:33 +0300
Subject: [PATCH 22/36] Change `db.statement` to only be collected if there is
sanitization (#3127)
---
CHANGELOG.md | 2 ++
semantic_conventions/trace/database.yaml | 5 ++---
specification/trace/semantic_conventions/database.md | 10 ++++------
3 files changed, 8 insertions(+), 9 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57557e3daa4..b4e747a6d42 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -212,6 +212,8 @@ release.
[#3158](https://github.com/open-telemetry/opentelemetry-specification/pull/3158)
- `http.route` SHOULD contain the "application root" if there is one.
([#3164](https://github.com/open-telemetry/opentelemetry-specification/pull/3164))
+- Change `db.statement` to only be collected if there is sanitization.
+ ([#3127](https://github.com/open-telemetry/opentelemetry-specification/pull/3127))
### Compatibility
diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml
index e89f5eadf3c..65cda87cf73 100644
--- a/semantic_conventions/trace/database.yaml
+++ b/semantic_conventions/trace/database.yaml
@@ -207,11 +207,10 @@ groups:
tag: call-level
type: string
requirement_level:
- conditionally_required: >
- If applicable and not explicitly disabled via instrumentation configuration.
+ recommended: >
+ Should be collected by default only if there is sanitization that excludes sensitive information.
brief: >
The database statement being executed.
- note: The value may be sanitized to exclude sensitive information.
examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"']
- id: operation
tag: call-level
diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md
index 22705196e3e..36bff3d5442 100644
--- a/specification/trace/semantic_conventions/database.md
+++ b/specification/trace/semantic_conventions/database.md
@@ -162,16 +162,14 @@ Usually only one `db.name` will be used per connection though.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. |
-| `db.statement` | string | The database statement being executed. [2] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Conditionally Required: [3] |
-| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [4] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. |
+| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [2] |
+| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [3] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. |
**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name).
-**[2]:** The value may be sanitized to exclude sensitive information.
+**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information.
-**[3]:** If applicable and not explicitly disabled via instrumentation configuration.
-
-**[4]:** 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.
+**[3]:** 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.
For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI.
From 2d654da8750f792af58d6a581c3119959c0a0c89 Mon Sep 17 00:00:00 2001
From: Reiley Yang
Date: Thu, 6 Apr 2023 15:00:48 -0700
Subject: [PATCH 23/36] [Editorial] Fix changelog (#3373)
Relocate the changelog for #3127.
---
CHANGELOG.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b4e747a6d42..3bd99a66f7e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -67,6 +67,8 @@ release.
([#3202](https://github.com/open-telemetry/opentelemetry-specification/pull/3202))
- Add Trino to Database specific conventions
([#3347](https://github.com/open-telemetry/opentelemetry-specification/pull/3347))
+- Change `db.statement` to only be collected if there is sanitization.
+ ([#3127](https://github.com/open-telemetry/opentelemetry-specification/pull/3127))
### Compatibility
@@ -212,8 +214,6 @@ release.
[#3158](https://github.com/open-telemetry/opentelemetry-specification/pull/3158)
- `http.route` SHOULD contain the "application root" if there is one.
([#3164](https://github.com/open-telemetry/opentelemetry-specification/pull/3164))
-- Change `db.statement` to only be collected if there is sanitization.
- ([#3127](https://github.com/open-telemetry/opentelemetry-specification/pull/3127))
### Compatibility
From 7956b56ce6cd2a216e48dbc13344897f49bbec85 Mon Sep 17 00:00:00 2001
From: Tristan Sloughter
Date: Thu, 6 Apr 2023 22:31:08 -0600
Subject: [PATCH 24/36] Remove underspecified and unused Span decorator from
Trace SDK. (#3363)
---
CHANGELOG.md | 4 +++-
specification/trace/sdk.md | 3 +--
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3bd99a66f7e..fc550d05eb7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,9 +11,11 @@ release.
### Traces
-* Clarify required parent information in ReadableSpan. Technically a relaxation,
+- Clarify required parent information in ReadableSpan. Technically a relaxation,
but previously it was easy to overlook certain properties were required.
[#3257](https://github.com/open-telemetry/opentelemetry-specification/pull/3257)
+- Remove underspecified and unused Span decorator from Trace SDK.
+ ([#3363](https://github.com/open-telemetry/opentelemetry-specification/pull/3363))
### Metrics
diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md
index ec69c39b8fd..fd37af985cf 100644
--- a/specification/trace/sdk.md
+++ b/specification/trace/sdk.md
@@ -470,8 +470,7 @@ Each processor registered on `TracerProvider` is a start of pipeline that consis
of span processor and optional exporter. SDK MUST allow to end each pipeline with
individual exporter.
-SDK MUST allow users to implement and configure custom processors and decorate
-built-in processors for advanced scenarios such as tagging or filtering.
+SDK MUST allow users to implement and configure custom processors.
The following diagram shows `SpanProcessor`'s relationship to other components
in the SDK:
From 52b357804f05c8dbc52901fc755cb783a0286a4b Mon Sep 17 00:00:00 2001
From: Trask Stalnaker
Date: Thu, 6 Apr 2023 21:36:41 -0700
Subject: [PATCH 25/36] BREAKING: Remove http.status_code attribute from the
http.server.active_requests metric (#3366)
---
CHANGELOG.md | 3 +++
semantic_conventions/metrics/http.yaml | 1 -
specification/metrics/semantic_conventions/http-metrics.md | 1 -
3 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc550d05eb7..306bce3fa06 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -71,6 +71,9 @@ release.
([#3347](https://github.com/open-telemetry/opentelemetry-specification/pull/3347))
- Change `db.statement` to only be collected if there is sanitization.
([#3127](https://github.com/open-telemetry/opentelemetry-specification/pull/3127))
+- BREAKING: Remove `http.status_code` attribute from the
+ `http.server.active_requests` metric.
+ ([#3366](https://github.com/open-telemetry/opentelemetry-specification/pull/3366))
### Compatibility
diff --git a/semantic_conventions/metrics/http.yaml b/semantic_conventions/metrics/http.yaml
index 2ae7581c4e1..ed1fc781844 100644
--- a/semantic_conventions/metrics/http.yaml
+++ b/semantic_conventions/metrics/http.yaml
@@ -21,7 +21,6 @@ groups:
unit: "{request}"
attributes:
- ref: http.method
- - ref: http.status_code
- ref: http.scheme
- ref: net.host.name
requirement_level: required
diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
index b76087662dc..e18bb475bae 100644
--- a/specification/metrics/semantic_conventions/http-metrics.md
+++ b/specification/metrics/semantic_conventions/http-metrics.md
@@ -90,7 +90,6 @@ This metric is optional.
|---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required |
-| `http.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. |
| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `localhost` | Required |
| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `8080` | Conditionally Required: [3] |
From 26dbcc26d9a36c615c349a8526b729953cedbd5b Mon Sep 17 00:00:00 2001
From: Trask Stalnaker
Date: Thu, 6 Apr 2023 21:56:17 -0700
Subject: [PATCH 26/36] Mark attribute requirement levels as stable (#3368)
---
CHANGELOG.md | 2 ++
specification/common/attribute-requirement-level.md | 2 +-
2 files changed, 3 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 306bce3fa06..66ef1dc564c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -74,6 +74,8 @@ release.
- BREAKING: Remove `http.status_code` attribute from the
`http.server.active_requests` metric.
([#3366](https://github.com/open-telemetry/opentelemetry-specification/pull/3366))
+- Mark attribute requirement levels as stable
+ ([#3368](https://github.com/open-telemetry/opentelemetry-specification/pull/3368))
### Compatibility
diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md
index 3543970a29e..e9da7f07025 100644
--- a/specification/common/attribute-requirement-level.md
+++ b/specification/common/attribute-requirement-level.md
@@ -1,6 +1,6 @@
# Attribute Requirement Levels for Semantic Conventions
-**Status**: [Experimental](../document-status.md)
+**Status**: [Stable](../document-status.md)
Table of Contents
From 8de4926b73c9538d855670988aad73de42aad287 Mon Sep 17 00:00:00 2001
From: Patrice Chalin
Date: Fri, 7 Apr 2023 15:55:06 -0400
Subject: [PATCH 27/36] [editorial] Use path, not external URL, for link into
glossary (#3375)
- Contributes to
https://github.com/open-telemetry/opentelemetry.io/issues/2429
- This is part of an effort to normalize links, for improved link
checking on the OTel website
---
specification/common/attribute-requirement-level.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md
index e9da7f07025..cfbc22b9da2 100644
--- a/specification/common/attribute-requirement-level.md
+++ b/specification/common/attribute-requirement-level.md
@@ -19,7 +19,7 @@
_This section applies to Log, Metric, Resource, and Span, and describes requirement levels for attributes defined in semantic conventions._
-Attribute requirement levels apply to the [instrumentation library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library).
+Attribute requirement levels apply to the [instrumentation library](../glossary.md#instrumentation-library).
The following attribute requirement levels are specified:
From 855d80c93ffc11ee7c96177be8082989afb020f5 Mon Sep 17 00:00:00 2001
From: Carlos Alberto Cortez
Date: Fri, 7 Apr 2023 15:14:18 -0600
Subject: [PATCH 28/36] Release 1.20.0 (#3364)
April release.
---
CHANGELOG.md | 47 +++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 45 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 66ef1dc564c..a1d6b71d4af 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,32 @@ release.
### Traces
+### Metrics
+
+### Logs
+
+### Resource
+
+### Semantic Conventions
+
+### Compatibility
+
+### OpenTelemetry Protocol
+
+### SDK Configuration
+
+### Telemetry Schemas
+
+### Common
+
+## v1.20.0 (2023-04-07)
+
+### Context
+
+- No changes.
+
+### Traces
+
- Clarify required parent information in ReadableSpan. Technically a relaxation,
but previously it was easy to overlook certain properties were required.
[#3257](https://github.com/open-telemetry/opentelemetry-specification/pull/3257)
@@ -23,8 +49,6 @@ release.
([#3306](https://github.com/open-telemetry/opentelemetry-specification/pull/3306))
- Remove No-Op instrument and Meter creation requirements.
([#3322](https://github.com/open-telemetry/opentelemetry-specification/pull/3322))
-- Fixed attributes requirement level in semantic conventions for hardware metrics
- ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
### Logs
@@ -43,6 +67,8 @@ release.
### Resource
+- No changes.
+
### Semantic Conventions
- Clarify that attribute requirement levels apply to the instrumentation library
@@ -67,6 +93,12 @@ release.
- Stabilize key components of `service.*` and `telemetry.sdk.*` resource
semantic conventions.
([#3202](https://github.com/open-telemetry/opentelemetry-specification/pull/3202))
+- Fixed attributes requirement level in semantic conventions for hardware metrics
+ ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
+- Added AWS S3 semantic conventions.
+ ([#3251](https://github.com/open-telemetry/opentelemetry-specification/pull/3251))
+- Fix units in the Kafka metric semantic conventions.
+ ([#3300](https://github.com/open-telemetry/opentelemetry-specification/pull/3300))
- Add Trino to Database specific conventions
([#3347](https://github.com/open-telemetry/opentelemetry-specification/pull/3347))
- Change `db.statement` to only be collected if there is sanitization.
@@ -79,14 +111,25 @@ release.
### Compatibility
+- No changes.
+
### OpenTelemetry Protocol
+- Declare OTLP stable.
+ ([#3274](https://github.com/open-telemetry/opentelemetry-specification/pull/3274))
+
### SDK Configuration
+- No changes.
+
### Telemetry Schemas
+- No changes.
+
### Common
+- No changes.
+
## v1.19.0 (2023-03-06)
### Context
From 29f8007c98736614bd32371facb3dd390a37818d Mon Sep 17 00:00:00 2001
From: Alan West <3676547+alanwest@users.noreply.github.com>
Date: Sat, 8 Apr 2023 08:42:13 -0700
Subject: [PATCH 29/36] Clarify parameters for emtting a log record (#3354)
Supersedes #3350
Clarifies the parameters for emitting a log record.
Context was particularly confusing. Context is not a property of the
`LogRecord` data model. Cleans up section of bridge API spec that seems
to suggest that Context is a field of `LogRecord`. Also, clarifies that
Context can be associated with an emitted LogRecord. We have similar
language in the trace API that leaves room for languages to achieve this
in an idiomatic way. See
https://github.com/open-telemetry/opentelemetry-specification/blob/d25734a47e6534a1bc8a52cb2bd51d42e987024b/specification/trace/api.md?plain=1#L365-L370
---------
Co-authored-by: Reiley Yang
---
CHANGELOG.md | 3 ++
specification/logs/README.md | 2 +-
specification/logs/bridge-api.md | 32 ++++++++-----------
specification/logs/event-api.md | 6 ++--
specification/logs/noop.md | 2 +-
specification/logs/sdk.md | 10 +++---
.../logs/semantic_conventions/exceptions.md | 6 ++--
.../semantic_conventions/feature-flags.md | 8 ++---
specification/versioning-and-stability.md | 2 +-
9 files changed, 34 insertions(+), 37 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a1d6b71d4af..a6590c00b68 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,9 @@ release.
### Logs
+- Clarify parameters for emitting a log record.
+ ([#3345](https://github.com/open-telemetry/opentelemetry-specification/pull/3354))
+
### Resource
### Semantic Conventions
diff --git a/specification/logs/README.md b/specification/logs/README.md
index bbab7393330..e2afcfdd159 100644
--- a/specification/logs/README.md
+++ b/specification/logs/README.md
@@ -137,7 +137,7 @@ Given the above state of the logging space we took the following approach:
translate them to OpenTelemetry log data model.
- OpenTelemetry defines a Logs Bridge API
- for [emitting LogRecords](./bridge-api.md#emit-logrecord). Application developers are
+ for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). Application developers are
NOT encouraged to call this API directly. It is provided for library authors
to build [log appender](../glossary.md#log-appender--bridge), which use
the API to bridge between existing logging libraries and the OpenTelemetry log
diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md
index 25c3a210e07..2a51cedf69b 100644
--- a/specification/logs/bridge-api.md
+++ b/specification/logs/bridge-api.md
@@ -14,8 +14,7 @@
+ [Get a Logger](#get-a-logger)
- [Logger](#logger)
* [Logger operations](#logger-operations)
- + [Emit LogRecord](#emit-logrecord)
-- [LogRecord](#logrecord)
+ + [Emit a LogRecord](#emit-a-logrecord)
- [Optional and required parameters](#optional-and-required-parameters)
- [Concurrency requirements](#concurrency-requirements)
- [Artifact Naming](#artifact-naming)
@@ -37,7 +36,8 @@ data model.
The Logs Bridge API consist of these main classes:
* [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s.
-* [Logger](#logger) is the class responsible for emitting logs as [LogRecords](#logrecord).
+* [Logger](#logger) is the class responsible for emitting logs as
+ [LogRecords](./data-model.md#log-and-event-record-definition).
```mermaid
graph TD
@@ -111,27 +111,21 @@ The `Logger` is responsible for emitting `LogRecord`s.
The `Logger` MUST provide functions to:
-#### Emit LogRecord
+- Emit a `LogRecord`
-Emit a `LogRecord` to the processing pipeline.
+#### Emit a LogRecord
-This function MAY be named `logRecord`.
+`LogRecord`s encapsulate the fields identified in the [`LogRecord`
+data model](data-model.md#log-and-event-record-definition) and are emitted to the processing pipeline using
+this API.
-**Parameters:**
-
-* `logRecord` - the [LogRecord](#logrecord) to emit.
-
-## LogRecord
-
-The API emits [LogRecords](#emit-logrecord) using the `LogRecord` [data model](data-model.md).
-
-A function receiving this as an argument MUST be able to set the following
-parameters:
+The API MUST accept the following parameters:
- [Timestamp](./data-model.md#field-timestamp)
- [Observed Timestamp](./data-model.md#field-observedtimestamp)
-- [Context](../context/README.md) that contains the
- [TraceContext](./data-model.md#trace-context-fields)
+- The [Context](../context/README.md) associated with the `LogRecord`. The API
+ MAY implicitly use the current Context as a default
+ behavior.
- [Severity Number](./data-model.md#field-severitynumber)
- [Severity Text](./data-model.md#field-severitytext)
- [Body](./data-model.md#field-body)
@@ -181,7 +175,7 @@ approaches.
The log appender implementation will typically acquire a [Logger](#logger) from the
global [LoggerProvider](#loggerprovider) at startup time, then
-call [Emit LogRecord](#emit-logrecord) for `LogRecord`s received from the
+call [Emit LogRecord](#emit-a-logrecord) for `LogRecord`s received from the
application.
[Implicit Context Injection](#implicit-context-injection)
diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md
index f9075d16104..78facadb2a3 100644
--- a/specification/logs/event-api.md
+++ b/specification/logs/event-api.md
@@ -42,7 +42,7 @@ OpenTelemetry events. In some logging libraries, producing records shaped as
OpenTelemetry events is clunky or error-prone.
The Event API offers convenience methods
-for [emitting LogRecords](./bridge-api.md#emit-logrecord) that conform
+for [emitting LogRecords](./bridge-api.md#emit-a-logrecord) that conform
to the [semantic conventions for Events](./semantic_conventions/events.md).
Unlike the [Logs Bridge API](./bridge-api.md), application developers and
instrumentation authors are encouraged to call this API directly.
@@ -80,11 +80,11 @@ This function MAY be named `logEvent`.
attribute with the key `event.name`. Care MUST be taken by the implementation
to not override or delete this attribute while the Event is emitted to
preserve its identity.
-* `logRecord` - the [LogRecord](./bridge-api.md#logrecord) representing the Event.
+* `logRecord` - the [LogRecord](./data-model.md#log-and-event-record-definition) representing the Event.
**Implementation Requirements:**
-The implementation MUST [emit](./bridge-api.md#emit-logrecord) the `logRecord` to
+The implementation MUST [emit](./bridge-api.md#emit-a-logrecord) the `logRecord` to
the `logger` specified when [creating the EventLogger](#create-eventlogger)
after making the following changes:
diff --git a/specification/logs/noop.md b/specification/logs/noop.md
index 896e11721f3..34c538c628e 100644
--- a/specification/logs/noop.md
+++ b/specification/logs/noop.md
@@ -54,4 +54,4 @@ return the same `Logger` instances to all creation requests.
### Emit LogRecord
The No-Op `Logger` MUST allow
-for [emitting LogRecords](./bridge-api.md#emit-logrecord).
+for [emitting LogRecords](./bridge-api.md#emit-a-logrecord).
diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md
index 05d82d68e47..08300accdd3 100644
--- a/specification/logs/sdk.md
+++ b/specification/logs/sdk.md
@@ -121,7 +121,7 @@ registered [LogRecordProcessors](#logrecordprocessor).
## Logger
If a `Logger` was obtained with `include_trace_context=true`, the `LogRecord`s
-it [emits](./bridge-api.md#emit-logrecord) MUST automatically include the Trace
+it [emits](./bridge-api.md#emit-a-logrecord) MUST automatically include the Trace
Context from the active Context, if Context has not been explicitly set.
Note that `Logger`s should not be responsible for configuration. This should be
@@ -129,13 +129,13 @@ the responsibility of the `LoggerProvider` instead.
## Additional LogRecord interfaces
-In addition to the [API-level definition for LogRecord](bridge-api.md#logrecord), the
+In addition to the [definition for LogRecord](data-model.md#log-and-event-record-definition), the
following `LogRecord`-like interfaces are defined in the SDK:
### ReadableLogRecord
A function receiving this as an argument MUST be able to access all the
-information added to the [LogRecord](bridge-api.md#logrecord). It MUST also be able to
+information added to the [LogRecord](data-model.md#log-and-event-record-definition). It MUST also be able to
access the [Instrumentation Scope](./data-model.md#field-instrumentationscope)
and [Resource](./data-model.md#field-resource) information (implicitly)
associated with the `LogRecord`.
@@ -151,7 +151,7 @@ value type.
### ReadWriteLogRecord
A function receiving this as an argument MUST be able to write to the
-full [LogRecord](bridge-api.md#logrecord) and additionally MUST be able to retrieve all
+full [LogRecord](data-model.md#log-and-event-record-definition) and additionally MUST be able to retrieve all
information
that was added to the `LogRecord` (as with
[ReadableLogRecord](#readablelogrecord)).
@@ -226,7 +226,7 @@ components in the SDK:
#### OnEmit
-`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-logrecord). This
+`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-a-logrecord). This
method is called synchronously on the thread that emitted the `LogRecord`,
therefore it SHOULD NOT block or throw exceptions.
diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md
index 63890971010..f40d44cb89d 100644
--- a/specification/logs/semantic_conventions/exceptions.md
+++ b/specification/logs/semantic_conventions/exceptions.md
@@ -3,7 +3,7 @@
**Status**: [Experimental](../../document-status.md)
This document defines semantic conventions for recording exceptions on
-[logs](../bridge-api.md#emit-logrecord) and [events](../event-api.md#emit-event)
+[logs](../bridge-api.md#emit-a-logrecord) and [events](../event-api.md#emit-event)
emitted through the [Logger API](../bridge-api.md#logger).
@@ -17,7 +17,7 @@ emitted through the [Logger API](../bridge-api.md#logger).
## Recording an Exception
Exceptions SHOULD be recorded as attributes on the
-[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit
+[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit
operations. Exceptions MAY be recorded on "logs" or "events" depending on the
context.
@@ -29,7 +29,7 @@ the language runtime.
## Attributes
The table below indicates which attributes should be added to the
-[LogRecord](../bridge-api.md#logrecord) and their types.
+[LogRecord](../data-model.md#log-and-event-record-definition) and their types.
| Attribute | Type | Description | Examples | Requirement Level |
diff --git a/specification/logs/semantic_conventions/feature-flags.md b/specification/logs/semantic_conventions/feature-flags.md
index 763821ada99..25c62b58e9c 100644
--- a/specification/logs/semantic_conventions/feature-flags.md
+++ b/specification/logs/semantic_conventions/feature-flags.md
@@ -3,8 +3,8 @@
**Status**: [Experimental](../../document-status.md)
This document defines semantic conventions for recording feature flag evaluations as
-a [log record](../bridge-api.md#logrecord) emitted through the
-[Logger API](../bridge-api.md#emit-logrecord).
+a [log record](../data-model.md#log-and-event-record-definition) emitted through the
+[Logger API](../bridge-api.md#emit-a-logrecord).
This is useful when a flag is evaluated outside of a transaction context
such as when the application loads or on a timer.
To record a flag evaluation as a part of a transaction context,
@@ -24,14 +24,14 @@ section of the trace semantic convention for feature flag evaluations.
## Recording an Evaluation
Feature flag evaluations SHOULD be recorded as attributes on the
-[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit
+[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit
operations. Evaluations MAY be recorded on "logs" or "events" depending on the
context.
## Attributes
The table below indicates which attributes should be added to the
-[LogRecord](../bridge-api.md#logrecord) and their types.
+[LogRecord](../data-model.md#log-and-event-record-definition) and their types.
The event name MUST be `feature_flag`.
diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md
index a0a5b8da7b1..f56162543e5 100644
--- a/specification/versioning-and-stability.md
+++ b/specification/versioning-and-stability.md
@@ -204,7 +204,7 @@ Semantic Conventions defines the set of fields in the OTLP data model:
both synchronous and asynchronous instruments.
- These exist on `NumberDataPoint`, `HistogramDataPoint`,
`ExponentialHistogramDataPoint` and `SummaryDataPoint`.
-- [Log Records](logs/bridge-api.md#logrecord)
+- [Log Records](logs/data-model.md#log-and-event-record-definition)
- The attribute keys provided on the LogRecord
- For log records that are [Log Events](logs/event-api.md)
- The following data provided to [emit event](logs/event-api.md#emit-event):
From feb4dac0742e3dd749954af295086ffdcd4571c8 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Sat, 8 Apr 2023 10:55:36 -0500
Subject: [PATCH 30/36] Propose histogram bucket boundary metric advice (aka
hint API) (#3216)
Fixes #2229.
Related to #3061 (lays groundwork but does not resolve).
Related to #2977, which may use this new API to have
`http.server.duration` report in seconds instead of ms without changing
/ breaking default bucket boundaries.
Summary of the change:
- Proposes a new parameter to optionally include when creating
instruments, called "advice".
- For the moment, advice only has one parameter for specifying the
bucket boundaries of explicit bucket histogram.
- Advice can be expanded with additional parameters in the future (e.g.
default attributes to retain). The parameters may be general (aka
applicable to all instruments) or specific to a particular instrument
kind, like bucket boundaries.
- Advice parameters can influence the [default
aggregation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#default-aggregation),
which is used if there is no matching view and if the reader does not
specify a preferred aggregation.
- Not clear that all advice will be oriented towards configuring
aggregation, so I've intentionally left the scope of what they can
influence open ended.
I've prototyped this in java
[here](https://github.com/open-telemetry/opentelemetry-java/pull/5217).
Example usage:
```
DoubleHistogram doubleHistogram =
meterProvider
.get("meter")
.histogramBuilder("histogram")
.setUnit("foo")
.setDescription("bar")
.setAdvice(
advice -> advice.setBoundaries(Arrays.asList(10.0, 20.0, 30.0)))
.build();
```
Advice could easily be changed to "hint" with everything else being
equal. I thought "advice" clearly described what we're trying to
accomplish, which is advice / recommend the implementation in providing
useful output with minimal configuration.
---------
Co-authored-by: Reiley Yang
---
CHANGELOG.md | 5 +++++
specification/metrics/api.md | 31 ++++++++++++++++++++++++++++++-
specification/metrics/sdk.md | 31 ++++++++++++++++++++-----------
3 files changed, 55 insertions(+), 12 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6590c00b68..4921c3137ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,9 @@ release.
### Metrics
+- Add experimental histogram advice API.
+ ([#3216](https://github.com/open-telemetry/opentelemetry-specification/pull/3216))
+
### Logs
- Clarify parameters for emitting a log record.
@@ -52,6 +55,8 @@ release.
([#3306](https://github.com/open-telemetry/opentelemetry-specification/pull/3306))
- Remove No-Op instrument and Meter creation requirements.
([#3322](https://github.com/open-telemetry/opentelemetry-specification/pull/3322))
+- Fixed attributes requirement level in semantic conventions for hardware metrics
+ ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
### Logs
diff --git a/specification/metrics/api.md b/specification/metrics/api.md
index d044bc348a6..9cc473b4b7a 100644
--- a/specification/metrics/api.md
+++ b/specification/metrics/api.md
@@ -4,7 +4,7 @@ linkTitle: API
# Metrics API
-**Status**: [Stable](../document-status.md)
+**Status**: [Stable](../document-status.md), except where otherwise specified
Table of Contents
@@ -22,6 +22,7 @@ linkTitle: API
+ [Instrument name syntax](#instrument-name-syntax)
+ [Instrument unit](#instrument-unit)
+ [Instrument description](#instrument-description)
+ + [Instrument advice](#instrument-advice)
+ [Synchronous and Asynchronous instruments](#synchronous-and-asynchronous-instruments)
- [Synchronous Instrument API](#synchronous-instrument-api)
- [Asynchronous Instrument API](#asynchronous-instrument-api)
@@ -182,6 +183,7 @@ will have the following fields:
one of the other kinds, whether it is synchronous or asynchronous
* An optional `unit` of measure
* An optional `description`
+* Optional `advice` (**experimental**)
Instruments are associated with the Meter during creation. Instruments
are identified by all of these fields.
@@ -235,6 +237,22 @@ instrument. The API MUST treat it as an opaque string.
* It MUST support at least 1023 characters. [OpenTelemetry
API](../overview.md#api) authors MAY decide if they want to support more.
+#### Instrument advice
+
+**Status**: [Experimental](../document-status.md)
+
+`advice` are an optional set of recommendations provided by the author of the
+Instrument, aimed at assisting implementations in providing useful output with
+minimal configuration.
+
+* Implementations MAY ignore `advice`. However, OpenTelemetry SDKs
+ handle `advice` as described [here](./sdk.md#instrument-advice).
+* `advice` parameters may be general, or vary by instrument `kind`.
+ * `Histogram`:
+ * `ExplicitBucketBoundaries` (`double[]`): The recommended set of bucket
+ boundaries to use if aggregating to
+ [explicit bucket Histogram metric data point](./data-model.md#histogram).
+
#### Synchronous and Asynchronous instruments
Instruments are categorized on whether they are synchronous or
@@ -295,6 +313,17 @@ The API to construct synchronous instruments MUST accept the following parameter
0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane)
encoded characters and hold at least 1023 characters.
+* `advice` for implementations.
+
+ Users can provide `advice`, but its up to their discretion. Therefore, this
+ API needs to be structured to accept `advice`, but MUST NOT obligate the user
+ to provide it.
+
+ `advice` needs to be structured as described
+ in [instrument advice](#instrument-advice), with parameters that are general
+ and specific to a particular instrument `kind`. The API SHOULD NOT
+ validate `advice`.
+
##### Asynchronous Instrument API
Asynchronous instruments have associated `callback` functions which
diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
index c3776142538..eab03a4dfd4 100644
--- a/specification/metrics/sdk.md
+++ b/specification/metrics/sdk.md
@@ -35,6 +35,7 @@ linkTitle: SDK
* [Instrument name](#instrument-name)
* [Instrument unit](#instrument-unit)
* [Instrument description](#instrument-description)
+ * [Instrument advice](#instrument-advice)
- [Attribute limits](#attribute-limits)
- [Exemplar](#exemplar)
* [ExemplarFilter](#exemplarfilter)
@@ -396,18 +397,18 @@ This Aggregation does not have any configuration parameters.
#### Default Aggregation
-The Default Aggregation informs the SDK to use the Instrument Kind
-(e.g. at View registration OR at first seen measurement)
-to select an aggregation and configuration parameters.
+The Default Aggregation informs the SDK to use the Instrument `kind` to select
+an aggregation and `advice` to influence aggregation configuration parameters
+(as noted in the "Selected Aggregation" column).
-| Instrument Kind | Selected Aggregation |
-| --- |-----------------------------------------------------------------------------------------|
-| [Counter](./api.md#counter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
-| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
-| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
-| [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
-| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) |
-| [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation) |
+| Instrument Kind | Selected Aggregation |
+|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Counter](./api.md#counter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
+| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
+| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
+| [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) |
+| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) |
+| [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation), with `ExplicitBucketBoundaries` from [advice](./api.md#instrument-advice) if provided |
This Aggregation does not have any configuration parameters.
@@ -643,6 +644,14 @@ When a Meter creates an instrument, it SHOULD NOT validate the instrument
description. If a description is not provided or the description is null, the
Meter MUST treat it the same as an empty description string.
+### Instrument advice
+
+**Status**: [Experimental](../document-status.md)
+
+When a Meter creates an instrument, it SHOULD validate the instrument advice
+parameters. If an advice parameter is not valid, the Meter SHOULD emit an error
+notifying the user and proceed as if the parameter was not provided.
+
## Attribute limits
**Status**: [Stable](../document-status.md)
From 0f6fbe54aa07d272041a07cacc51565a876b4963 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20Neum=C3=BCller?=
Date: Tue, 11 Apr 2023 15:13:14 +0200
Subject: [PATCH 31/36] Add back refs to cloud.resource_id lost in FaaS
renaming. (#3329)
These places were removed when #3188 in its original form removed
faas.id without replacement and weren't added back after changing it to
introduce cloud.resource_id instead.
Editorial change, no CHANGELOG or issue.
---
semantic_conventions/resource/faas.yaml | 1 +
.../resource/semantic_conventions/faas.md | 19 +++++++++++++++++++
.../trace/semantic_conventions/faas.md | 1 +
3 files changed, 21 insertions(+)
diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml
index 4a7d3e4f306..df1716b7d0b 100644
--- a/semantic_conventions/resource/faas.yaml
+++ b/semantic_conventions/resource/faas.yaml
@@ -60,3 +60,4 @@ groups:
On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE`
provides this information (which must be multiplied by 1,048,576).
examples: 134217728
+ - ref: cloud.resource_id
diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md
index b707bbf0f6c..e1c2c11a366 100644
--- a/specification/resource/semantic_conventions/faas.md
+++ b/specification/resource/semantic_conventions/faas.md
@@ -20,6 +20,7 @@ See also:
| `faas.version` | string | The immutable version of the function being executed. [2] | `26`; `pinkfroid-00002` | Recommended |
| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [3] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended |
| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [4] | `134217728` | Recommended |
+| [`cloud.resource_id`](cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [5] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended |
**[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
@@ -51,6 +52,24 @@ definition of function name MUST be used for this attribute
**[3]:** * **AWS Lambda:** Use the (full) log stream name.
**[4]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576).
+
+**[5]:** On some cloud providers, it may not be possible to determine the full ID at startup,
+so it may be necessary to set `cloud.resource_id` as a span attribute instead.
+
+The exact value to use for `cloud.resource_id` depends on the cloud provider.
+The following well-known definitions MUST be used if you set this attribute and they apply:
+
+* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
+ Take care not to use the "invoked ARN" directly but replace any
+ [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html)
+ with the resolved function version, as the same runtime instance may be invokable with
+ multiple different aliases.
+* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names)
+* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function,
+ *not* the function app, having the form
+ `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`.
+ This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
+ a TracerProvider.
Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-invocation-and-instance).
diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md
index 4acb5fa84d0..cfa486030a3 100644
--- a/specification/trace/semantic_conventions/faas.md
+++ b/specification/trace/semantic_conventions/faas.md
@@ -254,3 +254,4 @@ This example shows the FaaS attributes for a (non-FaaS) process hosted on Google
| Resource | `faas.name` | n/a | `"my-lambda-function"` |
| Resource | `faas.version` | n/a | `"semver:2.0.0"` |
| Resource | `faas.instance` | n/a | `"my-lambda-function:instance-0001"` |
+| Resource | `cloud.resource_id` | n/a | `"arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"` |
From b0ba0a93ef24f39146c7006423be0f4e1813d1b2 Mon Sep 17 00:00:00 2001
From: Sebastien Rosset
Date: Tue, 11 Apr 2023 09:29:16 -0700
Subject: [PATCH 32/36] Update the description of the `host.image` attribute
(#3194)
---
semantic_conventions/resource/host.yaml | 6 +++---
specification/resource/semantic_conventions/host.md | 6 +++---
2 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/semantic_conventions/resource/host.yaml b/semantic_conventions/resource/host.yaml
index c5bfa4399bf..457aa1c8ae3 100644
--- a/semantic_conventions/resource/host.yaml
+++ b/semantic_conventions/resource/host.yaml
@@ -3,7 +3,7 @@ groups:
prefix: host
type: resource
brief: >
- A host is defined as a general computing instance.
+ A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array.
attributes:
- id: id
type: string
@@ -62,11 +62,11 @@ groups:
- id: image.id
type: string
brief: >
- VM image ID. For Cloud, this value is from the provider.
+ VM image ID or host OS image ID. For Cloud, this value is from the provider.
examples: ['ami-07b06b442921831e5']
- id: image.version
type: string
brief: >
- The version string of the VM image as defined in
+ The version string of the VM image or host OS as defined in
[Version Attributes](README.md#version-attributes).
examples: ['0.1']
diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/semantic_conventions/host.md
index 94ffccf0368..7fe24db93aa 100644
--- a/specification/resource/semantic_conventions/host.md
+++ b/specification/resource/semantic_conventions/host.md
@@ -4,7 +4,7 @@
**type:** `host`
-**Description:** A host is defined as a general computing instance.
+**Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array.
| Attribute | Type | Description | Examples | Requirement Level |
@@ -14,8 +14,8 @@
| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended |
| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | Recommended |
| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | Recommended |
-| `host.image.id` | string | VM image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | Recommended |
-| `host.image.version` | string | The version string of the VM image as defined in [Version Attributes](README.md#version-attributes). | `0.1` | Recommended |
+| `host.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | Recommended |
+| `host.image.version` | string | The version string of the VM image or host OS as defined in [Version Attributes](README.md#version-attributes). | `0.1` | Recommended |
`host.arch` 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.
From 40e0457a3b86339a83bb1007c974e3e72a5feb3b Mon Sep 17 00:00:00 2001
From: Bertrand Martin <32521698+bertysentry@users.noreply.github.com>
Date: Wed, 12 Apr 2023 01:18:48 +0200
Subject: [PATCH 33/36] Issues #3132, #3133: Semconv for hardware metrics,
network metrics and attributes (#3344)
Fixes #3132, #3133
## Changes
In semantic conventions for hardware metrics:
* Updated network adapter description
* Changed `type` to `hw.error.type` for the `hw.errors` metric
---
.../semantic_conventions/hardware-metrics.md | 72 ++++++++++---------
1 file changed, 38 insertions(+), 34 deletions(-)
diff --git a/specification/metrics/semantic_conventions/hardware-metrics.md b/specification/metrics/semantic_conventions/hardware-metrics.md
index c6cc24e2729..9037d4d3558 100644
--- a/specification/metrics/semantic_conventions/hardware-metrics.md
+++ b/specification/metrics/semantic_conventions/hardware-metrics.md
@@ -52,12 +52,12 @@ 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 |
-| ----------- | ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ---------------------- | -------------------------- |
-| `hw.energy` | Energy consumed by the component, in joules | J | Counter | Int64 | | |
-| `hw.errors` | Number of errors encountered by the component | {error} | Counter | Int64 | `type` (Recommended) | |
-| `hw.power` | Instantaneous power consumed by the component, in Watts (`hw.energy` is preferred) | W | Gauge | Double | | |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
+| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values |
+| ----------- | ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | -------------------------- |
+| `hw.energy` | Energy consumed by the component, in joules | J | Counter | Int64 | | |
+| `hw.errors` | Number of errors encountered by the component | {error} | Counter | Int64 | `hw.error.type` (Recommended) | |
+| `hw.power` | Instantaneous power consumed by the component, in Watts (`hw.energy` is preferred) | W | Gauge | Double | | |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
These common `hw.` metrics must include the below attributes to describe the
monitored component:
@@ -194,18 +194,18 @@ Additional **Recommended** attributes:
**Description:** Graphics Processing Unit (discrete)
-| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
-| --------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------- |
-| `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `type` (Recommended) | `corrected`, `all` |
-| | | | | | `hw.type` (**Required**) | `gpu` |
-| `hw.gpu.io` | Received and transmitted bytes by the GPU | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
-| `hw.gpu.memory.limit` | Size of the GPU memory | By | UpDownCounter | Int64 | | |
-| `hw.gpu.memory.utilization` | Fraction of GPU memory used | 1 | Gauge | Double | | |
-| `hw.gpu.memory.usage` | GPU memory used | By | UpDownCounter | Int64 | | |
-| `hw.gpu.power` | GPU instantaneous power consumption in Watts | W | Gauge | Double | | |
-| `hw.gpu.utilization` | Fraction of time spent in a specific task | 1 | Gauge | Double | `task` (Recommended) | `decoder`, `encoder`, `general` |
-| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` |
-| | | | | | `hw.type` (**Required**) | `gpu` |
+| Name | Description | Units | Instrument Type ([*](README.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` |
+| `hw.gpu.io` | Received and transmitted bytes by the GPU | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
+| `hw.gpu.memory.limit` | Size of the GPU memory | By | UpDownCounter | Int64 | | |
+| `hw.gpu.memory.utilization` | Fraction of GPU memory used | 1 | Gauge | Double | | |
+| `hw.gpu.memory.usage` | GPU memory used | By | UpDownCounter | Int64 | | |
+| `hw.gpu.power` | GPU instantaneous power consumption in Watts | W | Gauge | Double | | |
+| `hw.gpu.utilization` | Fraction of time spent in a specific task | 1 | Gauge | Double | `task` (Recommended) | `decoder`, `encoder`, `general` |
+| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` |
+| | | | | | `hw.type` (**Required**) | `gpu` |
Additional **Recommended** attributes:
@@ -261,20 +261,22 @@ Additional **Recommended** attributes:
### `hw.network.` - Network adapter metrics
**Description:** A physical network interface, or a network interface controller
-(NIC), excluding virtual adapters and loopbacks. Examples: an Ethernet adapter,
-an HBA, an fiber channel port or a Wi-Fi adapter.
-
-| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | -------------------------- | --------------------------- |
-| `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `type` (Recommended) | `all`, `zero_buffer_credit` |
-| | | | | | `hw.type` (**Required**) | `network` |
-| `hw.network.bandwidth.limit` | Link speed | By | UpDownCounter | Int64 | | |
-| `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | |
-| `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
-| `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
-| `hw.network.up` | Link status: `1` (up) or `0` (down) | | UpDownCounter | Int | | |
-| `hw.status` | Operational status, regardless of the link status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
-| | | | | | `hw.type` (**Required**) | `network` |
+(NIC), excluding software-based virtual adapters and loopbacks. For example, a
+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 |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | ----------------------------- | --------------------------------- |
+| `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` |
+| | | | | | `direction` (Recommended) | `receive`, `transmit` |
+| `hw.network.bandwidth.limit` | Link speed | By | UpDownCounter | Int64 | | |
+| `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | |
+| `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
+| `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` |
+| `hw.network.up` | Link status: `1` (up) or `0` (down) | | UpDownCounter | Int | | |
+| `hw.status` | Operational status, regardless of the link status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` |
+| | | | | | `hw.type` (**Required**) | `network` |
Additional **Recommended** attributes:
@@ -292,7 +294,8 @@ Additional **Recommended** attributes:
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| ---------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- |
-| `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.type` (**Required**) | `physical_disk` |
+| `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` |
| `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk | 1 | Gauge | Double | `state` (**Required**) | `remaining` |
| `hw.physical_disk.size` | Size of the disk | By | UpDownCounter | Int64 | | |
| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. |
@@ -336,7 +339,8 @@ virtual tape libraries)
| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values |
| -------------------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------------------------- |
-| `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.type` | `tape_drive` |
+| `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` |
| `hw.tape_drive.operations` | Operations performed by the tape drive | {operation} | Counter | Int64 | `type` (Recommended) | `mount`, `unmount`, `clean` |
| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `needs_cleaning` |
| | | | | | `hw.type` (**Required**) | `tape_drive` |
From b1207ff132f9ad8bc5e9621ddc8b6714fddbddbc Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Wed, 12 Apr 2023 11:14:21 -0700
Subject: [PATCH 34/36] Editorial: add attribute_group type to log.record
(#3374)
---
semantic_conventions/logs/general.yaml | 1 +
1 file changed, 1 insertion(+)
diff --git a/semantic_conventions/logs/general.yaml b/semantic_conventions/logs/general.yaml
index fc4af35678a..48da970c137 100644
--- a/semantic_conventions/logs/general.yaml
+++ b/semantic_conventions/logs/general.yaml
@@ -1,6 +1,7 @@
groups:
- id: log.record
prefix: log.record
+ type: attribute_group
brief: >
The attributes described in this section are rather generic. They may be used in any Log Record they apply to.
attributes:
From 9fc6984ff15fa42a4e4e36bb0ef3d1b933702cd5 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Wed, 12 Apr 2023 17:31:28 -0500
Subject: [PATCH 35/36] Lay initial groundwork for file configuration (#3360)
Initial followup to [OTEP
#225](https://github.com/open-telemetry/oteps/pull/225).
This lays the initial groundwork for file configuration in the
specification. There are placeholders TODOs for many various followup
tasks. Additional work is also needed to figure out how to merge [SDK
Configuration](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-configuration.md),
[SDK Environment
Variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md)
and file configuration into a cohesive story.
This PR proposes the configuration schema live in
`opentelemetry-specification/specification/configuration/schema/`, which
implies that at some point additional build steps will be needed to
confirm changes to the schema are valid and allowed.
cc @MrAlias, @codeboten
---
CHANGELOG.md | 3 +
.../configuration/file-configuration.md | 73 +++++++++++++++++++
.../schema/opentelemetry_configuration.json | 15 ++++
3 files changed, 91 insertions(+)
create mode 100644 specification/configuration/file-configuration.md
create mode 100644 specification/configuration/schema/opentelemetry_configuration.json
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4921c3137ad..336669d767e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,9 @@ release.
### SDK Configuration
+- Lay initial groundwork for file configuration
+ ([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360))
+
### Telemetry Schemas
### Common
diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md
new file mode 100644
index 00000000000..dbe949b2c7b
--- /dev/null
+++ b/specification/configuration/file-configuration.md
@@ -0,0 +1,73 @@
+# File Configuration
+
+**Status**: [Experimental](../document-status.md)
+
+
+
+- [Overview](#overview)
+- [Configuration Model](#configuration-model)
+ * [Stability Definition](#stability-definition)
+- [Configuration file](#configuration-file)
+- [SDK Configuration](#sdk-configuration)
+ * [In-Memory Configuration Model](#in-memory-configuration-model)
+ * [Operations](#operations)
+- [References](#references)
+
+
+
+## Overview
+
+File configuration provides a mechanism for configuring OpenTelemetry which is
+more expressive and full-featured than
+the [environment variable](../sdk-environment-variables.md) based scheme, and
+language agnostic in a way not possible
+with [programmatic configuration](../sdk-configuration.md#programmatic).
+
+File configuration defines a [Configuration Model](#configuration-model),
+which can be expressed in a [configuration file](#configuration-file).
+Configuration files can be validated against the Configuration Schema, and
+interpreted to produce configured OpenTelemetry components.
+
+## Configuration Model
+
+The configuration model is defined
+in [./schema/](./schema/opentelemetry_configuration.json) using
+the [JSON Schema](https://json-schema.org/).
+
+### Stability Definition
+
+TODO: define stability guarantees and backwards compatibility
+
+## Configuration file
+
+A configuration file is a file representation of
+the [Configuration Model](#configuration-model).
+
+TODO: define acceptable file formats
+
+TODO: define environment variable substitution
+
+## SDK Configuration
+
+SDK configuration defines the interfaces and operations that SDKs are expected
+to expose to enable file based configuration.
+
+### In-Memory Configuration Model
+
+SDKs SHOULD provide an in-memory representation of
+the [Configuration Model](#configuration-model). In general, SDKs are encouraged
+to provide this in-memory representation in a manner that is idiomatic for their
+language. If an SDK needs to expose a class or interface, the
+name `Configuration` is RECOMMENDED.
+
+### Operations
+
+TODO: define how to parse configuration file to configuration model
+
+TODO: define how to apply configuration model to produce configured sdk
+components
+
+## References
+
+* Configuration
+ proposal ([OTEP #225](https://github.com/open-telemetry/oteps/pull/225))
diff --git a/specification/configuration/schema/opentelemetry_configuration.json b/specification/configuration/schema/opentelemetry_configuration.json
new file mode 100644
index 00000000000..2dc9cb04f8a
--- /dev/null
+++ b/specification/configuration/schema/opentelemetry_configuration.json
@@ -0,0 +1,15 @@
+{
+ "$id": "https://opentelemetry.io/otelconfig/OpenTelemetryConfiguration",
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "OpenTelemetryConfiguration",
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "file_format": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "file_format"
+ ]
+}
From 25f513dbea2810be1c6f94d314d1a8d7e7b592c9 Mon Sep 17 00:00:00 2001
From: Tyler Yahn
Date: Wed, 12 Apr 2023 15:56:32 -0700
Subject: [PATCH 36/36] Add recommendation to use non-prefixed units for metric
instruments (#3312)
---
CHANGELOG.md | 2 ++
specification/metrics/semantic_conventions/README.md | 2 ++
2 files changed, 4 insertions(+)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 336669d767e..9b9e7bad2a4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,6 +56,8 @@ release.
- Clarify that units should use UCUM case sensitive variant.
([#3306](https://github.com/open-telemetry/opentelemetry-specification/pull/3306))
+- Recommended non-prefixed units for metric instrument semantic conventions.
+ ([#3312](https://github.com/open-telemetry/opentelemetry-specification/pull/3312))
- Remove No-Op instrument and Meter creation requirements.
([#3322](https://github.com/open-telemetry/opentelemetry-specification/pull/3322))
- Fixed attributes requirement level in semantic conventions for hardware metrics
diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md
index a7d5db37483..ccd9f9e612e 100644
--- a/specification/metrics/semantic_conventions/README.md
+++ b/specification/metrics/semantic_conventions/README.md
@@ -190,6 +190,8 @@ give additional meaning *without* the leading default unit (`1`). For example,
use `{packet}`, `{error}`, `{fault}`, etc.
- Instrument units 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.
### Instrument Types