diff --git a/.chloggen/1297.yaml b/.chloggen/1297.yaml new file mode 100644 index 0000000000..3b907728a4 --- /dev/null +++ b/.chloggen/1297.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen_ai +note: Add `server.address`, `server.port`, and `error.type` to GenAI spans. +issues: [ 1297 ] diff --git a/.chloggen/add_linux_memory_slab.yaml b/.chloggen/add_linux_memory_slab.yaml new file mode 100755 index 0000000000..ebc232861f --- /dev/null +++ b/.chloggen/add_linux_memory_slab.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: linux + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add the `system.linux.memory.slab.usage` metric and the `linux.memory.slab.state` attributes. + +# 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: [531] + +# (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/.chloggen/jvm_memory-buffer_metric_renaming.yaml b/.chloggen/jvm_memory-buffer_metric_renaming.yaml new file mode 100755 index 0000000000..19ef16c697 --- /dev/null +++ b/.chloggen/jvm_memory-buffer_metric_renaming.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: jvm + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "Rename JVM metric `jvm.buffer.memory.usage` to `jvm.buffer.memory.used`" + +# 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: [288] + +# (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/.editorconfig b/.editorconfig new file mode 100644 index 0000000000..dfcc411892 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +root = true + +[*.{yaml,yml}] +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.rego] +indent_style = space +indent_size = 4 +trim_trailing_whitespace = true +insert_final_newline = true + +[Makefile] +indent_style = tab diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 9e86d2ce75..40af0a175b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -52,6 +52,7 @@ body: - area:http - area:jvm - area:k8s + - area:linux - area:log - area:messaging - area:network diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 7a1e2c8165..cc7c77ee8b 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -45,6 +45,7 @@ body: - area:http - area:jvm - area:k8s + - area:linux - area:log - area:messaging - area:network diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 8c13039fed..5787556938 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -54,6 +54,7 @@ body: - area:http - area:jvm - area:k8s + - area:linux - area:log - area:messaging - area:network diff --git a/docs/README.md b/docs/README.md index 27c2c200a0..f31cc91fa5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,3 +42,5 @@ Semantic Conventions by signals: * [Metrics](general/metrics.md): Semantic Conventions for metrics. * [Resource](resource/README.md): Semantic Conventions for resources. * [Trace](general/trace.md): Semantic Conventions for traces and spans. + +Also see, [Non-normative supplementary information](non-normative/README.md). diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index ad69328b23..49d5806716 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -66,6 +66,7 @@ Currently, the following namespaces exist: - [iOS](ios.md) - [JVM](jvm.md) - [K8s](k8s.md) +- [Linux](linux.md) - [Log](log.md) - [Messaging](messaging.md) - [Network](network.md) diff --git a/docs/attributes-registry/linux.md b/docs/attributes-registry/linux.md new file mode 100644 index 0000000000..cf817efa8e --- /dev/null +++ b/docs/attributes-registry/linux.md @@ -0,0 +1,22 @@ + + + + + +# Linux + +## Linux Memory Attributes + +Describes Linux Memory attributes + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | --------------------------- | ------------------------------ | ---------------------------------------------------------------- | +| `linux.memory.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------------- | ------------- | ---------------------------------------------------------------- | +| `reclaimable` | reclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 84e003d360..c9857d47fb 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -15,7 +15,7 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation -See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation). +See [compatibility](../non-normative/compatibility/aws.md#context-propagation). ## Common Attributes diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 4ed35e73f9..b36fde656a 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -168,7 +168,7 @@ For every message in the event, the [message system attributes][] (not message a 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.33.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](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. +See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. - [`messaging.operation.type`](/docs/messaging/messaging-spans.md) MUST be set to `process`. @@ -181,7 +181,7 @@ corresponding to the SQS event. The [message system attributes][] (not message a 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.33.0/specification/context/api-propagators.md) and added as a link to the span. -See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. +See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. - [`messaging.operation.type`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`. diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 800741360b..b2db3e1b2a 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -75,9 +75,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64 | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.token.type`](/docs/attributes-registry/gen-ai.md) | string | The type of token being counted. | `input`; `output` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** 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. @@ -165,9 +165,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [ 0.01, 0.02, | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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 the operation ended in an error | ![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` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** 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. @@ -265,9 +265,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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 the operation ended in an error | ![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` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** 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. @@ -364,9 +364,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** 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. @@ -451,9 +451,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** 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. diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index e50cd6a05d..505935dee1 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -52,6 +52,8 @@ These attributes track input data and metadata for a request to an GenAI model. | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [5] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -61,9 +63,10 @@ These attributes track input data and metadata for a request to an GenAI model. | [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [4] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [6] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** 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. @@ -79,8 +82,23 @@ 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`. -**[4]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +**[4]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +the canonical name of exception that occurred, or another low-cardinality error identifier. +Instrumentations SHOULD document the list of errors they report. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[6]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + + + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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. diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 895fbe8e4e..cb3f3360ca 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -1,6 +1,6 @@ # General Attributes diff --git a/docs/general/events.md b/docs/general/events.md index f86dda708f..87460baae5 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -1,6 +1,6 @@ # Semantic Conventions for Events diff --git a/docs/general/logs.md b/docs/general/logs.md index b48b379edd..24ead6f931 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -1,6 +1,6 @@ # General Logs Attributes diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 09892e5fc0..3c9740a478 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -1,6 +1,6 @@ # Metrics Semantic Conventions diff --git a/docs/non-normative/README.md b/docs/non-normative/README.md new file mode 100644 index 0000000000..c51419111d --- /dev/null +++ b/docs/non-normative/README.md @@ -0,0 +1,11 @@ + + +# Non-normative supplementary information + +The pages in this section are **non-normative**, most are supplementary +guidelines. diff --git a/docs/non-normative/compatibility/README.md b/docs/non-normative/compatibility/README.md new file mode 100644 index 0000000000..fa1af86c8e --- /dev/null +++ b/docs/non-normative/compatibility/README.md @@ -0,0 +1,7 @@ + + +# Compatibility diff --git a/supplementary-guidelines/compatibility/aws.md b/docs/non-normative/compatibility/aws.md similarity index 93% rename from supplementary-guidelines/compatibility/aws.md rename to docs/non-normative/compatibility/aws.md index 3777cb22a9..e40a7cc1aa 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/docs/non-normative/compatibility/aws.md @@ -1,6 +1,10 @@ + + # Compatibility Considerations for AWS -This document highlights compatibility considerations for OpenTelemetry +This page highlights compatibility considerations for OpenTelemetry instrumentations when interacting with AWS managed services using an aws-sdk, a third-party library, or a direct HTTP request. diff --git a/docs/http/migration-guide.md b/docs/non-normative/http-migration.md similarity index 98% rename from docs/http/migration-guide.md rename to docs/non-normative/http-migration.md index 65fea1a3fe..d0c70fe68f 100644 --- a/docs/http/migration-guide.md +++ b/docs/non-normative/http-migration.md @@ -1,4 +1,9 @@ -# HTTP semantic convention stability migration guide + + +# HTTP semantic convention stability migration Due to the significant number of modifications and the extensive user base affected by them, existing HTTP instrumentations published by @@ -207,7 +212,7 @@ which case `{summary}` is `HTTP`. ### Migrating from `<= v1.16.0` -This document does not cover these versions. +This page does not cover these versions. [Host header]: https://tools.ietf.org/html/rfc7230#section-5.4 [HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1 diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/docs/non-normative/libraries.md similarity index 93% rename from supplementary-guidelines/semantic_conventions_code_generation.md rename to docs/non-normative/libraries.md index 76436fed77..320627ed3e 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/docs/non-normative/libraries.md @@ -1,3 +1,8 @@ + + # Semantic convention libraries @@ -115,4 +120,4 @@ Code-generation usually involves several steps which could be semi-automated: 5. Fix lint violations in the auto-generated code (if any) 6. Send the PR with new code to the corresponding repository -Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh). +Here are examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh). diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 33bfa93f4c..cbda57ad10 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -33,7 +33,7 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry. - [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) - [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) - [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) - - [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) + - [Metric: `jvm.buffer.memory.used`](#metric-jvmbuffermemoryused) - [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) - [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) @@ -743,12 +743,12 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht -### Metric: `jvm.buffer.memory.usage` +### Metric: `jvm.buffer.memory.used` This metric is [recommended][MetricRecommended]. This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). - + @@ -757,7 +757,7 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `jvm.buffer.memory.used` | UpDownCounter | `By` | Measure of memory used by buffers. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -765,7 +765,7 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o - + diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index dbdee390f8..46ef36db2f 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -57,6 +57,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [Metric: `system.process.created`](#metric-systemprocesscreated) - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) - [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable) + - [Metric: `system.linux.memory.slab.usage`](#metric-systemlinuxmemoryslabusage) @@ -1475,6 +1476,58 @@ See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5 + + + + + +### Metric: `system.linux.memory.slab.usage` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.linux.memory.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system. +Note that the total slab memory is not constant and may vary over time. +See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`linux.memory.slab.state`](/docs/attributes-registry/linux.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `reclaimable` | reclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index 34af42f446..c5a8387f1a 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -27,7 +27,7 @@ fix_file() { "$1" } -important_files=("docs" "model" "README.md" "supplementary-guidelines") +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 diff --git a/model/metrics/deprecated/jvm-metrics.yaml b/model/metrics/deprecated/jvm-metrics.yaml new file mode 100644 index 0000000000..2641fc1a5c --- /dev/null +++ b/model/metrics/deprecated/jvm-metrics.yaml @@ -0,0 +1,10 @@ +groups: + - id: metric.jvm.buffer.memory.usage.deprecated + type: metric + metric_name: jvm.buffer.memory.usage + stability: experimental + deprecated: "Replaced by `jvm.buffer.memory.used`." + brief: "Deprecated, use `jvm.buffer.memory.used` instead." + extends: attributes.jvm.buffer + instrument: updowncounter + unit: "By" diff --git a/model/metrics/gen-ai.yaml b/model/metrics/gen-ai.yaml index 7c9979cf21..2c7035876c 100644 --- a/model/metrics/gen-ai.yaml +++ b/model/metrics/gen-ai.yaml @@ -4,10 +4,12 @@ groups: brief: 'This group describes GenAI metrics attributes' attributes: - ref: server.address + brief: GenAI server address. requirement_level: recommended - ref: server.port + brief: GenAI server port. requirement_level: - conditionally_required: If `sever.address` is set. + conditionally_required: If `server.address` is set. - ref: gen_ai.response.model requirement_level: recommended - ref: gen_ai.request.model diff --git a/model/metrics/jvm-metrics-experimental.yaml b/model/metrics/jvm-metrics-experimental.yaml index 5c9dc5025b..80e3a99041 100644 --- a/model/metrics/jvm-metrics-experimental.yaml +++ b/model/metrics/jvm-metrics-experimental.yaml @@ -41,9 +41,9 @@ groups: - ref: jvm.buffer.pool.name requirement_level: recommended - - id: metric.jvm.buffer.memory.usage + - id: metric.jvm.buffer.memory.used type: metric - metric_name: jvm.buffer.memory.usage + metric_name: jvm.buffer.memory.used stability: experimental extends: attributes.jvm.buffer brief: "Measure of memory used by buffers." diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 25e2d06665..9784deeece 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -342,3 +342,17 @@ groups: instrument: updowncounter unit: "By" attributes: [] + + - id: metric.system.linux.memory.slab.usage + type: metric + metric_name: system.linux.memory.slab.usage + stability: experimental + brief: "Reports the memory used by the Linux kernel for managing caches of frequently used objects." + note: | + The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system. + Note that the total slab memory is not constant and may vary over time. + See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + instrument: updowncounter + unit: "By" + attributes: + - ref: linux.memory.slab.state diff --git a/model/registry/linux.yaml b/model/registry/linux.yaml new file mode 100644 index 0000000000..a0f7caef79 --- /dev/null +++ b/model/registry/linux.yaml @@ -0,0 +1,19 @@ +groups: + # linux.memory.* attribute group + - id: registry.linux.memory + prefix: linux.memory + type: attribute_group + brief: "Describes Linux Memory attributes" + attributes: + - id: slab.state + type: + members: + - id: reclaimable + value: 'reclaimable' + stability: experimental + - id: unreclaimable + value: 'unreclaimable' + stability: experimental + stability: experimental + brief: "The Linux Slab memory state" + examples: ["reclaimable", "unreclaimable"] diff --git a/model/trace/gen-ai.yaml b/model/trace/gen-ai.yaml index d036c19755..9345f4f249 100644 --- a/model/trace/gen-ai.yaml +++ b/model/trace/gen-ai.yaml @@ -42,6 +42,20 @@ groups: requirement_level: recommended - ref: gen_ai.usage.output_tokens requirement_level: recommended + - ref: server.address + brief: GenAI server address. + requirement_level: recommended + - ref: server.port + brief: GenAI server port. + requirement_level: + conditionally_required: If `server.address` is set. + - ref: error.type + requirement_level: + conditionally_required: "if the operation ended in an error" + note: | + The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, + the canonical name of exception that occurred, or another low-cardinality error identifier. + Instrumentations SHOULD document the list of errors they report. events: - gen_ai.content.prompt - gen_ai.content.completion diff --git a/policies/registry.rego b/policies/registry.rego index 1c73ef450a..cc30c75f48 100644 --- a/policies/registry.rego +++ b/policies/registry.rego @@ -6,37 +6,37 @@ package before_resolution # Helper to create attribute registry violations. attr_registry_violation(violation_id, group_id, attr_id) = violation { - violation := { - "id": violation_id, - "type": "semantic_convention_policies", - "category": "attribute_registry_checks", - "group": group_id, - "attr": attr_id, - } + violation := { + "id": violation_id, + "type": "semantic_convention_policies", + "category": "attribute_registry_checks", + "group": group_id, + "attr": attr_id, + } } # We only allow attribute groups in the attribute registry. deny[attr_registry_violation("attribute_registry_can_only_contain_attribute_groups", group.id, "")] { - group := input.groups[_] - startswith(group.id, "registry.") - group.type != "attribute_group" + group := input.groups[_] + startswith(group.id, "registry.") + group.type != "attribute_group" } # Any group that is NOT in the attribute registry that has an attribute id is # in violation of not using the attribute registry. deny[attr_registry_violation("attributes_must_be_defined_in_attribute_registry", group.id, attr.id)] { - group := input.groups[_] - not startswith(group.id, "registry.") - attr := group.attributes[_] - attr.id != null + group := input.groups[_] + not startswith(group.id, "registry.") + attr := group.attributes[_] + attr.id != null } # A registry `attribute_group` containing at least one `ref` attribute is # considered invalid if it's not in the registry group. deny[attr_registry_violation("attributes_in_registry_cannot_reference_each_other", group.id, attr.ref)] { - # TODO - this will need to be updated to support `embed` in the future. - group := input.groups[_] - startswith(group.id, "registry.") - attr := group.attributes[_] - attr.ref != null + # TODO - this will need to be updated to support `embed` in the future. + group := input.groups[_] + startswith(group.id, "registry.") + attr := group.attributes[_] + attr.ref != null } diff --git a/schema-next.yaml b/schema-next.yaml index bb6c64e824..f475f28047 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -70,6 +70,9 @@ versions: - process.cpu.time - process.cpu.utilization - container.cpu.time + # https://github.com/open-telemetry/semantic-conventions/pull/1265 + - rename_metrics: + jvm.buffer.memory.usage: jvm.buffer.memory.used 1.26.0: metrics: changes: