From bcb052e03ed76eb9e3f28b10ee9bb76ab967a409 Mon Sep 17 00:00:00 2001 From: Guangya Liu Date: Thu, 16 Jan 2025 08:23:27 -0500 Subject: [PATCH 01/20] [chore] updated changelog for gen-ai (#1750) Signed-off-by: Guangya Liu --- .chloggen/1655.yaml | 2 +- .chloggen/1719.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.chloggen/1655.yaml b/.chloggen/1655.yaml index d15da0a393..d833884e93 100644 --- a/.chloggen/1655.yaml +++ b/.chloggen/1655.yaml @@ -7,7 +7,7 @@ change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: genai +component: gen-ai # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: | diff --git a/.chloggen/1719.yaml b/.chloggen/1719.yaml index efcabfa174..74ed83fd35 100644 --- a/.chloggen/1719.yaml +++ b/.chloggen/1719.yaml @@ -7,7 +7,7 @@ change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: genai +component: gen-ai # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: Adds `mistral_ai` as a `gen_ai.system` attribute value. From 539ce854bf8814c01e3e53d75453648cff0cdeed Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 16 Jan 2025 11:54:10 -0800 Subject: [PATCH 02/20] Add common guidance on recording errors on spans and metrics, clarify DB conventions (#1716) Co-authored-by: Trask Stalnaker --- .chloggen/1716.yaml | 4 + docs/attributes-registry/exception.md | 27 ++-- docs/cli/cli-spans.md | 3 +- docs/database/cassandra.md | 3 +- docs/database/cosmosdb.md | 3 +- docs/database/couchdb.md | 5 +- docs/database/database-spans.md | 58 +------- docs/database/elasticsearch.md | 3 +- docs/database/hbase.md | 2 +- docs/database/mariadb.md | 38 +----- docs/database/mongodb.md | 3 +- docs/database/mssql.md | 1 + docs/database/mysql.md | 38 +----- docs/database/postgresql.md | 36 +---- docs/database/redis.md | 3 +- docs/database/sql.md | 2 +- docs/exceptions/README.md | 2 - docs/exceptions/exceptions-spans.md | 46 +------ docs/faas/faas-spans.md | 2 + docs/gen-ai/gen-ai-spans.md | 6 + docs/general/recording-errors.md | 129 ++++++++++++++++++ docs/http/http-spans.md | 5 +- docs/messaging/messaging-spans.md | 6 + docs/rpc/rpc-spans.md | 6 + model/database/spans.yaml | 42 +++++- .../deprecated/registry-deprecated.yaml | 14 ++ model/exceptions/registry.yaml | 23 ---- 27 files changed, 240 insertions(+), 270 deletions(-) create mode 100644 .chloggen/1716.yaml create mode 100644 docs/general/recording-errors.md create mode 100644 model/exceptions/deprecated/registry-deprecated.yaml diff --git a/.chloggen/1716.yaml b/.chloggen/1716.yaml new file mode 100644 index 0000000000..1c16bf56d1 --- /dev/null +++ b/.chloggen/1716.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: docs, db +note: Add common guidance for recording errors on spans and metrics, clarify DB conventions. +issues: [1516, 1536, 1716] diff --git a/docs/attributes-registry/exception.md b/docs/attributes-registry/exception.md index be9b732e15..201dc3bd75 100644 --- a/docs/attributes-registry/exception.md +++ b/docs/attributes-registry/exception.md @@ -6,30 +6,23 @@ # Exception +- [Exception Attributes](#exception-attributes) +- [Deprecated Exception Attributes](#deprecated-exception-attributes) + ## Exception Attributes This document defines the shared attributes used to report a single exception associated with a span or log. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span, -if that span is ended while the exception is still logically "in flight". -This may be actually "in flight" in some languages (e.g. if the exception -is passed to a Context manager's `__exit__` method in Python) but will -usually be caught at the point of recording the exception in most languages. - -It is usually not possible to determine at the point where an exception is thrown -whether it will escape the scope of a span. -However, it is trivial to know that an exception -will escape, if one checks for an active exception just before ending the span, -as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). - -It follows that an exception may still escape the scope of the span -even if the `exception.escaped` attribute was not set or set to false, -since the event might have been recorded at a time where it was not -clear whether the exception will escape. +## Deprecated Exception Attributes + +Deprecated exception attributes. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `exception.escaped` | boolean | Indicates that the exception is escaping the scope of the span. | | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | diff --git a/docs/cli/cli-spans.md b/docs/cli/cli-spans.md index be7e2a61b8..0540a9641b 100644 --- a/docs/cli/cli-spans.md +++ b/docs/cli/cli-spans.md @@ -13,7 +13,8 @@ Span kind SHOULD be `INTERNAL` when the traced program is the callee or `CLIENT` The span name SHOULD be set to `{process.executable.name}`. Instrumentations that have additional context about executed commands MAY use a different low-cardinality span name format and SHOULD document it. -Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. +Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +additional details on how to record span status. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 7ec690b232..cf3d2b3b68 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -69,8 +69,7 @@ system specific term if more applicable. **[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. -**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[6] `db.response.status_code`:** All Cassandra protocol error codes SHOULD be considered errors. **[7] `db.response.status_code`:** If the operation failed and status code is available. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 810967a907..679e1fde6c 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -193,8 +193,7 @@ additional values when introducing new operations. **[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. -**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[6] `db.response.status_code`:** Response codes in the 4xx and 5xx range SHOULD be considered errors. **[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index b4eb826f75..873bd36565 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -23,7 +23,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB recorded as a string. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [7] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | @@ -31,8 +31,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o **[1] `db.operation.name`:** In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). -**[2] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[2] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. **[3] `db.response.status_code`:** If response was received and the HTTP response code is available. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index dcd4ec2202..5e1b17d4a5 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -12,7 +12,6 @@ linkTitle: Client Calls - [Name](#name) - [Status](#status) - - [Recording exception events](#recording-exception-events) - [Common attributes](#common-attributes) - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Sanitization of `db.query.text`](#sanitization-of-dbquerytext) @@ -89,59 +88,11 @@ For example, for an operation describing SQL query on an anonymous table like `S ## Status -[Span Status Code][SpanStatus] MUST be left unset if the operation has ended without any errors. +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. -Instrumentation SHOULD consider the operation as failed if any of the following is true: - -- the `db.response.status_code` value indicates an error - - > [!NOTE] - > - > The classification of status code as an error depends on the context. - > For example, a SQL STATE `02000` (`no_data`) indicates an error when the application - > expected the data to be available. However, it is not an error when the - > application is simply checking whether the data exists. - > - > Instrumentations that have additional context about a specific operation MAY use - > this context to set the span status more precisely. - > Instrumentations that don't have any additional context MUST follow the - > guidelines in this section. - -- an exception is thrown by the instrumented method call -- the instrumented method returns an error in another way - -When the operation ends with an error, instrumentation: - -- SHOULD set the span status code to `Error` -- SHOULD set the `error.type` attribute -- SHOULD set the span status description when it has additional information - about the error which is not expected to contain sensitive details and aligns - with [Span Status Description][SpanStatus] definition. - - It's NOT RECOMMENDED to duplicate `db.response.status_code` or `error.type` - in span status description. - - When the operation fails with an exception, the span status description SHOULD be set to - the exception message. - -### Recording exception events - -**Status**: [Experimental][DocumentStatus] - -When the operation fails with an exception, instrumentation SHOULD record -an [exception event](../exceptions/exceptions-spans.md) by default if, and only if, -the span being recorded is a local root span (does not have a local parent). - -> [!NOTE] -> -> Exception stack traces could be very long and are expensive to capture and store. -> Exceptions which are not handled by instrumented libraries are likely to be handled -> and logged by the caller. -> Exceptions that are not handled will be recorded by the outermost (local root) -> instrumentation such as HTTP or gRPC server. - -Instrumentation MAY provide a configuration option to record exceptions that -escape the surface of the instrumented API. +Semantic conventions for individual systems SHOULD specify which values of `db.response.status_code` +classify as errors. ## Common attributes @@ -466,4 +417,3 @@ More specific Semantic Conventions are defined for the following database techno * [SQL](sql.md): Semantic Conventions for *SQL* databases. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 175cf43fab..da64ed62fa 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -82,8 +82,7 @@ When a query string value is redacted, the query string key SHOULD still be pres **[4] `db.elasticsearch.path_parts`:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. -**[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[5] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. **[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 6e8e2b03b9..37d4d29163 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -24,7 +24,7 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Protocol-specific response code recorded as string. [4] | `200`; `409`; `14` | `Conditionally Required` If response was received. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Protocol-specific response code recorded as a string. [4] | `200`; `409`; `14` | `Conditionally Required` If response was received. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index 58285321b5..e34fc231da 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -42,41 +42,9 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database -return code which is adopted by some database systems like PostgreSQL. -See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html) -for the details. - -Other systems like MySQL, Oracle, or MS SQL Server define vendor-specific -error codes. Database SQL drivers usually provide access to both properties. -For example, in Java, the [`SQLException`](https://docs.oracle.com/javase/8/docs/api/java/sql/SQLException.html) -class reports them with `getSQLState()` and `getErrorCode()` methods. - -Instrumentations SHOULD populate the `db.response.status_code` with the -the most specific code available to them. - -Here's a non-exhaustive list of databases that report vendor-specific -codes with granularity higher than SQLSTATE (or don't report SQLSTATE -at all): - -- [DB2 SQL codes](https://www.ibm.com/docs/db2-for-zos/12?topic=codes-sql). -- [Maria DB error codes](https://mariadb.com/kb/en/mariadb-error-code-reference/) -- [Microsoft SQL Server errors](https://docs.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) -- [MySQL error codes](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) -- [Oracle error codes](https://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm) -- [SQLite result codes](https://www.sqlite.org/rescode.html) - -These systems SHOULD set the `db.response.status_code` to a -known vendor-specific error code. If only SQLSTATE is available, -it SHOULD be used. - -When multiple error codes are available and specificity is unclear, -instrumentation SHOULD set the `db.response.status_code` to the -concatenated string of all codes with '/' used as a separator. - -For example, generic DB instrumentation that detected an error and has -SQLSTATE `"42000"` and vendor-specific `1071` should set -`db.response.status_code` to `"42000/1071"`." +**[2] `db.response.status_code`:** MariaDB uses vendor-specific error codes on all errors and reports [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) in some cases. +MariaDB error codes are more granular than SQLSTATE, so MariaDB instrumentations SHOULD set the `db.response.status_code` to this known error code. +When SQLSTATE is available, SQLSTATE of "Class 02" or higher SHOULD be considered errors. When SQLSTATE is not available, all MariaDB error codes SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 26f33c9afb..0c8dbe46ba 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -40,8 +40,7 @@ then that collection name SHOULD be used. **[2] `db.operation.name`:** See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/). -**[3] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[3] `db.response.status_code`:** All MongoDB error codes SHOULD be considered errors. **[4] `db.response.status_code`:** If the operation failed and error code is available. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index e6147cae1d..5b30b833fb 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -47,6 +47,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[2] `db.response.status_code`:** Microsoft SQL Server does not report SQLSTATE. +Instrumentations SHOULD use [error severity](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-error-severities) returned along with the status code to determine the status of the span. Response codes with severity 11 or higher SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 99bb820e83..19b42520c0 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -22,7 +22,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) recorded as a string. [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | @@ -42,41 +42,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database -return code which is adopted by some database systems like PostgreSQL. -See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html) -for the details. - -Other systems like MySQL, Oracle, or MS SQL Server define vendor-specific -error codes. Database SQL drivers usually provide access to both properties. -For example, in Java, the [`SQLException`](https://docs.oracle.com/javase/8/docs/api/java/sql/SQLException.html) -class reports them with `getSQLState()` and `getErrorCode()` methods. - -Instrumentations SHOULD populate the `db.response.status_code` with the -the most specific code available to them. - -Here's a non-exhaustive list of databases that report vendor-specific -codes with granularity higher than SQLSTATE (or don't report SQLSTATE -at all): - -- [DB2 SQL codes](https://www.ibm.com/docs/db2-for-zos/12?topic=codes-sql). -- [Maria DB error codes](https://mariadb.com/kb/en/mariadb-error-code-reference/) -- [Microsoft SQL Server errors](https://docs.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) -- [MySQL error codes](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) -- [Oracle error codes](https://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm) -- [SQLite result codes](https://www.sqlite.org/rescode.html) - -These systems SHOULD set the `db.response.status_code` to a -known vendor-specific error code. If only SQLSTATE is available, -it SHOULD be used. - -When multiple error codes are available and specificity is unclear, -instrumentation SHOULD set the `db.response.status_code` to the -concatenated string of all codes with '/' used as a separator. - -For example, generic DB instrumentation that detected an error and has -SQLSTATE `"42000"` and vendor-specific `1071` should set -`db.response.status_code` to `"42000/1071"`." +**[2] `db.response.status_code`:** MySQL error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All MySQL error codes SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 545af7ae55..27c269ea39 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -49,41 +49,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the user provided whe It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database -return code which is adopted by some database systems like PostgreSQL. -See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html) -for the details. - -Other systems like MySQL, Oracle, or MS SQL Server define vendor-specific -error codes. Database SQL drivers usually provide access to both properties. -For example, in Java, the [`SQLException`](https://docs.oracle.com/javase/8/docs/api/java/sql/SQLException.html) -class reports them with `getSQLState()` and `getErrorCode()` methods. - -Instrumentations SHOULD populate the `db.response.status_code` with the -the most specific code available to them. - -Here's a non-exhaustive list of databases that report vendor-specific -codes with granularity higher than SQLSTATE (or don't report SQLSTATE -at all): - -- [DB2 SQL codes](https://www.ibm.com/docs/db2-for-zos/12?topic=codes-sql). -- [Maria DB error codes](https://mariadb.com/kb/en/mariadb-error-code-reference/) -- [Microsoft SQL Server errors](https://docs.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) -- [MySQL error codes](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) -- [Oracle error codes](https://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm) -- [SQLite result codes](https://www.sqlite.org/rescode.html) - -These systems SHOULD set the `db.response.status_code` to a -known vendor-specific error code. If only SQLSTATE is available, -it SHOULD be used. - -When multiple error codes are available and specificity is unclear, -instrumentation SHOULD set the `db.response.status_code` to the -concatenated string of all codes with '/' used as a separator. - -For example, generic DB instrumentation that detected an error and has -SQLSTATE `"42000"` and vendor-specific `1071` should set -`db.response.status_code` to `"42000/1071"`." +**[2] `db.response.status_code`:** PostgreSQL follows SQL standard conventions for [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE). Response codes of "Class 02" or higher SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/redis.md b/docs/database/redis.md index cd826850ff..8ef933e7a4 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -60,8 +60,7 @@ system specific term if more applicable. **[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. -**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[4] `db.response.status_code`:** All Redis error prefixes SHOULD be considered errors. **[5] `db.response.status_code`:** If the operation failed and status code is available. diff --git a/docs/database/sql.md b/docs/database/sql.md index a66b348723..b935d68ee7 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -46,7 +46,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, fully qualified within the server address and port. [1] | `customers`; `test.users` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as string. [2] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as a string. [2] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index bee2851df8..6c1c976e10 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -9,8 +9,6 @@ path_base_for_github_subdir: **Status**: [Stable][DocumentStatus] -This document defines semantic conventions for Exceptions. - Semantic conventions for Exceptions are defined for the following signals: * [Exceptions on spans](exceptions-spans.md): Semantic Conventions for Exceptions associated with *spans*. diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index afcb5a50c3..96ca6f49cd 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -11,33 +11,6 @@ exceptions associated with spans. -- [Recording an Exception](#recording-an-exception) -- [Exception event](#exception-event) - - [Stacktrace Representation](#stacktrace-representation) - - - -## Recording an Exception - -An exception SHOULD be recorded as an `Event` on the span during which it occurred. -The name of the event MUST be `"exception"`. - -A typical template for an auto-instrumentation implementing this semantic convention -using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#record-exception) -could look like this (pseudo-Java): - -```java -Span span = myTracer.startSpan(/*...*/); -try { - // Code that does the actual work which the Span represents -} catch (Throwable e) { - span.recordException(e, Attributes.of("exception.escaped", true)); - throw e; -} finally { - span.end(); -} -``` - ## Exception event @@ -57,30 +30,13 @@ This event describes a single exception. |---|---|---|---|---|---| | [`exception.message`](/docs/attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`exception.type`](/docs/attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`exception.escaped`](/docs/attributes-registry/exception.md) | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [3] | | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.escaped`](/docs/attributes-registry/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. | | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | | [`exception.stacktrace`](/docs/attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. **[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. -**[3] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span, -if that span is ended while the exception is still logically "in flight". -This may be actually "in flight" in some languages (e.g. if the exception -is passed to a Context manager's `__exit__` method in Python) but will -usually be caught at the point of recording the exception in most languages. - -It is usually not possible to determine at the point where an exception is thrown -whether it will escape the scope of a span. -However, it is trivial to know that an exception -will escape, if one checks for an active exception just before ending the span, -as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). - -It follows that an exception may still escape the scope of the span -even if the `exception.escaped` attribute was not set or set to false, -since the event might have been recorded at a time where it was not -clear whether the exception will escape. - diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index b49ee5766c..89b01428ba 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -36,6 +36,8 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. + If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index 99cfb96f8b..54ebc54f37 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -11,6 +11,7 @@ linkTitle: Generative AI traces - [Name](#name) + - [Status](#status) - [GenAI attributes](#genai-attributes) - [Capturing inputs and outputs](#capturing-inputs-and-outputs) @@ -30,6 +31,11 @@ GenAI spans MUST follow the overall [guidelines for span names](https://github.c The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. +### Status + +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. + ## GenAI attributes These attributes track input data and metadata for a request to a GenAI model. Each attribute represents a concept that is common to most Generative AI clients. diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md new file mode 100644 index 0000000000..b6ed152711 --- /dev/null +++ b/docs/general/recording-errors.md @@ -0,0 +1,129 @@ + + +# Recording errors + +**Status**: [Development][DocumentStatus]. + + + +- [What constitutes an error](#what-constitutes-an-error) +- [Recording errors on spans](#recording-errors-on-spans) +- [Recording errors on metrics](#recording-errors-on-metrics) +- [Recording exceptions](#recording-exceptions) + + + +This document provides recommendations to semantic convention and instrumentation authors +on how to record errors on spans and metrics. + +Individual semantic conventions are encouraged to provide additional guidance. + +## What constitutes an error + +An operation SHOULD be considered as failed if any of the following is true: + +- an exception is thrown by the instrumented method (API, block of code, or another instrumented unit) +- the instrumented method returns an error in another way, for example, via an error code + + Semantic conventions that define domain-specific status codes SHOULD specify + which status codes should be reported as errors by a general-purpose instrumentation. + +> [!NOTE] +> +> The classification of a status code as an error depends on the context. +> For example, an HTTP 404 "Not Found" status code indicates an error if the application +> expected the resource to be available. However, it is not an error when the +> application is simply checking whether the resource exists. +> +> Instrumentations that have additional context about a specific request MAY use +> this context to set the span status more precisely. + +Errors that were retried or handled (allowing an operation to complete gracefully) SHOULD NOT +be recorded on spans or metrics that describe this operation. + +## Recording errors on spans + +[Span Status Code][SpanStatus] MUST be left unset if the instrumented operation has +ended without any errors. + +When the operation ends with an error, instrumentation: + +- SHOULD set the span status code to `Error` +- SHOULD set the [`error.type`](/docs/attributes-registry/error.md#error-type) attribute +- SHOULD set the span status description when it has additional information + about the error which is not expected to contain sensitive details and aligns + with [Span Status Description][SpanStatus] definition. + + It's NOT RECOMMENDED to duplicate status code or `error.type` in span status description. + + When the operation fails with an exception, the span status description SHOULD be set to + the exception message. + +Refer to the [recording exceptions](#recording-errors) on capturing exception +details. + +## Recording errors on metrics + +Semantic conventions for operations usually define an operation duration histogram +metric. This metric SHOULD include the `error.type` attribute. This enables users to derive +throughput and error rates. + +Operations that complete successfully SHOULD NOT include the `error.type` attribute, +allowing users to filter out errors. + +Semantic conventions SHOULD include `error.type` on other metrics when it's applicable. +For example, `messaging.client.sent.messages` metric measures message throughput (one +messaging operation may involve sending multiple messages) and includes `error.type`. + +It's RECOMMENDED to report one metric that includes successes and failures as opposed +to reporting two (or more) metrics depending on the operation status. + +Instrumentation SHOULD ensure `error.type` is applied consistently across spans +and metrics when both are reported. A span and its corresponding metric for a single +operation SHOULD have the same `error.type` value if the operation failed and SHOULD NOT +include it if the operation succeeded. + +## Recording exceptions + +When an instrumented operation fails with an exception, instrumentation SHOULD record +this exception as a [span event](/docs/exceptions/exceptions-spans.md) or a [log record](/docs/exceptions/exceptions-logs.md). + +It's RECOMMENDED to use the `Span.recordException` API or logging library API that takes exception instance +instead of providing individual attributes. This enables the OpenTelemetry SDK to +control what information is recorded based on application configuration. + +It's NOT RECOMMENDED to record the same exception more than once. +It's NOT RECOMMENDED to record exceptions that are handled by the instrumented library. + +For example, in this code-snippet, `ResourceAlreadyExistsException` is handled and the corresponding +native instrumentation should not record it. Exceptions which are propagated +to the caller should be recorded (or logged) once. + +```java +public boolean createIfNotExists(String resourceId) throws IOException { + Span span = startSpan(); + try { + create(resourceId); + return true; + } catch (ResourceAlreadyExistsException e) { + // not recording exception and not setting span status to error - exception is handled + // but we can set attributes that capture additional details + span.setAttribute(AttributeKey.stringKey("acme.resource.create.status"), "already_exists"); + return false; + } catch (IOException e) { + // recording exception here (assuming it was not recorded inside `create` method) + span.recordException(e); + // or + // logger.warn(e); + + span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName()) + span.setStatus(StatusCode.ERROR, e.getMessage()); + throw e; + } +} +``` + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 6d54263fcd..2ac016a237 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -91,7 +91,7 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. -> **Note:** +> [!NOTE] > > The classification of an HTTP status code as an error depends on the context. > For example, a 404 "Not Found" status code indicates an error if the application @@ -117,6 +117,9 @@ the client or server from sending/receiving the request/response fully. When instrumentation detects such errors it SHOULD set span status to `Error` and SHOULD set the `error.type` attribute. +**Status**: [Development][DocumentStatus] - Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +general considerations on how to record span status. + ## HTTP client This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 0d13af08bd..02cbbc2691 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -22,6 +22,7 @@ - [Span name](#span-name) - [Operation types](#operation-types) - [Span kind](#span-kind) + - [Span status](#span-status) - [Trace structure](#trace-structure) - [Producer spans](#producer-spans) - [Consumer spans](#consumer-spans) @@ -247,6 +248,11 @@ Span kind SHOULD be set according to the following table, based on the operation Setting span kinds according to this table allows analysis tools to interpret spans and relationships between them without the need for additional semantic hints. +### Span status + +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. + ### Trace structure #### Producer spans diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 9401826e9b..d73492be49 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -15,6 +15,7 @@ This document defines how to describe remote procedure calls - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - [Span name](#span-name) + - [Span status](#span-status) - [Service name](#service-name) - [Client attributes](#client-attributes) - [Server attributes](#server-attributes) @@ -79,6 +80,11 @@ Examples of span names: `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls - `MyServiceWithNoPackage/theMethod` +### Span status + +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. + ### Service name On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 476127d09c..b03a9cf9a1 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -148,6 +148,9 @@ groups: represented as a string. note: > Microsoft SQL Server does not report SQLSTATE. + + Instrumentations SHOULD use [error severity](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-error-severities) + returned along with the status code to determine the status of the span. Response codes with severity 11 or higher SHOULD be considered errors. examples: ["102", "40020"] - id: span.db.postgresql.client @@ -183,8 +186,10 @@ groups: - ref: db.response.status_code brief: > [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). + note: > + PostgreSQL follows SQL standard conventions for [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE). + Response codes of "Class 02" or higher SHOULD be considered errors. examples: ["08000", "08P01"] - - id: span.db.mysql.client type: span stability: experimental @@ -209,7 +214,10 @@ groups: examples: ["products", "customers"] - ref: db.response.status_code brief: > - [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). + [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) recorded as a string. + note: > + MySQL error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) + conventions. All MySQL error codes SHOULD be considered errors. examples: ["1005", "MY-010016"] - id: span.db.mariadb.client @@ -238,8 +246,18 @@ groups: brief: > [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/) represented as a string. - examples: ["1008", "3058"] + note: > + MariaDB uses vendor-specific error codes on all errors and reports + [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) in some cases. + + MariaDB error codes are more granular than SQLSTATE, so MariaDB instrumentations + SHOULD set the `db.response.status_code` to this known error code. + + When SQLSTATE is available, SQLSTATE of "Class 02" or higher SHOULD be + considered errors. When SQLSTATE is not available, all MariaDB error + codes SHOULD be considered errors. + examples: ["1008", "3058"] - id: span.db.cassandra.client type: span span_kind: client @@ -274,6 +292,8 @@ groups: - ref: db.response.status_code brief: > [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. + note: > + All Cassandra protocol error codes SHOULD be considered errors. examples: ["102", "40020"] - id: span.db.hbase.client type: span @@ -302,7 +322,7 @@ groups: conditionally_required: If readily available. - ref: db.response.status_code brief: > - Protocol-specific response code recorded as string. + Protocol-specific response code recorded as a string. examples: ["200", "409", "14"] requirement_level: conditionally_required: If response was received. @@ -334,7 +354,9 @@ groups: note: "" # overriding the base note - ref: db.response.status_code brief: > - The HTTP response code returned by the Couch DB. + The HTTP response code returned by the Couch DB recorded as a string. + note: > + HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. examples: ["200", "201", "429"] requirement_level: conditionally_required: If response was received and the HTTP response code is available. @@ -395,6 +417,8 @@ groups: brief: > The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. examples: ["ERR", "WRONGTYPE", "CLUSTERDOWN"] + note: > + All Redis error prefixes SHOULD be considered errors. - ref: db.operation.batch.size - ref: db.operation.parameter requirement_level: opt_in @@ -434,6 +458,8 @@ groups: - ref: db.response.status_code brief: > [MongoDB error code](https://www.mongodb.com/docs/manual/reference/error-codes/) represented as a string. + note: > + All MongoDB error codes SHOULD be considered errors. requirement_level: conditionally_required: If the operation failed and error code is available. examples: ["36", "11602"] @@ -492,6 +518,8 @@ groups: brief: > The HTTP response code returned by the Elasticsearch cluster. examples: ["200", "201", "429"] + note: > + HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. requirement_level: conditionally_required: If response was received. - id: span.db.sql.client @@ -528,7 +556,7 @@ groups: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - ref: db.response.status_code brief: > - Database response code recorded as string. + Database response code recorded as a string. note: | SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database return code which is adopted by some database systems like PostgreSQL. @@ -607,6 +635,8 @@ groups: brief: > Cosmos DB status code. examples: ["200", "201"] + note: > + Response codes in the 4xx and 5xx range SHOULD be considered errors. requirement_level: conditionally_required: if response was received - ref: db.response.returned_rows diff --git a/model/exceptions/deprecated/registry-deprecated.yaml b/model/exceptions/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..ed9e57ac93 --- /dev/null +++ b/model/exceptions/deprecated/registry-deprecated.yaml @@ -0,0 +1,14 @@ +groups: + - id: registry.exception.deprecated + type: attribute_group + display_name: Deprecated Exception Attributes + brief: > + Deprecated exception attributes. + attributes: + - id: exception.escaped + type: boolean + stability: stable + deprecated: "It's no longer recommended to record exceptions that are handled + and do not escape the scope of a span." + brief: > + Indicates that the exception is escaping the scope of the span. diff --git a/model/exceptions/registry.yaml b/model/exceptions/registry.yaml index 1ebc90d854..7231a394de 100644 --- a/model/exceptions/registry.yaml +++ b/model/exceptions/registry.yaml @@ -31,26 +31,3 @@ groups: at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5) - - id: exception.escaped - type: boolean - stability: stable - brief: > - SHOULD be set to true if the exception event is recorded at a point where - it is known that the exception is escaping the scope of the span. - note: |- - An exception is considered to have escaped (or left) the scope of a span, - if that span is ended while the exception is still logically "in flight". - This may be actually "in flight" in some languages (e.g. if the exception - is passed to a Context manager's `__exit__` method in Python) but will - usually be caught at the point of recording the exception in most languages. - - It is usually not possible to determine at the point where an exception is thrown - whether it will escape the scope of a span. - However, it is trivial to know that an exception - will escape, if one checks for an active exception just before ending the span, - as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). - - It follows that an exception may still escape the scope of the span - even if the `exception.escaped` attribute was not set or set to false, - since the event might have been recorded at a time where it was not - clear whether the exception will escape. From 4a395177b4927b84d4c6de95bf708929a584acf2 Mon Sep 17 00:00:00 2001 From: Guangya Liu Date: Fri, 17 Jan 2025 10:34:57 -0500 Subject: [PATCH 03/20] [chore] Added content for update toc (#1754) Signed-off-by: Guangya Liu --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 111d35baa9..68755d1cf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,6 +32,7 @@ requirements and recommendations. - [Auto formatting](#auto-formatting) - [Markdown style](#markdown-style) - [Misspell check](#misspell-check) + - [Update the tables of content](#update-the-tables-of-content) - [Markdown link check](#markdown-link-check) - [Updating the referenced specification version](#updating-the-referenced-specification-version) - [Making a Release](#making-a-release) @@ -343,6 +344,7 @@ You can also run these fixes individually. See: - [Misspell Correction](#misspell-check) +- [Update the tables of content](#update-the-tables-of-content) - [Update the markdown files](#2-update-the-markdown-files) ### Markdown style @@ -389,6 +391,14 @@ To quickly fix typos, use make misspell-correction ``` +### Update the tables of content + +To update the tables of content, run: + +```bash +make markdown-toc +``` + ### Markdown link check To check the validity of links in all markdown files, run the following command: From 4ede34198ecafa26fc84141c716c50283218772a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 17 Jan 2025 10:54:38 -0500 Subject: [PATCH 04/20] [editorial] Adjust link into in-toto attestation spec (#1753) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/attributes-registry/artifact.md | 2 +- model/artifact/registry.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/artifact.md b/docs/attributes-registry/artifact.md index 4006920b1c..0258573481 100644 --- a/docs/attributes-registry/artifact.md +++ b/docs/attributes-registry/artifact.md @@ -13,7 +13,7 @@ This group describes attributes specific to artifacts. Artifacts are files or ot | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `artifact.attestation.filename` | string | The provenance filename of the built attestation which directly relates to the build artifact filename. This filename SHOULD accompany the artifact at publish time. See the [SLSA Relationship](https://slsa.dev/spec/v1.0/distributing-provenance#relationship-between-artifacts-and-attestations) specification for more information. | `golang-binary-amd64-v0.1.0.attestation`; `docker-image-amd64-v0.1.0.intoto.json1`; `release-1.tar.gz.attestation`; `file-name-package.tar.gz.intoto.json1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `artifact.attestation.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the software attestation space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.attestation.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the [software attestation space](https://github.com/in-toto/attestation/tree/main/spec) also refer to this as the **digest**. | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `artifact.attestation.id` | string | The id of the build [software attestation](https://slsa.dev/attestation-model). | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `artifact.filename` | string | The human readable file name of the artifact, typically generated during build and release processes. Often includes the package name and version in the file name. [1] | `golang-binary-amd64-v0.1.0`; `docker-image-amd64-v0.1.0`; `release-1.tar.gz`; `file-name-package.tar.gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `artifact.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), often found in checksum.txt on a release of the artifact and used to verify package integrity. [2] | `9ff4c52759e2c4ac70b7d517bc7fcdc1cda631ca0045271ddd1b192544f8a3e9` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/artifact/registry.yaml b/model/artifact/registry.yaml index 4f6dd98419..7887d9775e 100644 --- a/model/artifact/registry.yaml +++ b/model/artifact/registry.yaml @@ -91,7 +91,7 @@ groups: stability: experimental brief: > The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), - of the built attestation. Some envelopes in the software attestation - space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). + of the built attestation. Some envelopes in the [software attestation + space](https://github.com/in-toto/attestation/tree/main/spec) also refer to this as the **digest**. examples: ["1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408"] From 3ea010382421807ddef2ea62cccf3e5dd4673262 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 17 Jan 2025 14:38:55 -0500 Subject: [PATCH 05/20] [editorial] Fix invalid link syntax in `system/hardware-metrics` (#1759) --- docs/system/hardware-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index fb5496deb7..6494ec696c 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -11,7 +11,7 @@ metrics in OpenTelemetry. Consider the [general metric semantic conventions](/do when creating instruments not explicitly defined in the specification. This document is being converted to specific hardware metrics, parts of this document that have already been -converted are now located in the [Hardware] (/docs/hardware/README.md) folder and are no longer present in this file. +converted are now located in the [Hardware](/docs/hardware/README.md) folder and are no longer present in this file. Please note that this is an [ongoing process](https://github.com/open-telemetry/semantic-conventions/issues/1309) and may take some time to complete. From 44fc8fa2f14526dfd54cffe3956bbbd678b39607 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 17 Jan 2025 15:51:42 -0800 Subject: [PATCH 06/20] Update specification version to 1.40.0 (#1763) --- README.md | 2 +- docs/database/cosmosdb.md | 2 +- docs/database/database-metrics.md | 4 ++-- docs/database/database-spans.md | 2 +- docs/dns/dns-metrics.md | 2 +- docs/dotnet/dotnet-aspnetcore-metrics.md | 4 ++-- docs/dotnet/dotnet-dns-metrics.md | 2 +- docs/dotnet/dotnet-http-metrics.md | 4 ++-- docs/dotnet/dotnet-kestrel-metrics.md | 4 ++-- docs/dotnet/dotnet-signalr-metrics.md | 2 +- docs/exceptions/exceptions-logs.md | 8 ++++---- docs/faas/aws-lambda.md | 4 ++-- docs/faas/faas-metrics.md | 6 +++--- docs/feature-flags/feature-flags-logs.md | 8 ++++---- docs/gen-ai/gen-ai-metrics.md | 2 +- docs/gen-ai/gen-ai-spans.md | 2 +- docs/general/events.md | 6 +++--- docs/general/logs.md | 4 ++-- docs/general/metrics.md | 4 ++-- docs/general/recording-errors.md | 2 +- docs/general/trace.md | 2 +- docs/http/http-metrics.md | 6 +++--- docs/http/http-spans.md | 6 +++--- docs/messaging/messaging-metrics.md | 4 ++-- docs/messaging/messaging-spans.md | 2 +- docs/resource/README.md | 6 +++--- docs/resource/cloudfoundry.md | 2 +- docs/rpc/connect-rpc.md | 2 +- docs/rpc/grpc.md | 4 ++-- docs/runtime/jvm-metrics.md | 2 +- docs/runtime/nodejs-metrics.md | 2 +- docs/runtime/v8js-metrics.md | 4 ++-- internal/tools/update_specification_version.sh | 6 +++--- 33 files changed, 61 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index ddba49fe5f..26d9ed7fdc 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Checks](https://github.com/open-telemetry/semantic-conventions/workflows/Checks/badge.svg?branch=main)](https://github.com/open-telemetry/semantic-conventions/actions?query=workflow%3A%22Checks%22+branch%3Amain) [![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/open-telemetry/semantic-conventions.svg?logo=opentelemetry&&color=f5a800&label=Latest%20release)](https://github.com/open-telemetry/semantic-conventions/releases/latest) -[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.39.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.39.0) +[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.40.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.40.0) Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 679e1fde6c..537f4ef778 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -316,7 +316,7 @@ This metric is [required][MetricRequired]. It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of throughput control within the Azure Cosmos DB database, monitoring their usage is crucial to avoid throttling. this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 1, 5, 10, 25, 50, 100, 250, 500, 1000]`. Explaining bucket configuration: diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 47412d1ac3..b966d52465 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -65,7 +65,7 @@ This metric is [required][MetricRequired]. When this metric is reported alongside a database operation span, the metric value SHOULD be the same as the database operation span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. @@ -232,7 +232,7 @@ The following metric instruments describe database query response. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000]`. Explaining bucket configuration: diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 5e1b17d4a5..1f6dffa233 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -58,7 +58,7 @@ with all retries. ## Name -Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). The **span name** SHOULD be `{db.query.summary}` if a summary is available. diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md index 9cdec3122d..63c8dec891 100644 --- a/docs/dns/dns-metrics.md +++ b/docs/dns/dns-metrics.md @@ -24,7 +24,7 @@ This document defines semantic conventions to apply when instrumenting DNS queri This metric is optional. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 76f65aa849..e34a449933 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -172,7 +172,7 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting ### Metric: `aspnetcore.rate_limiting.request_lease.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -228,7 +228,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ### Metric: `aspnetcore.rate_limiting.request.time_in_queue` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 43137549c8..638c6c728e 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -20,7 +20,7 @@ This article defines semantic conventions for DNS metrics emitted by .NET. ### Metric: `dns.lookup.duration` This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index fd1f9c99fa..6d0bd2f238 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -77,7 +77,7 @@ Notes: ### Metric: `http.client.connection.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. @@ -106,7 +106,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. ### Metric: `http.client.request.time_in_queue` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 5bbb8d5d34..51c32f64bf 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -93,7 +93,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ## Metric: `kestrel.connection.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. @@ -474,7 +474,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ## Metric: `kestrel.tls_handshake.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index e4b0d24cdd..5f3b0632f4 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -18,7 +18,7 @@ This article defines semantic conventions for SignalR metrics emitted by .NET co ## Metric: `signalr.server.connection.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index b709aaf9d0..136a761e61 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -7,8 +7,8 @@ linkTitle: Logs **Status**: [Stable][DocumentStatus] This document defines semantic conventions for recording exceptions on -[logs](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md#emit-an-event) -emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger). +[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-an-event) +emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#logger). @@ -21,7 +21,7 @@ emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry ## Recording an Exception Exceptions SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#logger) emit operations. Exceptions MAY be recorded on "logs" or "events" depending on the context. @@ -33,7 +33,7 @@ the language runtime. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index c61a9a7f2f..9b1ce60960 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -163,7 +163,7 @@ be ` process`. If there are multiple sources in the batch, the nam For every message in the event, the [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/context/api-propagators.md) and added as a link to the span. This means the span may have as many links as messages in the batch. See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. @@ -176,7 +176,7 @@ See [compatibility](../non-normative/compatibility/aws.md#context-propagation) f For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span corresponding to the SQS event. The [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/context/api-propagators.md) and added as a link to the span. See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 32920096f0..bce085ebdb 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -46,7 +46,7 @@ The following metrics are recorded by the FaaS instance. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -86,7 +86,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -306,7 +306,7 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 1f601e9e71..12940ea8fe 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -7,8 +7,8 @@ linkTitle: Logs **Status**: [Experimental][DocumentStatus] This document defines semantic conventions for recording feature flag evaluations as -a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the -[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#emit-a-logrecord). +a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the +[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/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. @@ -32,14 +32,14 @@ This can be used to determine the impact a feature has on a request, enabling en ## Recording an Evaluation Feature flag evaluations SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#logger) emit operations. Evaluations MAY be recorded on "logs" or "events" depending on the context. ## Evaluation event The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 8efa2376e7..443a16e7f3 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -501,4 +501,4 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRequired]: /docs/general/metric-requirement-level.md#required [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended -[ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters +[ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index 54ebc54f37..df77481ecb 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -27,7 +27,7 @@ instrumented protocol such as HTTP. ## Name -GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. diff --git a/docs/general/events.md b/docs/general/events.md index 4e80862f13..15f0cf5207 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -15,7 +15,7 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t Examples of Events might include things like uncaught exceptions, button clicks, user logout, network connection severed, etc. -In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md) that conforms to the conventions included here. +In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md) that conforms to the conventions included here. In addition to a required name, an Event may contain a _payload_ (body) of any type permitted by the [LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body). @@ -32,7 +32,7 @@ structure and semantics will also be defined. * An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md). -* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) +* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the named event. @@ -47,7 +47,7 @@ structure and semantics will also be defined. Recommendations for defining events: * Use the _payload_ (body) to represent the details of the event instead of a - collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) + collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-an-event) diff --git a/docs/general/logs.md b/docs/general/logs.md index 030396b0d5..17bd676bbd 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -28,7 +28,7 @@ The following semantic conventions for logs are defined: * [Feature Flags](/docs/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. Apart from semantic conventions for logs, [events](events.md), [traces](trace.md), and [metrics](metrics.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General log identification attributes @@ -61,7 +61,7 @@ The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID This section describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log. -**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) as `an immutable representation of the entity producing telemetry`. +**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) as `an immutable representation of the entity producing telemetry`. The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission. As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes. diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 961abaedf4..63a24f3179 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -36,7 +36,7 @@ The following semantic conventions surrounding metrics are defined: * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also -defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with +defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General Guidelines @@ -87,7 +87,7 @@ usable. When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the -[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/compatibility/prometheus_and_openmetrics.md). +[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/compatibility/prometheus_and_openmetrics.md). ### Instrument Units diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md index b6ed152711..91246b7247 100644 --- a/docs/general/recording-errors.md +++ b/docs/general/recording-errors.md @@ -126,4 +126,4 @@ public boolean createIfNotExists(String resourceId) throws IOException { ``` [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status +[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#set-status diff --git a/docs/general/trace.md b/docs/general/trace.md index 591e306ad1..a83586d535 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -33,7 +33,7 @@ The following semantic conventions for spans are defined: * [RPC/RMI](/docs/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans. Apart from semantic conventions for traces, [metrics](metrics.md), [logs](logs.md), and [events](events.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 60c9b9f09e..6b7de43d56 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -64,7 +64,7 @@ This metric is required. When this metric is reported alongside an HTTP server span, the metric value SHOULD be the same as the HTTP server span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -511,7 +511,7 @@ This metric is required. When this metric is reported alongside an HTTP client span, the metric value SHOULD be the same as the HTTP client span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -864,7 +864,7 @@ This metric is optional. ### Metric: `http.client.connection.duration` This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. This metric is optional. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 2ac016a237..7b70586d03 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -64,7 +64,7 @@ and various HTTP versions like 1.1, 2 and SPDY. ## Name -HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). HTTP span names SHOULD be `{method} {target}` if there is a (low-cardinality) `target` available. If there is no (low-cardinality) `{target}` available, HTTP span names SHOULD be `{method}`. @@ -86,7 +86,7 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. ## Status -[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the +[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the 1xx, 2xx or 3xx ranges, unless there was another error (e.g., network error receiving the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. @@ -746,4 +746,4 @@ Span name: `POST /uploads/:document_id`. | `error.type` | `WebSocketDisconnect` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/sdk.md#span-processor +[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/sdk.md#span-processor diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index 87e6ff8467..3a2226e0cd 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -53,7 +53,7 @@ When this metric is reported alongside a messaging span, the metric value SHOULD This metric is [required][MetricRequired]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -367,7 +367,7 @@ When this metric is reported alongside a messaging process span, the metric valu This metric is [required][MetricRequired] for push-based message delivery and is [recommended][MetricRecommended] for processing operations instrumented for pull-based scenarios. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 02cbbc2691..182e363874 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -188,7 +188,7 @@ in such a way that it cannot be changed by intermediaries. ### Span name -Messaging spans SHOULD follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +Messaging spans SHOULD follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). diff --git a/docs/resource/README.md b/docs/resource/README.md index b687ade923..7bd51bed02 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -9,7 +9,7 @@ path_base_for_github_subdir: **Status**: [Mixed][DocumentStatus] -This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/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 +This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/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). @@ -58,14 +58,14 @@ Given their significance some resource attributes are treated specifically as de ### Semantic Attributes with Dedicated Environment Variable These are the attributes which MAY be configurable via a dedicated environment variable -as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/configuration/sdk-environment-variables.md): +as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/configuration/sdk-environment-variables.md): - [`service.name`](#service) ### Semantic Attributes with SDK-provided Default Value These are the attributes which MUST be provided by the SDK -as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md#sdk-provided-resource-attributes): +as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md#sdk-provided-resource-attributes): - [`service.name`](#service) - [`telemetry.sdk` group](#telemetry-sdk) diff --git a/docs/resource/cloudfoundry.md b/docs/resource/cloudfoundry.md index 7149437f8f..d2876e1c58 100644 --- a/docs/resource/cloudfoundry.md +++ b/docs/resource/cloudfoundry.md @@ -201,4 +201,4 @@ should be used. The `system.instance.id` should be set to `spec.id`. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/document-status.md diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 57e1f3bd0c..03f7ae4658 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -65,6 +65,6 @@ Below is a table of attributes that SHOULD be included on client and server Conn ## Connect RPC Status -If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. +If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 11fbc5807f..bc1dd57361 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -65,10 +65,10 @@ Below is a table of attributes that SHOULD be included on client and server gRPC ## gRPC Status The table below describes when -the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be set +the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/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](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#spankind). +and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#spankind). | gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status | |---|---|---| diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 2536649713..241a2fce4c 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -206,7 +206,7 @@ This metric is obtained by subscribing to [`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.1, 1, 10 ]`. diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md index ab4c498b63..8e2b385853 100644 --- a/docs/runtime/nodejs-metrics.md +++ b/docs/runtime/nodejs-metrics.md @@ -246,6 +246,6 @@ This metric is [recommended][MetricRecommended]. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/document-status.md [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended [Eventloop]: https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md index c26f429c16..f593a6bda3 100644 --- a/docs/runtime/v8js-metrics.md +++ b/docs/runtime/v8js-metrics.md @@ -32,7 +32,7 @@ This document describes semantic conventions for V8 JS Engine Runtime metrics in This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.1, 1, 10 ]`. @@ -228,5 +228,5 @@ This metric is [recommended][MetricRecommended]. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/document-status.md [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index a57c766eb0..33b6650c5e 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -6,9 +6,9 @@ # Set this to the version number you want to CHANGE in URLs in the repository. -PREVIOUS_SPECIFICATION_VERSION="v1.37.0" +PREVIOUS_SPECIFICATION_VERSION="v1.39.0" # Set this to the version number you want to KEEP in URLs in the repository. -LATEST_SPECIFICATION_VERSION="v1.39.0" +LATEST_SPECIFICATION_VERSION="v1.40.0" # The specific pattern we look for when replacing URLs SPECIFICATION_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/tree/" SPECIFICATION_BLOB_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/blob/" @@ -30,6 +30,6 @@ fix_file() { important_files=("docs" "model" "README.md") # TODO - limit to markdown/yaml files? -find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do +find "${important_files[@]}" -type f -not -path '*/.*' -not -path '*.png' -print0 | while read -d $'\0' file; do fix_file "$file" done From f80534875ebeba7b009dc34bf1c5ea98996d37ed Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Sat, 18 Jan 2025 12:41:08 -0800 Subject: [PATCH 07/20] Fix website linking (#1766) --- docs/general/naming.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/general/naming.md b/docs/general/naming.md index 62921a4ae9..ad6587f97b 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -1,3 +1,7 @@ + + # Naming **Status**: [Stable][DocumentStatus], Unless otherwise specified. From f249173193c50bb985cd59116f76e753ed21f392 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 05:11:38 -0800 Subject: [PATCH 08/20] Add clarification about `OTEL_SEMCONV_STABILITY_OPT_IN` (#1758) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/non-normative/db-migration.md | 4 ++++ docs/non-normative/http-migration.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 596a665a2c..bd6d2039bd 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -22,6 +22,10 @@ updated to the stable database semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable database conventions. +> [!NOTE] +> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating +> from an experimental semantic convention to its initial stable version. + ## Summary of changes This section summarizes the changes made to the HTTP semantic conventions diff --git a/docs/non-normative/http-migration.md b/docs/non-normative/http-migration.md index d0c70fe68f..959648b76c 100644 --- a/docs/non-normative/http-migration.md +++ b/docs/non-normative/http-migration.md @@ -29,6 +29,10 @@ updated to the stable HTTP semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable HTTP and networking conventions. +> [!NOTE] +> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating +> from an experimental semantic convention to its initial stable version. + ## Summary of changes This section summarizes the changes made to the HTTP semantic conventions From eae7a310558039380b3bbc15f28e3e606028df9a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 05:13:29 -0800 Subject: [PATCH 09/20] Fix link (#1761) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/general/recording-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md index 91246b7247..ea5189eadc 100644 --- a/docs/general/recording-errors.md +++ b/docs/general/recording-errors.md @@ -61,7 +61,7 @@ When the operation ends with an error, instrumentation: When the operation fails with an exception, the span status description SHOULD be set to the exception message. -Refer to the [recording exceptions](#recording-errors) on capturing exception +Refer to the [recording exceptions](#recording-exceptions) on capturing exception details. ## Recording errors on metrics From b810141201bb6b9b6e1c4e038f4d9d878056777d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 08:48:07 -0800 Subject: [PATCH 10/20] Move release instructions to RELEASING.md (#1762) --- CONTRIBUTING.md | 28 ---------------------------- RELEASING.md | 26 ++++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 28 deletions(-) create mode 100644 RELEASING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68755d1cf2..e2b4b153e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,6 @@ requirements and recommendations. - [Update the tables of content](#update-the-tables-of-content) - [Markdown link check](#markdown-link-check) - [Updating the referenced specification version](#updating-the-referenced-specification-version) -- [Making a Release](#making-a-release) - [Merging existing ECS conventions](#merging-existing-ecs-conventions) @@ -415,33 +414,6 @@ make markdown-link-check 4. Run the script from the root directory, e.g. `semantic-conventions$ ./internal/tools/update_specification_version.sh`. 5. Add all modified files to the change submit and submit a PR. -## Making a Release - -- Ensure the referenced specification version is up to date. Use - [tooling to update the spec](#updating-the-referenced-specification-version) - if needed. -- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) - against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. -- Create a staging branch for the release. - - Update `schema-next.yaml` file and move to `schemas/{version}` - - Ensure the `next` version is appropriately configured as the `{version}`. - - Copy `schema-next.yaml` to `schemas/{version}`. - - Add `next` as a version in `schema-next.yaml` version. - - Run `make chlog-update VERSION=v{version}` - - `make chlog-update` will clean up all the current `.yaml` files inside the - `.chloggen` folder automatically - - Double check that `CHANGELOG.md` is updated with the proper `v{version}` - - Send staging branch as PR for review. -- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): - - Set title and tag to `v{version}` - - Set target to the commit of the merged release PR - - Copy changelog to the release notes - - Verify that the release looks like expected - - Publish release - -New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR) -eventually results in new version of schema file being published. - ## Merging existing ECS conventions The Elastic Common Schema (ECS) is being merged into OpenTelemetry Semantic diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000000..18f54b3347 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,26 @@ +# Making a Release + +- Ensure the referenced specification version is up to date. Use + [tooling to update the spec](./CONTRIBUTING.md#updating-the-referenced-specification-version) + if needed. +- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) + against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. +- Create a staging branch for the release. + - Update `schema-next.yaml` file and move to `schemas/{version}` + - Ensure the `next` version is appropriately configured as the `{version}`. + - Copy `schema-next.yaml` to `schemas/{version}`. + - Add `next` as a version in `schema-next.yaml` version. + - Run `make chlog-update VERSION=v{version}` + - `make chlog-update` will clean up all the current `.yaml` files inside the + `.chloggen` folder automatically + - Double check that `CHANGELOG.md` is updated with the proper `v{version}` + - Send staging branch as PR for review. +- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): + - Set title and tag to `v{version}` + - Set target to the commit of the merged release PR + - Copy changelog to the release notes + - Verify that the release looks like expected + - Publish release + +New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR) +eventually results in new version of schema file being published. From 77f0b70d36c42f072ee1391afd681774cea4e39c Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 10:20:16 -0800 Subject: [PATCH 11/20] Release automation (#1765) Co-authored-by: Liudmila Molkova --- .github/workflows/prepare-release.yml | 59 +++++++++++++++++++ .../scripts/use-cla-approved-github-bot.sh | 4 ++ 2 files changed, 63 insertions(+) create mode 100644 .github/workflows/prepare-release.yml create mode 100755 .github/workflows/scripts/use-cla-approved-github-bot.sh diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml new file mode 100644 index 0000000000..f53766c277 --- /dev/null +++ b/.github/workflows/prepare-release.yml @@ -0,0 +1,59 @@ +name: Prepare release +on: + workflow_dispatch: + inputs: + version: + description: 'The version to release, e.g. 1.30.0' + required: true + +jobs: + create-pull-request: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate version + run: | + version=${{ inputs.version }} + if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "unexpected version: $version" + exit 1 + fi + + - name: Use CLA approved github bot + run: .github/workflows/scripts/use-cla-approved-github-bot.sh + + - name: Update schema files + run: | + if ! grep -q "^ next:$" schema-next.yaml; then + echo "String 'next:' not found in the file" + exit 1 + fi + + version=${{ inputs.version }} + sed -i "0,/^ next:$/s// $version:/" schema-next.yaml + cp schema-next.yaml "schemas/$version" + git add "schemas/$version" + + sed -i "0,/^ $version:$/s// next:\n $version:/" schema-next.yaml + + - name: Update change log + run: | + make chlog-update VERSION=v${{ inputs.version }} + + - name: Create pull request + env: + # not using secrets.GITHUB_TOKEN since pull requests from that token do not run workflows + GH_TOKEN: ${{ secrets.OPENTELEMETRYBOT_GITHUB_TOKEN }} + run: | + version=${{ inputs.version }} + message="Prepare release v${version}" + body="Prepare release \`v${version}\`." + branch="opentelemetrybot/prepare-release-v${version}" + + git checkout -b $branch + git commit -a -m "$message" + git push --set-upstream origin $branch + gh pr create --title "$message" \ + --body "$body" \ + --base main diff --git a/.github/workflows/scripts/use-cla-approved-github-bot.sh b/.github/workflows/scripts/use-cla-approved-github-bot.sh new file mode 100755 index 0000000000..a4c68b0e30 --- /dev/null +++ b/.github/workflows/scripts/use-cla-approved-github-bot.sh @@ -0,0 +1,4 @@ +#!/bin/bash -e + +git config user.name opentelemetrybot +git config user.email 107717825+opentelemetrybot@users.noreply.github.com From 0e109d266238cbd2ca5025f54edd51d5f18019b3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 20 Jan 2025 13:56:50 -0800 Subject: [PATCH 12/20] Label all new issues with `triage:needs-triage` label (#1767) --- .github/ISSUE_TEMPLATE/bug_report.yaml | 2 +- .github/ISSUE_TEMPLATE/change_proposal.yaml | 2 +- .github/ISSUE_TEMPLATE/new-conventions.yaml | 2 +- .../workflows/scripts/prepare-new-issue.sh | 29 +++++++------------ 4 files changed, 14 insertions(+), 21 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 43a6c3c748..252669d92b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -1,6 +1,6 @@ name: Bug report description: Create a report to help us improve -labels: ["bug", "triage:needs-triage"] +labels: ["bug"] body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index bb0d28736a..6eab59ae69 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -1,6 +1,6 @@ name: Propose changes to existing conventions description: Propose changes you'd like to be added to existing conventions -labels: ["enhancement", "triage:needs-triage"] +labels: ["enhancement"] body: - type: dropdown id: area diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index eb43279195..f4e3498651 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -1,6 +1,6 @@ name: Propose new semantic conventions description: Propose new conventions you'd like to be part of the OpenTelemetry project -labels: ["enhancement", "triage:needs-triage", "experts needed"] +labels: ["enhancement", "experts needed"] body: - type: markdown attributes: diff --git a/.github/workflows/scripts/prepare-new-issue.sh b/.github/workflows/scripts/prepare-new-issue.sh index 6142e5b3b8..391fc698ab 100755 --- a/.github/workflows/scripts/prepare-new-issue.sh +++ b/.github/workflows/scripts/prepare-new-issue.sh @@ -28,7 +28,7 @@ if [[ -z "${ISSUE:-}" || -z "${BODY:-}" || -z "${OPENER:-}" ]]; then exit 0 fi -LABELS="" +LABELS="triage:needs-triage" AREAS_SECTION_START=$( (echo "${BODY}" | grep -n '### Area(s)' | awk '{ print $1 }' | grep -oE '[0-9]+') || echo '-1' ) BODY_AREAS="" @@ -45,26 +45,19 @@ for AREA in ${BODY_AREAS}; do continue fi - if [[ -n "${LABELS}" ]]; then - LABELS+="," - fi - LABELS+="${AREA}" + LABELS+=",${AREA}" done -if [[ -v PINGED_AREAS[@] ]]; then - echo "The issue was associated with areas:" "${!PINGED_AREAS[@]}" +if [[ -v BODY_AREAS[@] ]]; then + echo "The issue was associated with areas:" "${!BODY_AREAS[@]}" else echo "No related areas were given" fi -if [[ -n "${LABELS}" ]]; then - # Notes on this call: - # 1. Labels will be deduplicated by the GitHub CLI. - # 2. The call to edit the issue will fail if any of the - # labels doesn't exist. We can be reasonably sure that - # all labels will exist since they come from a known set. - echo "Adding the following labels: ${LABELS//,/ /}" - gh issue edit "${ISSUE}" --add-label "${LABELS}" || true -else - echo "No labels were found to add" -fi +# Notes on this call: +# 1. Labels will be deduplicated by the GitHub CLI. +# 2. The call to edit the issue will fail if any of the +# labels doesn't exist. We can be reasonably sure that +# all labels will exist since they come from a known set. +echo "Adding the following labels: ${LABELS//,/ /}" +gh issue edit "${ISSUE}" --add-label "${LABELS}" || true From c828bebb75977b2139b53c2a0aad89b9bff767e3 Mon Sep 17 00:00:00 2001 From: Christos Markou Date: Tue, 21 Jan 2025 12:54:27 +0200 Subject: [PATCH 13/20] Add k8s.namespace.phase metric and attribute (#1668) Signed-off-by: ChrsMark Co-authored-by: Jina Jain --- .chloggen/add_k8s_ns_phase.yaml | 22 ++++++++++++++ docs/attributes-registry/k8s.md | 25 ++++++++++++---- docs/non-normative/k8s-migration.md | 19 ++++++++++++ docs/system/k8s-metrics.md | 45 +++++++++++++++++++++++++++++ model/k8s/metrics.yaml | 15 ++++++++++ model/k8s/registry.yaml | 30 +++++++++++++++---- 6 files changed, 144 insertions(+), 12 deletions(-) create mode 100755 .chloggen/add_k8s_ns_phase.yaml diff --git a/.chloggen/add_k8s_ns_phase.yaml b/.chloggen/add_k8s_ns_phase.yaml new file mode 100755 index 0000000000..b7813687e3 --- /dev/null +++ b/.chloggen/add_k8s_ns_phase.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: k8s + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add k8s.namespace.phase metric along with the respective attribute + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1668] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md index 784ab78b5e..ab3c706dc8 100644 --- a/docs/attributes-registry/k8s.md +++ b/docs/attributes-registry/k8s.md @@ -29,6 +29,7 @@ Kubernetes resource attributes. | `k8s.job.name` | string | The name of the Job. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.namespace.phase` | string | The phase of the K8s namespace. [2] | `active`; `terminating` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.node.name` | string | The name of the Node. | `node-1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.pod.annotation.` | string | The annotation key-value pairs placed on the Pod, the `` being the annotation name, the value being the annotation value. | `k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets=true`; `k8s.pod.annotation.mycompany.io/arch=x64`; `k8s.pod.annotation.data=` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -65,18 +66,30 @@ Which states: Therefore, UIDs between clusters should be extremely unlikely to conflict. +**[2] `k8s.namespace.phase`:** This attribute aligns with the `phase` field of the +[K8s NamespaceStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#namespacestatus-v1-core) + +--- + +`k8s.namespace.phase` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `active` | Active namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `terminating` | Terminating namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + --- `k8s.volume.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| -| `configMap` | A [configMap](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `downwardAPI` | A [downwardAPI](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `emptyDir` | An [emptyDir](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `local` | A [local](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `persistentVolumeClaim` | A [persistentVolumeClaim](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `secret` | A [secret](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `configMap` | A [configMap](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `downwardAPI` | A [downwardAPI](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `emptyDir` | An [emptyDir](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local` | A [local](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `persistentVolumeClaim` | A [persistentVolumeClaim](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `secret` | A [secret](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Deprecated Kubernetes Attributes diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index 39e7d464c5..022be1d594 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -51,6 +51,7 @@ and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then: - [K8s DaemonSet metrics](#k8s-daemonset-metrics) - [K8s Job metrics](#k8s-job-metrics) - [K8s Cronjob metrics](#k8s-cronjob-metrics) + - [K8s Namespace metrics](#k8s-namespace-metrics) @@ -234,3 +235,21 @@ The changes in their metric types are the following: | `k8s.cronjob.active_jobs` (type: `gauge`) | `k8s.cronjob.active_jobs` (type: `updowncounter`) | + +### K8s Namespace metrics + +The K8s Namespace metrics implemented by the Collector and specifically the +[k8scluster](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.115.0/receiver/k8sclusterreceiver/documentation.md) +receiver were introduced as semantic conventions in +[#1649](https://github.com/open-telemetry/semantic-conventions/pull/1668) (TODO: replace with SemConv version once +available). + +The changes in their metrics are the following: + + + +| Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | +|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| +| `k8s.namespace.phase` (type: `gauge`), 1 for active and 0 for terminating | `k8s.namespace.phase` (type: `updowncounter`), with the attribute `k8s.namespace.phase` indicating the phase | + + diff --git a/docs/system/k8s-metrics.md b/docs/system/k8s-metrics.md index e95ba7fec1..6211d31c6e 100644 --- a/docs/system/k8s-metrics.md +++ b/docs/system/k8s-metrics.md @@ -65,6 +65,8 @@ and therefore inherit its attributes, like `k8s.pod.name` and `k8s.pod.uid`. - [Metric: `k8s.job.max_parallel_pods`](#metric-k8sjobmax_parallel_pods) - [CronJob Metrics](#cronjob-metrics) - [Metric: `k8s.cronjob.active_jobs`](#metric-k8scronjobactive_jobs) +- [Namespace Metrics](#namespace-metrics) + - [Metric: `k8s.namespace.phase`](#metric-k8snamespacephase) @@ -1028,5 +1030,48 @@ This metric SHOULD, at a minimum, be reported against a +## Namespace Metrics + +**Description:** Namespace level metrics captured under the namespace `k8s.namespace`. + +### Metric: `k8s.namespace.phase` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `k8s.namespace.phase` | UpDownCounter | `{namespace}` | Describes number of K8s namespaces that are currently in a given phase. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This metric SHOULD, at a minimum, be reported against a +[`k8s.namespace`](../resource/k8s.md#namespace) resource. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.namespace.phase`](/docs/attributes-registry/k8s.md) | string | The phase of the K8s namespace. [1] | `active`; `terminating` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `k8s.namespace.phase`:** This attribute aligns with the `phase` field of the +[K8s NamespaceStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#namespacestatus-v1-core) + +--- + +`k8s.namespace.phase` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `active` | Active namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `terminating` | Terminating namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/k8s/metrics.yaml b/model/k8s/metrics.yaml index 1301662270..c091a5e4a0 100644 --- a/model/k8s/metrics.yaml +++ b/model/k8s/metrics.yaml @@ -442,3 +442,18 @@ groups: This metric SHOULD, at a minimum, be reported against a [`k8s.cronjob`](../resource/k8s.md#cronjob) resource. + + # k8s.namespace.* metrics + - id: metric.k8s.namespace.phase + type: metric + metric_name: k8s.namespace.phase + stability: experimental + brief: "Describes number of K8s namespaces that are currently in a given phase." + instrument: updowncounter + unit: "{namespace}" + note: | + This metric SHOULD, at a minimum, be reported against a + [`k8s.namespace`](../resource/k8s.md#namespace) resource. + attributes: + - ref: k8s.namespace.phase + requirement_level: required diff --git a/model/k8s/registry.yaml b/model/k8s/registry.yaml index e1e0107fcc..c9b639b697 100644 --- a/model/k8s/registry.yaml +++ b/model/k8s/registry.yaml @@ -192,25 +192,43 @@ groups: members: - id: persistent_volume_claim value: 'persistentVolumeClaim' - brief: "A [persistentVolumeClaim](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume" + brief: "A [persistentVolumeClaim](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume" stability: experimental - id: config_map value: 'configMap' - brief: "A [configMap](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume" + brief: "A [configMap](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume" stability: experimental - id: downward_api value: 'downwardAPI' - brief: "A [downwardAPI](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume" + brief: "A [downwardAPI](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume" stability: experimental - id: empty_dir value: 'emptyDir' - brief: "An [emptyDir](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume" + brief: "An [emptyDir](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume" stability: experimental - id: secret value: 'secret' - brief: "A [secret](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume" + brief: "A [secret](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume" stability: experimental - id: local value: 'local' - brief: "A [local](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume" + brief: "A [local](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume" + stability: experimental + - id: k8s.namespace.phase + stability: experimental + brief: > + The phase of the K8s namespace. + note: | + This attribute aligns with the `phase` field of the + [K8s NamespaceStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#namespacestatus-v1-core) + examples: [ "active", "terminating" ] + type: + members: + - id: active + value: 'active' + brief: "Active namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase)" + stability: experimental + - id: terminating + value: 'terminating' + brief: "Terminating namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase)" stability: experimental From efd7f1ec352da4947f868256bfba986a95114931 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 21 Jan 2025 07:24:07 -0800 Subject: [PATCH 14/20] Check and close milestone if any as part of release steps (#1774) --- RELEASING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/RELEASING.md b/RELEASING.md index 18f54b3347..1cb7183309 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,5 +1,7 @@ # Making a Release +- Close the [release milestone](https://github.com/open-telemetry/semantic-conventions/milestones) + if there is one. - Ensure the referenced specification version is up to date. Use [tooling to update the spec](./CONTRIBUTING.md#updating-the-referenced-specification-version) if needed. From 2eb5802266c9cf141690aaeba6a4c5d8891bf271 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 21 Jan 2025 13:22:02 -0800 Subject: [PATCH 15/20] Update issue templates (simplify and clarify the process) (#1771) Co-authored-by: Trask Stalnaker --- .github/ISSUE_TEMPLATE/bug_report.yaml | 27 ++--- .github/ISSUE_TEMPLATE/change_proposal.yaml | 24 ++--- .github/ISSUE_TEMPLATE/new-conventions.yaml | 114 +++----------------- 3 files changed, 30 insertions(+), 135 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 252669d92b..9424ec95d2 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -15,8 +15,10 @@ body: description: Which area(s) does your bug report concern? If none fits, please select `area:other` multiple: true options: + - docs + - tooling + - schema - area:other - - area:docs # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` # DO NOT manually edit it. # Start semconv area list @@ -90,27 +92,12 @@ body: # End semconv area list - type: textarea attributes: - label: What happened? - description: Please provide as much detail as you reasonably can. - value: | - ## Description - - ## Steps to Reproduce (if any) - - ## Expected Result - - ## Actual Result - validations: - required: true - - - type: input - attributes: - label: Semantic convention version - description: What version did you use? (e.g., `v1.24.0`, `1eb551b`, etc) + label: What's the problem? + description: Please describe the problem as precisely as you reasonably can. validations: required: true - type: textarea attributes: - label: Additional context - description: Any additional information you think may be relevant to this issue. + label: Describe the solution you'd like + description: A clear and concise description of solution you'd like to see. diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 6eab59ae69..64ea39cecb 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -1,6 +1,5 @@ -name: Propose changes to existing conventions -description: Propose changes you'd like to be added to existing conventions -labels: ["enhancement"] +name: Propose enhancement to existing conventions +description: Propose changes you'd like to see body: - type: dropdown id: area @@ -9,6 +8,9 @@ body: description: Which area(s) does your change request concern? multiple: true options: + - docs + - tooling + - schema # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` # DO NOT manually edit it. # Start semconv area list @@ -82,21 +84,11 @@ body: # End semconv area list - type: textarea attributes: - label: Is your change request related to a problem? Please describe. - description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + label: What's missing? + description: Please describe the use-case or scenario that is not covered by the existing conventions. validations: required: true - type: textarea attributes: label: Describe the solution you'd like - description: A clear and concise description of what you want to happen. - validations: - required: true - - type: textarea - attributes: - label: Describe alternatives you've considered - description: A clear and concise description of any alternative solutions or features you've considered. - - type: textarea - attributes: - label: Additional context - description: Add any other context or screenshots about the feature request here. + description: A clear and concise description of solution you'd like to see. diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index f4e3498651..f1daf6eac4 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -1,111 +1,27 @@ name: Propose new semantic conventions -description: Propose new conventions you'd like to be part of the OpenTelemetry project +description: Propose new conventions you'd like to see in the OpenTelemetry project labels: ["enhancement", "experts needed"] body: - type: markdown attributes: value: | - Please make sure to fill out the entire form below, providing as much context as you can in order to help us triage the proposal as quickly as possible. + Thanks for your interest in contributing to the OpenTelemetry Semantic Conventions! - Before filing the proposal, please be sure you have searched through [existing issues](https://github.com/open-telemetry/semantic-conventions/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aenhancement+label%3Aarea:new) to see if an existing issue covers your proposal. + Substantial changes to the conventions follow [OTel project management] + (https://github.com/open-telemetry/community/blob/main/project-management.md) process + and usually require a group of people who are familiar with the domain, + are involved with instrumentation efforts, and are committed to be the point of contact for + pull requests, issues, and questions in this area. - Additionally, make sure to read and follow the guidelines on [Project Proposal](https://github.com/open-telemetry/community/blob/main/project-management.md#project-management), in case the proposal is for a new set of conventions/working group. - - type: dropdown - id: area - attributes: - label: Area(s) - description: Which area(s) does your new conventions concern? If none fits, please select `area:new` - multiple: true - options: - - area:new - # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` - # DO NOT manually edit it. - # Start semconv area list - - area:android - - area:artifact - - area:aspnetcore - - area:aws - - area:azure - - area:browser - - area:cicd - - area:client - - area:cloud - - area:cloudevents - - area:cloudfoundry - - area:code - - area:container - - area:cpu - - area:db - - area:deployment - - area:destination - - area:device - - area:disk - - area:dns - - area:dotnet - - area:error - - area:exception - - area:faas - - area:feature-flag - - area:file - - area:gcp - - area:gen-ai - - area:geo - - area:go - - area:graphql - - area:hardware - - area:heroku - - area:host - - area:http - - area:jvm - - area:k8s - - area:linux - - area:log - - area:messaging - - area:network - - area:nodejs - - area:oci - - area:opentracing - - area:os - - area:otel - - area:peer - - area:process - - area:profile - - area:rpc - - area:security-rule - - area:server - - area:service - - area:session - - area:signalr - - area:source - - area:system - - area:telemetry - - area:test - - area:thread - - area:tls - - area:url - - area:user - - area:user-agent - - area:v8js - - area:vcs - - area:webengine - # End semconv area list - - type: textarea - attributes: - label: Is your change request related to a problem? Please describe. - description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - validations: - required: true + Creating a new issue here is a great first step to find others interested in collaborating. - type: textarea attributes: - label: Describe the solution you'd like - description: A clear and concise description of what you want to happen. + label: Propose new conventions + description: | + Please provide a brief description of the conventions, including + telemetry signals you'd like to define. + + Consider specifying which instrumentations or systems would implement these + conventions and the benefits they would bring to the ecosystem. validations: required: true - - type: textarea - attributes: - label: Describe alternatives you've considered - description: A clear and concise description of any alternative solutions or features you've considered. - - type: textarea - attributes: - label: Additional context - description: Add any other context or screenshots about the feature request here. From 8d43ef0bcc0886d5e9dbcdf884d9b0463b33f87e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 22 Jan 2025 09:18:47 -0800 Subject: [PATCH 16/20] Add warning to db migration guide (#1785) --- docs/non-normative/db-migration.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index bd6d2039bd..91135a9299 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -1,5 +1,9 @@ # Database semantic convention stability migration guide +> [!WARNING] +> This document is a work in progress and the database semantic conventions +> have not been marked stable yet and changes are still being made. + Due to the significant number of modifications and the extensive user base affected by them, existing database instrumentations published by OpenTelemetry are required to implement a migration plan that will assist users in From 578c4bf60ba4c9f744a0745c29298197b8e51d07 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 22 Jan 2025 10:15:11 -0800 Subject: [PATCH 17/20] Update release instructions (#1778) --- RELEASING.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 1cb7183309..683e009dde 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,4 +1,6 @@ -# Making a Release +# Releasing + +## Preparing a new release - Close the [release milestone](https://github.com/open-telemetry/semantic-conventions/milestones) if there is one. @@ -7,17 +9,13 @@ if needed. - Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. -- Create a staging branch for the release. - - Update `schema-next.yaml` file and move to `schemas/{version}` - - Ensure the `next` version is appropriately configured as the `{version}`. - - Copy `schema-next.yaml` to `schemas/{version}`. - - Add `next` as a version in `schema-next.yaml` version. - - Run `make chlog-update VERSION=v{version}` - - `make chlog-update` will clean up all the current `.yaml` files inside the - `.chloggen` folder automatically - - Double check that `CHANGELOG.md` is updated with the proper `v{version}` - - Send staging branch as PR for review. -- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): +- Run the [prepare release workflow](https://github.com/open-telemetry/semantic-conventions/actions/workflows/prepare-release.yml). + - Review and merge the pull request that it creates. + - Note: the PR will need to be closed and the workflow re-run if any non-chore PRs are merged to `main` while the PR is open. + +## Making the release + +- Create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): - Set title and tag to `v{version}` - Set target to the commit of the merged release PR - Copy changelog to the release notes From 68b0afaf20c05933fe1ffc3a9cb498d6c97ea938 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 22 Jan 2025 10:45:29 -0800 Subject: [PATCH 18/20] Don't render deprecated enum members (#1764) --- docs/attributes-registry/db.md | 5 ----- docs/attributes-registry/messaging.md | 2 -- docs/attributes-registry/system.md | 1 - templates/registry/markdown/enum_macros.j2 | 2 +- 4 files changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 6877905356..76bebb23a1 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -88,12 +88,9 @@ Semantic conventions for individual database systems SHOULD document what `db.re | Value | Description | Stability | |---|---|---| | `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cache` | Deprecated, use `intersystems_cache` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `intersystems_cache`. | | `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cloudscape` | Deprecated, use `other_sql` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `other_sql`. | | `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `coldfusion` | Deprecated, no replacement at this time. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | | `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -104,7 +101,6 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firstsql` | Deprecated, use `other_sql` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `other_sql`. | | `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -122,7 +118,6 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `mssqlcompact` | Deprecated, Microsoft SQL Server Compact is discontinued. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, use `other_sql` instead. | | `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index b21661f4df..915a4989aa 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -66,9 +66,7 @@ size should be used. | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch sending scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `deliver` | Deprecated. Use `process` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `process`. | | `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `publish` | Deprecated. Use `send` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `send`. | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md index 8a6f0166e6..9178e260e9 100644 --- a/docs/attributes-registry/system.md +++ b/docs/attributes-registry/system.md @@ -81,7 +81,6 @@ Describes System Memory attributes | `buffers` | buffers | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cached` | cached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `shared` | shared | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, report shared memory usage with `metric.system.memory.shared` metric | | `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## System Paging Attributes diff --git a/templates/registry/markdown/enum_macros.j2 b/templates/registry/markdown/enum_macros.j2 index 8dbc583cdc..d20327e14b 100644 --- a/templates/registry/markdown/enum_macros.j2 +++ b/templates/registry/markdown/enum_macros.j2 @@ -1,5 +1,5 @@ {% import 'stability.j2' as stability %} -{% macro filter(member) %}{% if snippet_type is not defined or (member.deprecated is none or member.deprecated == "") %}{{ "True" }}{% else %}{{ "False" }}{% endif %}{% endmacro %} +{% macro filter(member) %}{% if (member.deprecated is none or member.deprecated == "") %}{{ "True" }}{% else %}{{ "False" }}{% endif %}{% endmacro %} {% macro table(enum, notes) %} --- From e2f8527758b01660049598ea5ccbbe25677d8f14 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 22 Jan 2025 10:48:15 -0800 Subject: [PATCH 19/20] Label PRs that contain breaking changes based on the changelog (#1769) Co-authored-by: Trask Stalnaker --- .github/workflows/prepare-new-issue.yml | 3 -- .github/workflows/prepare-new-pr.yml | 32 +++++++++++++++++ .github/workflows/scripts/prepare-new-pr.sh | 39 +++++++++++++++++++++ 3 files changed, 71 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/prepare-new-pr.yml create mode 100755 .github/workflows/scripts/prepare-new-pr.sh diff --git a/.github/workflows/prepare-new-issue.yml b/.github/workflows/prepare-new-issue.yml index 345b7dcd1e..f17a144fca 100644 --- a/.github/workflows/prepare-new-issue.yml +++ b/.github/workflows/prepare-new-issue.yml @@ -10,9 +10,6 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Run update permissions - run: chmod +x ./.github/workflows/scripts/prepare-new-issue.sh - - name: Run prepare-new-issue.sh run: ./.github/workflows/scripts/prepare-new-issue.sh env: diff --git a/.github/workflows/prepare-new-pr.yml b/.github/workflows/prepare-new-pr.yml new file mode 100644 index 0000000000..a8a00fe5eb --- /dev/null +++ b/.github/workflows/prepare-new-pr.yml @@ -0,0 +1,32 @@ +name: 'Prepare new PR' +on: + pull_request_target: + types: [opened, synchronize] + branches: [ 'main*' ] + paths: ['.chloggen/*'] + +jobs: + prepare-new-pr: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + if: ${{ github.repository_owner == 'open-telemetry' }} + steps: + # check out main + - uses: actions/checkout@v4 + # sparse checkout to only get the .chloggen directory + - uses: actions/checkout@v4 + with: + ref: ${{ github.head_ref }} + path: prchangelog + sparse-checkout: .chloggen + + # we're going to run prepare-new-pr script from the main branch + # to parse changelog record from the PR branch. + - name: Run prepare-new-pr.sh + run: ./.github/workflows/scripts/prepare-new-pr.sh + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR: ${{ github.event.pull_request.number }} + PR_CHANGELOG_PATH: prchangelog diff --git a/.github/workflows/scripts/prepare-new-pr.sh b/.github/workflows/scripts/prepare-new-pr.sh new file mode 100755 index 0000000000..dc369b80b4 --- /dev/null +++ b/.github/workflows/scripts/prepare-new-pr.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# +# Copyright The OpenTelemetry Authors +# SPDX-License-Identifier: Apache-2.0 +# +# This script uses chloggen file to get the change_type and adds it as a label to the PR. +# If there are none or multiple changelog files, it will ignore the PR. +# +# Notes: +# - label should exist in the repository in order to add it to the PR. +# - if label already exist, this is a no-op. +# - if any error happens, the script quietly exits with 0. + +if [ -z ${PR:-} ]; then + echo "PR number is required" + exit 1 +fi + +if [ -z ${PR_CHANGELOG_PATH:-} ]; then + echo "PR_CHANGELOG_PATH is required" + exit 1 +fi + +CHLOG="$(gh pr view $PR --json files --jq '.files.[].path | select (. | startswith(".chloggen/"))')" +echo "Change log file(s): ${CHLOG}" + +if [ -z "$CHLOG" ]; then + echo "No changelog found in the PR. Ignoring this change." + exit 0 +fi + +COUNT="$(echo "$CHLOG" | wc -l)" +if [ $COUNT -eq 1 ]; then + CHANGE_TYPE=$(awk -F': ' '/^change_type:/ {print $2}' "$PR_CHANGELOG_PATH/$CHLOG" | xargs) + echo $CHANGE_TYPE + gh pr edit "${PR}" --add-label "${CHANGE_TYPE}" || true +else + echo "Found multiple changelog files. Ignoring this change." +fi From 01bf5e44d2a451cbd94704faf1e94048a2674759 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 22 Jan 2025 12:26:48 -0800 Subject: [PATCH 20/20] Temporarily ignore failing link (#1786) --- .lychee.toml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.lychee.toml b/.lychee.toml index 38599eea36..c60f30a7f4 100644 --- a/.lychee.toml +++ b/.lychee.toml @@ -6,7 +6,9 @@ exclude = [ "^https://www.foo.bar", # excluding links to pull requests and issues is done for performance "^https://github.com/open-telemetry/semantic-conventions/(pull|issues)/\\d+$", - "^https://github.com/open-telemetry/opentelemetry-specification/(pull|issues)/\\d+$" + "^https://github.com/open-telemetry/opentelemetry-specification/(pull|issues)/\\d+$", + # TODO (trask) remove this exclusion after (hopefully) this page comes back up + "^https://docs.oracle.com/en/java/javase/17/docs/api/" ] # better to be safe and avoid failures