Merge pull request #681 from open-telemetry/main

[SEMANTIC CONVENTIONS] Upgrade to semantic conventions 1.40.0 (open-telemetry#3881)

Author: malkia

CHANGELOG.md

@@ -18,6 +18,9 @@ Increment the:
 * [BUILD] Avoid break caused by max() macro on windows
   [#3863](https://github.com/open-telemetry/opentelemetry-cpp/pull/3863)
 
+* [SEMANTIC CONVENTIONS] Upgrade to semantic conventions 1.40.0
+  [#3881](https://github.com/open-telemetry/opentelemetry-cpp/pull/3881)
+
 ## [1.25 2026-02-07]
 
 * [RELEASE] Bump main branch to 1.25.0-dev (#3759)

api/include/opentelemetry/semconv/db_attributes.h

@@ -85,7 +85,10 @@ static constexpr const char *kDbOperationName = "db.operation.name";
   instrumentation hooks or other means. If it is not available, instrumentations
   that support query parsing SHOULD generate a summary following
   <a href="/docs/db/database-spans.md#generating-a-summary-of-the-query">Generating query
-  summary</a> section.
+  summary</a> section. <p> For batch operations, if the individual operations are known to have the
+  same query summary then that query summary SHOULD be used prepended by @code BATCH  @endcode,
+  otherwise @code db.query.summary @endcode SHOULD be @code BATCH @endcode or some other database
+  system specific term if more applicable.
  */
 static constexpr const char *kDbQuerySummary = "db.query.summary";
 

api/include/opentelemetry/semconv/exception_attributes.h

@@ -30,6 +30,10 @@ OPENTELEMETRY_DEPRECATED static constexpr const char *kExceptionEscaped = "excep
 
 /**
   The exception message.
+  <blockquote>
+  [!WARNING]
+  <p>
+  This attribute may contain sensitive information.</blockquote>
  */
 static constexpr const char *kExceptionMessage = "exception.message";
 

api/include/opentelemetry/semconv/http_attributes.h

@@ -53,13 +53,21 @@ static constexpr const char *kHttpRequestHeader = "http.request.header";
   could end up converting valid HTTP request methods to @code _OTHER @endcode, 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). <p> HTTP method names are case-sensitive and @code http.request.method @endcode
-  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. Tracing instrumentations that do so, MUST also set @code http.request.method_original
-  @endcode to the original value.
+  support a comma-separated list of case-sensitive known HTTP methods. <p>
+
+  If this override is done via declarative configuration, then the list MUST be configurable via the
+  @code known_methods @endcode property (an array of case-sensitive strings with minimum items 0)
+  under @code .instrumentation/development.general.http.client @endcode and/or
+  @code .instrumentation/development.general.http.server @endcode.
+  <p>
+  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.
+  <p>
+  HTTP method names are case-sensitive and @code http.request.method @endcode 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. Tracing
+  instrumentations that do so, MUST also set @code http.request.method_original @endcode to the
+  original value.
  */
 static constexpr const char *kHttpRequestMethod = "http.request.method";
 

api/include/opentelemetry/semconv/incubating/db_attributes.h

@@ -417,7 +417,10 @@ static constexpr const char *kDbQueryParameter = "db.query.parameter";
   instrumentation hooks or other means. If it is not available, instrumentations
   that support query parsing SHOULD generate a summary following
   <a href="/docs/db/database-spans.md#generating-a-summary-of-the-query">Generating query
-  summary</a> section.
+  summary</a> section. <p> For batch operations, if the individual operations are known to have the
+  same query summary then that query summary SHOULD be used prepended by @code BATCH  @endcode,
+  otherwise @code db.query.summary @endcode SHOULD be @code BATCH @endcode or some other database
+  system specific term if more applicable.
  */
 static constexpr const char *kDbQuerySummary = "db.query.summary";
 

api/include/opentelemetry/semconv/incubating/error_attributes.h

@@ -21,15 +21,18 @@ namespace error
 
 /**
   A message providing more detail about an error in human-readable form.
-  <p>
+
+  @deprecated
+  {"note": "Use domain-specific error message attribute. For example, use @code
+  feature_flag.error.message @endcode for feature flag errors.", "reason": "obsoleted"} <p>
   @code error.message @endcode should provide additional context and detail about an error.
   It is NOT RECOMMENDED to duplicate the value of @code error.type @endcode in @code error.message
   @endcode. It is also NOT RECOMMENDED to duplicate the value of @code exception.message @endcode in
   @code error.message @endcode. <p>
   @code error.message @endcode is NOT RECOMMENDED for metrics or spans due to its unbounded
   cardinality and overlap with span status.
  */
-static constexpr const char *kErrorMessage = "error.message";
+OPENTELEMETRY_DEPRECATED static constexpr const char *kErrorMessage = "error.message";
 
 /**
   Describes a class of error the operation ended with.

api/include/opentelemetry/semconv/incubating/exception_attributes.h

@@ -30,6 +30,10 @@ OPENTELEMETRY_DEPRECATED static constexpr const char *kExceptionEscaped = "excep
 
 /**
   The exception message.
+  <blockquote>
+  [!WARNING]
+  <p>
+  This attribute may contain sensitive information.</blockquote>
  */
 static constexpr const char *kExceptionMessage = "exception.message";
 

api/include/opentelemetry/semconv/incubating/feature_flag_attributes.h

@@ -25,11 +25,17 @@ namespace feature_flag
 static constexpr const char *kFeatureFlagContextId = "feature_flag.context.id";
 
 /**
-  Deprecated, use @code error.message @endcode instead.
+  A message providing more detail about an error that occurred during feature flag evaluation in
+  human-readable form.
+ */
+static constexpr const char *kFeatureFlagErrorMessage = "feature_flag.error.message";
+
+/**
+  Deprecated, use @code feature_flag.error.message @endcode instead.
 
   @deprecated
-  {"note": "Replaced by @code error.message @endcode.", "reason": "renamed", "renamed_to":
-  "error.message"}
+  {"note": "Replaced by @code feature_flag.error.message @endcode.", "reason": "renamed",
+  "renamed_to": "feature_flag.error.message"}
  */
 OPENTELEMETRY_DEPRECATED static constexpr const char *kFeatureFlagEvaluationErrorMessage =
     "feature_flag.evaluation.error.message";

api/include/opentelemetry/semconv/incubating/gcp_attributes.h

@@ -180,6 +180,26 @@ static constexpr const char *kGcpGceInstanceHostname = "gcp.gce.instance.hostnam
  */
 static constexpr const char *kGcpGceInstanceName = "gcp.gce.instance.name";
 
+/**
+  The name of the Instance Group Manager (IGM) that manages this VM, if any.
+ */
+static constexpr const char *kGcpGceInstanceGroupManagerName =
+    "gcp.gce.instance_group_manager.name";
+
+/**
+  The region of a <strong>regional</strong> Instance Group Manager (e.g., @code us-central1
+  @endcode). Set this <strong>only</strong> when the IGM is regional.
+ */
+static constexpr const char *kGcpGceInstanceGroupManagerRegion =
+    "gcp.gce.instance_group_manager.region";
+
+/**
+  The zone of a <strong>zonal</strong> Instance Group Manager (e.g., @code us-central1-a @endcode).
+  Set this <strong>only</strong> when the IGM is zonal.
+ */
+static constexpr const char *kGcpGceInstanceGroupManagerZone =
+    "gcp.gce.instance_group_manager.zone";
+
 namespace GcpApphubServiceCriticalityTypeValues
 {
 /**

api/include/opentelemetry/semconv/incubating/gen_ai_attributes.h

@@ -34,6 +34,11 @@ static constexpr const char *kGenAiAgentId = "gen_ai.agent.id";
  */
 static constexpr const char *kGenAiAgentName = "gen_ai.agent.name";
 
+/**
+  The version of the GenAI agent.
+ */
+static constexpr const char *kGenAiAgentVersion = "gen_ai.agent.version";
+
 /**
   Deprecated, use Event API to report completions contents.
 
@@ -311,6 +316,27 @@ static constexpr const char *kGenAiResponseId = "gen_ai.response.id";
  */
 static constexpr const char *kGenAiResponseModel = "gen_ai.response.model";
 
+/**
+  The documents retrieved.
+  <p>
+  Instrumentations MUST follow <a href="/docs/gen-ai/gen-ai-retrieval-documents.json">Retrieval
+  documents JSON schema</a>. 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. <p> Each document object
+  SHOULD contain at least the following properties:
+  @code id @endcode (string): A unique identifier for the document, @code score @endcode (double):
+  The relevance score of the document
+ */
+static constexpr const char *kGenAiRetrievalDocuments = "gen_ai.retrieval.documents";
+
+/**
+  The query text used for retrieval.
+  <blockquote>
+  [!Warning]
+  This attribute may contain sensitive information.</blockquote>
+ */
+static constexpr const char *kGenAiRetrievalQueryText = "gen_ai.retrieval.query.text";
+
 /**
   Deprecated, use @code gen_ai.provider.name @endcode instead.
 
@@ -418,6 +444,22 @@ static constexpr const char *kGenAiToolName = "gen_ai.tool.name";
  */
 static constexpr const char *kGenAiToolType = "gen_ai.tool.type";
 
+/**
+  The number of input tokens written to a provider-managed cache.
+  <p>
+  The value SHOULD be included in @code gen_ai.usage.input_tokens @endcode.
+ */
+static constexpr const char *kGenAiUsageCacheCreationInputTokens =
+    "gen_ai.usage.cache_creation.input_tokens";
+
+/**
+  The number of input tokens served from a provider-managed cache.
+  <p>
+  The value SHOULD be included in @code gen_ai.usage.input_tokens @endcode.
+ */
+static constexpr const char *kGenAiUsageCacheReadInputTokens =
+    "gen_ai.usage.cache_read.input_tokens";
+
 /**
   Deprecated, use @code gen_ai.usage.output_tokens @endcode instead.
 
@@ -430,6 +472,11 @@ OPENTELEMETRY_DEPRECATED static constexpr const char *kGenAiUsageCompletionToken
 
 /**
   The number of tokens used in the GenAI input (prompt).
+  <p>
+  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.
  */
 static constexpr const char *kGenAiUsageInputTokens = "gen_ai.usage.input_tokens";
 
@@ -509,6 +556,13 @@ static constexpr const char *kTextCompletion = "text_completion";
  */
 static constexpr const char *kEmbeddings = "embeddings";
 
+/**
+  Retrieval operation such as <a
+  href="https://platform.openai.com/docs/api-reference/vector-stores/search">OpenAI Search Vector
+  Store API</a>
+ */
+static constexpr const char *kRetrieval = "retrieval";
+
 /**
   Create GenAI agent
  */