Merge branch 'main' into deprecate-tls-server-name

.chloggen/1166.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: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: db
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Sampling relevant attributes defined for database client spans
+
+# 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: [ 1019 ]
+
+# (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:

.chloggen/1167.yaml

@@ -0,0 +1,4 @@
+change_type: bug_fix
+component: http
+note: "Relax requirement on when to set HTTP span status to Error from `MUST` to `SHOULD`."
+issues: [1167, 1003]

.chloggen/1202.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: gen_ai
+note: Convert `gen_ai.operation.name` to enum and use it on spans
+issues: [ 1202 ]

.chloggen/log-original-body.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: log
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add 'log.record.original' 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: [1137]
+
+# (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:

docs/attributes-registry/gen-ai.md

@@ -16,8 +16,8 @@ This document defines the attributes used to describe telemetry in the context o
 | Attribute                          | Type     | Description                                                                                      | Examples                                                                | Stability                                                        |
 | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
 | `gen_ai.completion`                | string   | The full response received from the GenAI model. [1]                                             | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `gen_ai.operation.name`            | string   | The name of the operation being performed.                                                       | `chat`; `completion`                                                    | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `gen_ai.prompt`                    | string   | The full prompt sent to the GenAI model. [2]                                                     | `[{'role': 'user', 'content': 'What is the capital of France?'}]`       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `gen_ai.operation.name`            | string   | The name of the operation being performed. [2]                                                   | `chat`; `text_completion`                                               | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `gen_ai.prompt`                    | string   | The full prompt sent to the GenAI model. [3]                                                     | `[{'role': 'user', 'content': 'What is the capital of France?'}]`       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.request.frequency_penalty` | double   | The frequency penalty setting for the GenAI request.                                             | `0.1`                                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.request.max_tokens`        | int      | The maximum number of tokens the model generates for a request.                                  | `100`                                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.request.model`             | string   | The name of the GenAI model a request is being made to.                                          | `gpt-4`                                                                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -29,17 +29,33 @@ This document defines the attributes used to describe telemetry in the context o
 | `gen_ai.response.finish_reasons`   | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`                                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.response.id`               | string   | The unique identifier for the completion.                                                        | `chatcmpl-123`                                                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.response.model`            | string   | The name of the model that generated the response.                                               | `gpt-4-0613`                                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `gen_ai.system`                    | string   | The Generative AI product as identified by the client or server instrumentation. [3]             | `openai`                                                                | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `gen_ai.system`                    | string   | The Generative AI product as identified by the client or server instrumentation. [4]             | `openai`                                                                | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.token.type`                | string   | The type of token being counted.                                                                 | `input`; `output`                                                       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.usage.input_tokens`        | int      | The number of tokens used in the GenAI input (prompt).                                           | `100`                                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `gen_ai.usage.output_tokens`       | int      | The number of tokens used in the GenAI response (completion).                                    | `180`                                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation)
 
-**[2]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation)
+**[2]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
 
-**[3]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge.
-For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
+**[3]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation)
+
+**[4]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+by `gen_ai.request.model` and `gen_ai.response.model` attributes.
+
+The actual GenAI product may differ from the one identified by the client.
+For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system`
+is set to `openai` based on the instrumentation's best knowledge.
+
+For custom model, a custom friendly name SHOULD be used.
+If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
+
+`gen_ai.operation.name` 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                                                        |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `chat`            | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)                         | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 

docs/attributes-registry/log.md

@@ -40,9 +40,12 @@ Attributes for a file to which log was emitted.
 
 This document defines the generic attributes that may be used in any Log Record.
 
-| Attribute        | Type   | Description                                 | Examples                     | Stability                                                        |
-| ---------------- | ------ | ------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
-| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Attribute             | Type   | Description                                 | Examples                                                                                                                         | Stability                                                        |
+| --------------------- | ------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `log.record.original` | string | The complete orignal Log Record. [1]        | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `log.record.uid`      | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV`                                                                                                     | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
+**[1]:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.)
+
+**[2]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
 The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed.

docs/attributes-registry/process.md

@@ -33,7 +33,7 @@ An operating system process.
 | `process.real_user.id`        | int      | The real user ID (RUID) of the process.                                                                                                                                                                                                                                                                                                                     | `1000`                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.real_user.name`      | string   | The username of the real user of the process.                                                                                                                                                                                                                                                                                                               | `operator`                                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.runtime.description` | string   | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment.                                                                                                                                                                                                                         | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0`    | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `process.runtime.name`        | string   | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler.                                                                                                                                                                                                                                             | `OpenJDK Runtime Environment`                       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `process.runtime.name`        | string   | The name of the runtime of this process.                                                                                                                                                                                                                                                                                                                    | `OpenJDK Runtime Environment`                       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.runtime.version`     | string   | The version of the runtime of this process, as returned by the runtime without modification.                                                                                                                                                                                                                                                                | `14.0.2`                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.saved_user.id`       | int      | The saved user ID (SUID) of the process.                                                                                                                                                                                                                                                                                                                    | `1002`                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.saved_user.name`     | string   | The username of the saved user.                                                                                                                                                                                                                                                                                                                             | `operator`                                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

docs/database/cassandra.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"cassandra"`.
+`db.system` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**.
 
 ## Attributes
 
@@ -75,6 +75,16 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `db.cassandra.consistency_level` 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 |

docs/database/cosmosdb.md

@@ -13,7 +13,7 @@ described on this page.
 
 ## Attributes
 
-`db.system` MUST be set to `"cosmosdb"`.
+`db.system` MUST be set to `"cosmosdb"` and SHOULD be provided **at span creation time**.
 
 Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created.
 
@@ -76,6 +76,16 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `db.cosmosdb.connection_mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |