diff --git a/CHANGELOG.md b/CHANGELOG.md index 07005073f4..bfe4603421 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/api/include/opentelemetry/semconv/db_attributes.h b/api/include/opentelemetry/semconv/db_attributes.h index 67abc8a669..f9fc8ed8ff 100644 --- a/api/include/opentelemetry/semconv/db_attributes.h +++ b/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 Generating query - summary section. + summary 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 @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"; diff --git a/api/include/opentelemetry/semconv/exception_attributes.h b/api/include/opentelemetry/semconv/exception_attributes.h index 8947d711f1..15b5cde060 100644 --- a/api/include/opentelemetry/semconv/exception_attributes.h +++ b/api/include/opentelemetry/semconv/exception_attributes.h @@ -30,6 +30,10 @@ OPENTELEMETRY_DEPRECATED static constexpr const char *kExceptionEscaped = "excep /** The exception message. +

+ [!WARNING] +

+ This attribute may contain sensitive information.

*/ static constexpr const char *kExceptionMessage = "exception.message"; diff --git a/api/include/opentelemetry/semconv/http_attributes.h b/api/include/opentelemetry/semconv/http_attributes.h index b815b5d6b8..6f7bbd3f9d 100644 --- a/api/include/opentelemetry/semconv/http_attributes.h +++ b/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).

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.

+ + 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. +

+ 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 @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"; diff --git a/api/include/opentelemetry/semconv/incubating/db_attributes.h b/api/include/opentelemetry/semconv/incubating/db_attributes.h index 0384eab4cd..8be4d501e9 100644 --- a/api/include/opentelemetry/semconv/incubating/db_attributes.h +++ b/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 Generating query - summary section. + summary 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 @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"; diff --git a/api/include/opentelemetry/semconv/incubating/error_attributes.h b/api/include/opentelemetry/semconv/incubating/error_attributes.h index 2efa4b4876..ff42fadcbf 100644 --- a/api/include/opentelemetry/semconv/incubating/error_attributes.h +++ b/api/include/opentelemetry/semconv/incubating/error_attributes.h @@ -21,7 +21,10 @@ namespace error /** A message providing more detail about an error in human-readable form. -

+ + @deprecated + {"note": "Use domain-specific error message attribute. For example, use @code + feature_flag.error.message @endcode for feature flag errors.", "reason": "obsoleted"}

@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 @@ -29,7 +32,7 @@ namespace error @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. diff --git a/api/include/opentelemetry/semconv/incubating/exception_attributes.h b/api/include/opentelemetry/semconv/incubating/exception_attributes.h index 8947d711f1..15b5cde060 100644 --- a/api/include/opentelemetry/semconv/incubating/exception_attributes.h +++ b/api/include/opentelemetry/semconv/incubating/exception_attributes.h @@ -30,6 +30,10 @@ OPENTELEMETRY_DEPRECATED static constexpr const char *kExceptionEscaped = "excep /** The exception message. +

+ [!WARNING] +

+ This attribute may contain sensitive information.

*/ static constexpr const char *kExceptionMessage = "exception.message"; diff --git a/api/include/opentelemetry/semconv/incubating/feature_flag_attributes.h b/api/include/opentelemetry/semconv/incubating/feature_flag_attributes.h index f80c0ad4cb..767f1e54c1 100644 --- a/api/include/opentelemetry/semconv/incubating/feature_flag_attributes.h +++ b/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"; diff --git a/api/include/opentelemetry/semconv/incubating/gcp_attributes.h b/api/include/opentelemetry/semconv/incubating/gcp_attributes.h index 74ddef337d..f0d92164b4 100644 --- a/api/include/opentelemetry/semconv/incubating/gcp_attributes.h +++ b/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 regional Instance Group Manager (e.g., @code us-central1 + @endcode). Set this only when the IGM is regional. + */ +static constexpr const char *kGcpGceInstanceGroupManagerRegion = + "gcp.gce.instance_group_manager.region"; + +/** + The zone of a zonal Instance Group Manager (e.g., @code us-central1-a @endcode). + Set this only when the IGM is zonal. + */ +static constexpr const char *kGcpGceInstanceGroupManagerZone = + "gcp.gce.instance_group_manager.zone"; + namespace GcpApphubServiceCriticalityTypeValues { /** diff --git a/api/include/opentelemetry/semconv/incubating/gen_ai_attributes.h b/api/include/opentelemetry/semconv/incubating/gen_ai_attributes.h index d7407c4143..1ff125dddb 100644 --- a/api/include/opentelemetry/semconv/incubating/gen_ai_attributes.h +++ b/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. +

+ Instrumentations MUST follow Retrieval + documents JSON schema. 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: + @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. +

+ [!Warning] + This attribute may contain sensitive information.
+ */ +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. +

+ 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. +

+ 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). +

+ 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 OpenAI Search Vector + Store API + */ +static constexpr const char *kRetrieval = "retrieval"; + /** Create GenAI agent */ diff --git a/api/include/opentelemetry/semconv/incubating/http_attributes.h b/api/include/opentelemetry/semconv/incubating/http_attributes.h index 1af52bbb62..acdb1a8927 100644 --- a/api/include/opentelemetry/semconv/incubating/http_attributes.h +++ b/api/include/opentelemetry/semconv/incubating/http_attributes.h @@ -104,13 +104,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).

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.

+ + 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. +

+ 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 @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"; diff --git a/api/include/opentelemetry/semconv/incubating/k8s_attributes.h b/api/include/opentelemetry/semconv/incubating/k8s_attributes.h index b3361f3519..208b47d3c6 100644 --- a/api/include/opentelemetry/semconv/incubating/k8s_attributes.h +++ b/api/include/opentelemetry/semconv/incubating/k8s_attributes.h @@ -510,6 +510,126 @@ static constexpr const char *kK8sResourcequotaResourceName = "k8s.resourcequota. */ static constexpr const char *kK8sResourcequotaUid = "k8s.resourcequota.uid"; +/** + The annotation placed on the Service, the @code @endcode being the annotation name, the + value being the annotation value, even if the value is empty.

Examples:

+ */ +static constexpr const char *kK8sServiceAnnotation = "k8s.service.annotation"; + +/** + The address type of the service endpoint. +

+ The network address family or type of the endpoint. + This attribute aligns with the @code addressType @endcode field of the + K8s + EndpointSlice. It is used to differentiate metrics when a Service is backed by multiple + address types (e.g., in dual-stack clusters). + */ +static constexpr const char *kK8sServiceEndpointAddressType = "k8s.service.endpoint.address_type"; + +/** + The condition of the service endpoint. +

+ The current operational condition of the service endpoint. + An endpoint can have multiple conditions set at once (e.g., both @code serving @endcode and @code + terminating @endcode during rollout). This attribute aligns with the condition fields in the K8s + EndpointSlice. + */ +static constexpr const char *kK8sServiceEndpointCondition = "k8s.service.endpoint.condition"; + +/** + The zone of the service endpoint. +

+ The zone where the endpoint is located, typically corresponding to a failure domain. + This attribute aligns with the @code zone @endcode field of endpoints in the + K8s + EndpointSlice. It enables zone-aware monitoring of service endpoint distribution and supports + features like Topology + Aware Routing.

If the zone is not populated (e.g., nodes without the @code + topology.kubernetes.io/zone @endcode label), the attribute value will be an empty string. + */ +static constexpr const char *kK8sServiceEndpointZone = "k8s.service.endpoint.zone"; + +/** + The label placed on the Service, the @code @endcode being the label name, the value being + the label value, even if the value is empty.

Examples:

+ */ +static constexpr const char *kK8sServiceLabel = "k8s.service.label"; + +/** + The name of the Service. + */ +static constexpr const char *kK8sServiceName = "k8s.service.name"; + +/** + Whether the Service publishes not-ready endpoints. +

+ Whether the Service is configured to publish endpoints before the pods are ready. + This attribute is typically used to indicate that a Service (such as a headless + Service for a StatefulSet) allows peer discovery before pods pass their readiness probes. + It aligns with the @code publishNotReadyAddresses @endcode field of the + K8s + ServiceSpec. + */ +static constexpr const char *kK8sServicePublishNotReadyAddresses = + "k8s.service.publish_not_ready_addresses"; + +/** + The selector key-value pair placed on the Service, the @code @endcode being the selector + key, the value being the selector value.

These selectors are used to correlate with pod + labels. Each selector key-value pair becomes a separate attribute.

Examples:

+ */ +static constexpr const char *kK8sServiceSelector = "k8s.service.selector"; + +/** + The traffic distribution policy for the Service. +

+ Specifies how traffic is distributed to endpoints for this Service. + This attribute aligns with the @code trafficDistribution @endcode field of the + K8s + ServiceSpec. Known values include @code PreferSameZone @endcode (prefer endpoints in the same + zone as the client) and + @code PreferSameNode @endcode (prefer endpoints on the same node, fallback to same zone, then + cluster-wide). If this field is not set on the Service, the attribute SHOULD NOT be emitted. When + not set, Kubernetes distributes traffic evenly across all endpoints cluster-wide. + */ +static constexpr const char *kK8sServiceTrafficDistribution = "k8s.service.traffic_distribution"; + +/** + The type of the Kubernetes Service. +

+ This attribute aligns with the @code type @endcode field of the + K8s + ServiceSpec. + */ +static constexpr const char *kK8sServiceType = "k8s.service.type"; + +/** + The UID of the Service. + */ +static constexpr const char *kK8sServiceUid = "k8s.service.uid"; + /** The annotation placed on the StatefulSet, the @code @endcode being the annotation name, the value being the annotation value, even if the value is empty.

Examples: