Merge branch 'main' into docs/clarify-log-processor-error-handling

Author: xrmx

CHANGELOG.md

@@ -14,6 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `opentelemetry-sdk`: Clarify log processor error handling expectations in documentation
   ([#4915](https://github.com/open-telemetry/opentelemetry-python/pull/4915))
+- bump semantic-conventions to v1.40.0
+  ([#4941](https://github.com/open-telemetry/opentelemetry-python/pull/4941))
 - Add stale PR GitHub Action
   ([#4926](https://github.com/open-telemetry/opentelemetry-python/pull/4926))
 - `opentelemetry-sdk`: Drop unused Jaeger exporter environment variables (exporter removed in 1.22.0)

opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/error_attributes.py

@@ -19,12 +19,7 @@
 
 ERROR_MESSAGE: Final = "error.message"
 """
-A message providing more detail about an error in human-readable form.
-Note: `error.message` should provide additional context and detail about an error.
-It is NOT RECOMMENDED to duplicate the value of `error.type` in `error.message`.
-It is also NOT RECOMMENDED to duplicate the value of `exception.message` in `error.message`.
-
-`error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status.
+Deprecated: Use domain-specific error message attribute. For example, use `feature_flag.error.message` for feature flag errors.
 """
 
 ERROR_TYPE: Final = "error.type"

opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/feature_flag_attributes.py

@@ -22,11 +22,16 @@
 The unique identifier for the flag evaluation context. For example, the targeting key.
 """
 
+FEATURE_FLAG_ERROR_MESSAGE: Final = "feature_flag.error.message"
+"""
+A message providing more detail about an error that occurred during feature flag evaluation in human-readable form.
+"""
+
 FEATURE_FLAG_EVALUATION_ERROR_MESSAGE: Final = (
     "feature_flag.evaluation.error.message"
 )
 """
-Deprecated: Replaced by `error.message`.
+Deprecated: Replaced by `feature_flag.error.message`.
 """
 
 FEATURE_FLAG_EVALUATION_REASON: Final = "feature_flag.evaluation.reason"

opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/gcp_attributes.py

@@ -159,6 +159,27 @@
 The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names).
 """
 
+GCP_GCE_INSTANCE_GROUP_MANAGER_NAME: Final = (
+    "gcp.gce.instance_group_manager.name"
+)
+"""
+The name of the Instance Group Manager (IGM) that manages this VM, if any.
+"""
+
+GCP_GCE_INSTANCE_GROUP_MANAGER_REGION: Final = (
+    "gcp.gce.instance_group_manager.region"
+)
+"""
+The region of a **regional** Instance Group Manager (e.g., `us-central1`). Set this **only** when the IGM is regional.
+"""
+
+GCP_GCE_INSTANCE_GROUP_MANAGER_ZONE: Final = (
+    "gcp.gce.instance_group_manager.zone"
+)
+"""
+The zone of a **zonal** Instance Group Manager (e.g., `us-central1-a`). Set this **only** when the IGM is zonal.
+"""
+
 
 class GcpApphubServiceCriticalityTypeValues(Enum):
     MISSION_CRITICAL = "MISSION_CRITICAL"

opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/gen_ai_attributes.py

@@ -32,6 +32,11 @@
 Human-readable name of the GenAI agent provided by the application.
 """
 
+GEN_AI_AGENT_VERSION: Final = "gen_ai.agent.version"
+"""
+The version of the GenAI agent.
+"""
+
 GEN_AI_COMPLETION: Final = "gen_ai.completion"
 """
 Deprecated: Removed, no replacement at this time.
@@ -268,6 +273,25 @@
 The name of the model that generated the response.
 """
 
+GEN_AI_RETRIEVAL_DOCUMENTS: Final = "gen_ai.retrieval.documents"
+"""
+The documents retrieved.
+Note: 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.
+"""
+
+GEN_AI_RETRIEVAL_QUERY_TEXT: Final = "gen_ai.retrieval.query.text"
+"""
+The query text used for retrieval.
+Note: > [!Warning]
+> This attribute may contain sensitive information.
+"""
+
 GEN_AI_SYSTEM: Final = "gen_ai.system"
 """
 Deprecated: Replaced by `gen_ai.provider.name`.
@@ -364,6 +388,22 @@
 Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates.
 """
 
+GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS: Final = (
+    "gen_ai.usage.cache_creation.input_tokens"
+)
+"""
+The number of input tokens written to a provider-managed cache.
+Note: The value SHOULD be included in `gen_ai.usage.input_tokens`.
+"""
+
+GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS: Final = (
+    "gen_ai.usage.cache_read.input_tokens"
+)
+"""
+The number of input tokens served from a provider-managed cache.
+Note: The value SHOULD be included in `gen_ai.usage.input_tokens`.
+"""
+
 GEN_AI_USAGE_COMPLETION_TOKENS: Final = "gen_ai.usage.completion_tokens"
 """
 Deprecated: Replaced by `gen_ai.usage.output_tokens`.
@@ -372,6 +412,10 @@
 GEN_AI_USAGE_INPUT_TOKENS: Final = "gen_ai.usage.input_tokens"
 """
 The number of tokens used in the GenAI input (prompt).
+Note: 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.
 """
 
 GEN_AI_USAGE_OUTPUT_TOKENS: Final = "gen_ai.usage.output_tokens"
@@ -416,6 +460,8 @@ class GenAiOperationNameValues(Enum):
     """Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions)."""
     EMBEDDINGS = "embeddings"
     """Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create)."""
+    RETRIEVAL = "retrieval"
+    """Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search)."""
     CREATE_AGENT = "create_agent"
     """Create GenAI agent."""
     INVOKE_AGENT = "invoke_agent"

opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/k8s_attributes.py

@@ -468,6 +468,113 @@
 The UID of the resource quota.
 """
 
+K8S_SERVICE_ANNOTATION_TEMPLATE: Final = "k8s.service.annotation"
+"""
+The annotation placed on the Service, the `<key>` being the annotation name, the value being the annotation value, even if the value is empty.
+Note: Examples:
+
+- An annotation `prometheus.io/scrape` with value `true` SHOULD be recorded as
+  the `k8s.service.annotation.prometheus.io/scrape` attribute with value `"true"`.
+- An annotation `data` with empty string value SHOULD be recorded as
+  the `k8s.service.annotation.data` attribute with value `""`.
+"""
+
+K8S_SERVICE_ENDPOINT_ADDRESS_TYPE: Final = "k8s.service.endpoint.address_type"
+"""
+The address type of the service endpoint.
+Note: The network address family or type of the endpoint.
+This attribute aligns with the `addressType` field of the
+[K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/).
+It is used to differentiate metrics when a Service is backed by multiple address types
+(e.g., in dual-stack clusters).
+"""
+
+K8S_SERVICE_ENDPOINT_CONDITION: Final = "k8s.service.endpoint.condition"
+"""
+The condition of the service endpoint.
+Note: The current operational condition of the service endpoint.
+An endpoint can have multiple conditions set at once (e.g., both `serving` and `terminating` during rollout).
+This attribute aligns with the condition fields in the [K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/).
+"""
+
+K8S_SERVICE_ENDPOINT_ZONE: Final = "k8s.service.endpoint.zone"
+"""
+The zone of the service endpoint.
+Note: The zone where the endpoint is located, typically corresponding to a failure domain.
+This attribute aligns with the `zone` field of endpoints in the
+[K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/).
+It enables zone-aware monitoring of service endpoint distribution and supports
+features like [Topology Aware Routing](https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/).
+
+If the zone is not populated (e.g., nodes without the `topology.kubernetes.io/zone` label),
+the attribute value will be an empty string.
+"""
+
+K8S_SERVICE_LABEL_TEMPLATE: Final = "k8s.service.label"
+"""
+The label placed on the Service, the `<key>` being the label name, the value being the label value, even if the value is empty.
+Note: Examples:
+
+- A label `app` with value `my-service` SHOULD be recorded as
+  the `k8s.service.label.app` attribute with value `"my-service"`.
+- A label `data` with empty string value SHOULD be recorded as
+  the `k8s.service.label.data` attribute with value `""`.
+"""
+
+K8S_SERVICE_NAME: Final = "k8s.service.name"
+"""
+The name of the Service.
+"""
+
+K8S_SERVICE_PUBLISH_NOT_READY_ADDRESSES: Final = (
+    "k8s.service.publish_not_ready_addresses"
+)
+"""
+Whether the Service publishes not-ready endpoints.
+Note: 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 `publishNotReadyAddresses` field of the
+[K8s ServiceSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec).
+"""
+
+K8S_SERVICE_SELECTOR_TEMPLATE: Final = "k8s.service.selector"
+"""
+The selector key-value pair placed on the Service, the `<key>` being the selector key, the value being the selector value.
+Note: These selectors are used to correlate with pod labels. Each selector key-value pair becomes a separate attribute.
+
+Examples:
+
+- A selector `app=my-app` SHOULD be recorded as
+  the `k8s.service.selector.app` attribute with value `"my-app"`.
+- A selector `version=v1` SHOULD be recorded as
+  the `k8s.service.selector.version` attribute with value `"v1"`.
+"""
+
+K8S_SERVICE_TRAFFIC_DISTRIBUTION: Final = "k8s.service.traffic_distribution"
+"""
+The traffic distribution policy for the Service.
+Note: Specifies how traffic is distributed to endpoints for this Service.
+This attribute aligns with the `trafficDistribution` field of the
+[K8s ServiceSpec](https://kubernetes.io/docs/reference/networking/virtual-ips/#traffic-distribution).
+Known values include `PreferSameZone` (prefer endpoints in the same zone as the client) and
+`PreferSameNode` (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.
+"""
+
+K8S_SERVICE_TYPE: Final = "k8s.service.type"
+"""
+The type of the Kubernetes Service.
+Note: This attribute aligns with the `type` field of the
+[K8s ServiceSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec).
+"""
+
+K8S_SERVICE_UID: Final = "k8s.service.uid"
+"""
+The UID of the Service.
+"""
+
 K8S_STATEFULSET_ANNOTATION_TEMPLATE: Final = "k8s.statefulset.annotation"
 """
 The annotation placed on the StatefulSet, the `<key>` being the annotation name, the value being the annotation value, even if the value is empty.
@@ -601,6 +708,35 @@ class K8sPodStatusReasonValues(Enum):
     """The pod was rejected admission to the node because of an error during admission that could not be categorized."""
 
 
+class K8sServiceEndpointAddressTypeValues(Enum):
+    IPV4 = "IPv4"
+    """IPv4 address type."""
+    IPV6 = "IPv6"
+    """IPv6 address type."""
+    FQDN = "FQDN"
+    """FQDN address type."""
+
+
+class K8sServiceEndpointConditionValues(Enum):
+    READY = "ready"
+    """The endpoint is ready to receive new connections."""
+    SERVING = "serving"
+    """The endpoint is currently handling traffic."""
+    TERMINATING = "terminating"
+    """The endpoint is in the process of shutting down."""
+
+
+class K8sServiceTypeValues(Enum):
+    CLUSTER_IP = "ClusterIP"
+    """ClusterIP service type."""
+    NODE_PORT = "NodePort"
+    """NodePort service type."""
+    LOAD_BALANCER = "LoadBalancer"
+    """LoadBalancer service type."""
+    EXTERNAL_NAME = "ExternalName"
+    """ExternalName service type."""
+
+
 class K8sVolumeTypeValues(Enum):
     PERSISTENT_VOLUME_CLAIM = "persistentVolumeClaim"
     """A [persistentVolumeClaim](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume."""

opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/message_attributes.py

@@ -19,27 +19,27 @@
 
 MESSAGE_COMPRESSED_SIZE: Final = "message.compressed_size"
 """
-Deprecated: Replaced by `rpc.message.compressed_size`.
+Deprecated: Deprecated, no replacement at this time.
 """
 
 MESSAGE_ID: Final = "message.id"
 """
-Deprecated: Replaced by `rpc.message.id`.
+Deprecated: Deprecated, no replacement at this time.
 """
 
 MESSAGE_TYPE: Final = "message.type"
 """
-Deprecated: Replaced by `rpc.message.type`.
+Deprecated: Deprecated, no replacement at this time.
 """
 
 MESSAGE_UNCOMPRESSED_SIZE: Final = "message.uncompressed_size"
 """
-Deprecated: Replaced by `rpc.message.uncompressed_size`.
+Deprecated: Deprecated, no replacement at this time.
 """
 
 
 @deprecated(
-    "The attribute message.type is deprecated - Replaced by `rpc.message.type`"
+    "The attribute message.type is deprecated - Deprecated, no replacement at this time"
 )
 class MessageTypeValues(Enum):
     SENT = "SENT"

opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/openai_attributes.py

@@ -15,6 +15,11 @@
 from enum import Enum
 from typing import Final
 
+OPENAI_API_TYPE: Final = "openai.api.type"
+"""
+The type of OpenAI API being used.
+"""
+
 OPENAI_REQUEST_SERVICE_TIER: Final = "openai.request.service_tier"
 """
 The service tier requested. May be a specific tier, default, or auto.
@@ -33,6 +38,13 @@
 """
 
 
+class OpenaiApiTypeValues(Enum):
+    CHAT_COMPLETIONS = "chat_completions"
+    """The OpenAI [Chat Completions API](https://developers.openai.com/api/reference/chat-completions/overview)."""
+    RESPONSES = "responses"
+    """The OpenAI [Responses API](https://developers.openai.com/api/reference/responses/overview)."""
+
+
 class OpenaiRequestServiceTierValues(Enum):
     AUTO = "auto"
     """The system will utilize scale tier credits until they are exhausted."""