open-telemetry · renovate · May 15, 2026 · May 15, 2026
@@ -50,7 +50,7 @@ task default: default_tasks
 desc 'update semantic conventions'
 task generate: %i[update_spec_version_constant generate_require_rollups]
 
-SPEC_VERSION = '1.38.0'
+SPEC_VERSION = '1.40.0'
 OTEL_WEAVER_VERSION = 'v0.22.1'
 semconv_source_dir = Pathname.new('./tmp/semconvrepo')
 semconv_output_dir = Pathname.new('./lib/opentelemetry/semconv')

@@ -7,7 +7,7 @@
 module OpenTelemetry
   module SemanticConventions
     # Version of the OpenTelemetry Semantic Conventions from which this library was generated.
-    SPEC_VERSION = '1.38.0'
+    SPEC_VERSION = '1.40.0'
     # Release version of this gem. May not match SPEC_VERSION until gem is released after a spec update.
     VERSION = '1.37.1'
   end

@@ -83,15 +83,20 @@ module DB
       # Summary may be available to the instrumentation through
       # instrumentation hooks or other means. If it is not available, instrumentations
       # that support query parsing SHOULD generate a summary following
-      # [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query)
+      # [Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query)
       # section.
       #
+      # For batch operations, if the individual operations are known to have the same query summary
+      # then that query summary SHOULD be used prepended by `BATCH `,
+      # otherwise `db.query.summary` SHOULD be `BATCH` or some other database
+      # system specific term if more applicable.
+      #
       # @note Stability Level: stable
       DB_QUERY_SUMMARY = 'db.query.summary'
 
       # The database query being executed.
       #
-      # For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext).
+      # For sanitization see [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext).
       # For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
       # Parameterized query text SHOULD NOT be sanitized. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
       #

@@ -39,7 +39,7 @@ module ERROR
       #
       # If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
       #
-      # If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
+      # If a specific domain defines its own set of error identifiers (such as HTTP or RPC status codes),
       # it's RECOMMENDED to:
       #
       # - Use a domain-specific attribute

@@ -31,6 +31,8 @@ module EXCEPTION
 
       # The exception message.
       #
+      # > [!WARNING]> This attribute may contain sensitive information.
+      #
       # @note Stability Level: stable
       EXCEPTION_MESSAGE = 'exception.message'
 

@@ -62,8 +62,15 @@ module HTTP
       #
       # If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override
       # the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named
-      # OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods
-      # (this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).
+      # OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods.
+      #
+      #
+      # If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property
+      # (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or
+      # `.instrumentation/development.general.http.server`.
+      #
+      # In either case, this list MUST be a full override of the default known methods,
+      # it is not a list of known methods in addition to the defaults.
       #
       # HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
       # Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.

@@ -63,12 +63,12 @@ module CONTAINER
 
         # Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/containers/run/#container-identification). The UUID might be abbreviated.
         #
-        # @note Stability Level: development
+        # @note Stability Level: beta
         CONTAINER_ID = 'container.id'
 
         # Runtime specific image identifier. Usually a hash algorithm followed by a UUID.
         #
-        # Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/reference/api/engine/version/v1.43/#tag/Container/operation/ContainerInspect) endpoint.
+        # Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/reference/api/engine/version/v1.52/#tag/Container/operation/ContainerInspect) endpoint.
         # K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`.
         # The ID is assigned by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes.
         #
@@ -77,19 +77,19 @@ module CONTAINER
 
         # Name of the image the container was built on.
         #
-        # @note Stability Level: development
+        # @note Stability Level: beta
         CONTAINER_IMAGE_NAME = 'container.image.name'
 
         # Repo digests of the container image as provided by the container runtime.
         #
-        # [Docker](https://docs.docker.com/reference/api/engine/version/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
+        # [Docker](https://docs.docker.com/reference/api/engine/version/v1.52/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
         #
-        # @note Stability Level: development
+        # @note Stability Level: beta
         CONTAINER_IMAGE_REPO_DIGESTS = 'container.image.repo_digests'
 
-        # Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/reference/api/engine/version/v1.43/#tag/Image/operation/ImageInspect). Should be only the `<tag>` section of the full name for example from `registry.example.com/my-org/my-image:<tag>`.
+        # Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/reference/api/engine/version/v1.52/#tag/Image/operation/ImageInspect). Should be only the `<tag>` section of the full name for example from `registry.example.com/my-org/my-image:<tag>`.
         #
-        # @note Stability Level: development
+        # @note Stability Level: beta
         CONTAINER_IMAGE_TAGS = 'container.image.tags'
 
         # Must be called with a key for the full attribute name. See notes below about the expectations

@@ -328,17 +328,22 @@ module DB
         # Summary may be available to the instrumentation through
         # instrumentation hooks or other means. If it is not available, instrumentations
         # that support query parsing SHOULD generate a summary following
-        # [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query)
+        # [Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query)
         # section.
         #
+        # For batch operations, if the individual operations are known to have the same query summary
+        # then that query summary SHOULD be used prepended by `BATCH `,
+        # otherwise `db.query.summary` SHOULD be `BATCH` or some other database
+        # system specific term if more applicable.
+        #
         # @note Stability Level: stable
         #
         # @deprecated Now available in the stable namespace at {OpenTelemetry::SemConv::DB::DB_QUERY_SUMMARY}.
         DB_QUERY_SUMMARY = 'db.query.summary'
 
         # The database query being executed.
         #
-        # For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext).
+        # For sanitization see [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext).
         # For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
         # Parameterized query text SHOULD NOT be sanitized. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
         #

@@ -33,6 +33,7 @@ module ERROR
         # `error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status.
         #
         # @note Stability Level: development
+        # @deprecated Use domain-specific error message attribute. For example, use `feature_flag.error.message` for feature flag errors.
         ERROR_MESSAGE = 'error.message'
 
         # Describes a class of error the operation ended with.
@@ -51,7 +52,7 @@ module ERROR
         #
         # If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
         #
-        # If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
+        # If a specific domain defines its own set of error identifiers (such as HTTP or RPC status codes),
         # it's RECOMMENDED to:
         #
         # - Use a domain-specific attribute

@@ -32,6 +32,8 @@ module EXCEPTION
 
         # The exception message.
         #
+        # > [!WARNING]> This attribute may contain sensitive information.
+        #
         # @note Stability Level: stable
         #
         # @deprecated Now available in the stable namespace at {OpenTelemetry::SemConv::EXCEPTION::EXCEPTION_MESSAGE}.

@@ -29,10 +29,15 @@ module FEATURE_FLAG
         # @note Stability Level: release_candidate
         FEATURE_FLAG_CONTEXT_ID = 'feature_flag.context.id'
 
-        # Deprecated, use `error.message` instead.
+        # A message providing more detail about an error that occurred during feature flag evaluation in human-readable form.
+        #
+        # @note Stability Level: release_candidate
+        FEATURE_FLAG_ERROR_MESSAGE = 'feature_flag.error.message'
+
+        # Deprecated, use `feature_flag.error.message` instead.
         #
         # @note Stability Level: development
-        # @deprecated Replaced by `error.message`.
+        # @deprecated Replaced by `feature_flag.error.message`.
         FEATURE_FLAG_EVALUATION_ERROR_MESSAGE = 'feature_flag.evaluation.error.message'
 
         # Deprecated, use `feature_flag.result.reason` instead.

@@ -149,6 +149,21 @@ module GCP
         # @note Stability Level: development
         GCP_GCE_INSTANCE_NAME = 'gcp.gce.instance.name'
 
+        # The name of the Instance Group Manager (IGM) that manages this VM, if any.
+        #
+        # @note Stability Level: development
+        GCP_GCE_INSTANCE_GROUP_MANAGER_NAME = 'gcp.gce.instance_group_manager.name'
+
+        # The region of a **regional** Instance Group Manager (e.g., `us-central1`). Set this **only** when the IGM is regional.
+        #
+        # @note Stability Level: development
+        GCP_GCE_INSTANCE_GROUP_MANAGER_REGION = 'gcp.gce.instance_group_manager.region'
+
+        # The zone of a **zonal** Instance Group Manager (e.g., `us-central1-a`). Set this **only** when the IGM is zonal.
+        #
+        # @note Stability Level: development
+        GCP_GCE_INSTANCE_GROUP_MANAGER_ZONE = 'gcp.gce.instance_group_manager.zone'
+
         # @!endgroup
       end
     end

@@ -39,6 +39,11 @@ module GEN_AI
         # @note Stability Level: development
         GEN_AI_AGENT_NAME = 'gen_ai.agent.name'
 
+        # The version of the GenAI agent.
+        #
+        # @note Stability Level: development
+        GEN_AI_AGENT_VERSION = 'gen_ai.agent.version'
+
         # Deprecated, use Event API to report completions contents.
         #
         # @note Stability Level: development
@@ -181,6 +186,11 @@ module GEN_AI
         # @deprecated Removed, no replacement at this time.
         GEN_AI_PROMPT = 'gen_ai.prompt'
 
+        # The name of the prompt that uniquely identifies it.
+        #
+        # @note Stability Level: development
+        GEN_AI_PROMPT_NAME = 'gen_ai.prompt.name'
+
         # The Generative AI provider as identified by the client or server instrumentation.
         #
         # The attribute SHOULD be set based on the instrumentation's best
@@ -277,6 +287,27 @@ module GEN_AI
         # @note Stability Level: development
         GEN_AI_RESPONSE_MODEL = 'gen_ai.response.model'
 
+        # The documents retrieved.
+        #
+        # Instrumentations MUST follow [Retrieval documents JSON schema](/docs/gen-ai/gen-ai-retrieval-documents.json).
+        # When the attribute is recorded on events, it MUST be recorded in structured
+        # form. When recorded on spans, it MAY be recorded as a JSON string if structured
+        # format is not supported and SHOULD be recorded in structured form otherwise.
+        #
+        # Each document object SHOULD contain at least the following properties:
+        # `id` (string): A unique identifier for the document, `score` (double): The relevance score of the document
+        #
+        # @note Stability Level: development
+        GEN_AI_RETRIEVAL_DOCUMENTS = 'gen_ai.retrieval.documents'
+
+        # The query text used for retrieval.
+        #
+        # > [!Warning]
+        # > This attribute may contain sensitive information.
+        #
+        # @note Stability Level: development
+        GEN_AI_RETRIEVAL_QUERY_TEXT = 'gen_ai.retrieval.query.text'
+
         # Deprecated, use `gen_ai.provider.name` instead.
         #
         # @note Stability Level: development
@@ -379,6 +410,20 @@ module GEN_AI
         # @note Stability Level: development
         GEN_AI_TOOL_TYPE = 'gen_ai.tool.type'
 
+        # The number of input tokens written to a provider-managed cache.
+        #
+        # The value SHOULD be included in `gen_ai.usage.input_tokens`.
+        #
+        # @note Stability Level: development
+        GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = 'gen_ai.usage.cache_creation.input_tokens'
+
+        # The number of input tokens served from a provider-managed cache.
+        #
+        # The value SHOULD be included in `gen_ai.usage.input_tokens`.
+        #
+        # @note Stability Level: development
+        GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = 'gen_ai.usage.cache_read.input_tokens'
+
         # Deprecated, use `gen_ai.usage.output_tokens` instead.
         #
         # @note Stability Level: development
@@ -387,6 +432,11 @@ module GEN_AI
 
         # The number of tokens used in the GenAI input (prompt).
         #
+        # This value SHOULD include all types of input tokens, including cached tokens.
+        # Instrumentations SHOULD make a best effort to populate this value, using a total
+        # provided by the provider when available or, depending on the provider API,
+        # by summing different token types parsed from the provider output.
+        #
         # @note Stability Level: development
         GEN_AI_USAGE_INPUT_TOKENS = 'gen_ai.usage.input_tokens'
 

@@ -99,8 +99,15 @@ module HTTP
         #
         # If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override
         # the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named
-        # OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods
-        # (this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).
+        # OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods.
+        #
+        #
+        # If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property
+        # (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or
+        # `.instrumentation/development.general.http.server`.
+        #
+        # In either case, this list MUST be a full override of the default known methods,
+        # it is not a list of known methods in addition to the defaults.
         #
         # HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
         # Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# This file was autogenerated. Do not edit it by hand.
+
+require_relative 'jsonrpc/attributes'