opentelemetry-semantic-conventions: Bump semantic conventions to 1.29.0 (open-telemetry#4337)

* opentelemetry-semantic-conventions: Bump semantic conventions to 1.29.0

* Add changelog

Author: xrmx

CHANGELOG.md

@@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#4310](https://github.com/open-telemetry/opentelemetry-python/pull/4310))
 - sdk: instantiate lazily `ExemplarBucket`s in `ExemplarReservoir`s
   ([#4260](https://github.com/open-telemetry/opentelemetry-python/pull/4260))
+- semantic-conventions: Bump to 1.29.0
+  ([#4337](https://github.com/open-telemetry/opentelemetry-python/pull/4337))
 
 ## Version 1.28.0/0.49b0 (2024-11-05)
 

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

@@ -27,7 +27,7 @@
 
 CICD_PIPELINE_TASK_NAME: Final = "cicd.pipeline.task.name"
 """
-The human readable name of a task within a pipeline. Task here most closely aligns with a [computing process](https://en.wikipedia.org/wiki/Pipeline_(computing)) in a pipeline. Other terms for tasks include commands, steps, and procedures.
+The human readable name of a task within a pipeline. Task here most closely aligns with a [computing process](https://wikipedia.org/wiki/Pipeline_(computing)) in a pipeline. Other terms for tasks include commands, steps, and procedures.
 """
 
 CICD_PIPELINE_TASK_RUN_ID: Final = "cicd.pipeline.task.run.id"
@@ -37,7 +37,7 @@
 
 CICD_PIPELINE_TASK_RUN_URL_FULL: Final = "cicd.pipeline.task.run.url.full"
 """
-The [URL](https://en.wikipedia.org/wiki/URL) of the pipeline run providing the complete address in order to locate and identify the pipeline run.
+The [URL](https://wikipedia.org/wiki/URL) of the pipeline run providing the complete address in order to locate and identify the pipeline run.
 """
 
 CICD_PIPELINE_TASK_TYPE: Final = "cicd.pipeline.task.type"

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

@@ -52,13 +52,13 @@
 The exact value to use for `cloud.resource_id` depends on the cloud provider.
 The following well-known definitions MUST be used if you set this attribute and they apply:
 
-* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
+- **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
   Take care not to use the "invoked ARN" directly but replace any
   [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html)
   with the resolved function version, as the same runtime instance may be invocable with
   multiple different aliases.
-* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names)
-* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function,
+- **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names)
+- **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function,
   *not* the function app, having the form
   `/subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
   This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share

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

@@ -25,7 +25,7 @@
 CLOUDFOUNDRY_APP_INSTANCE_ID: Final = "cloudfoundry.app.instance.id"
 """
 The index of the application instance. 0 when just one instance is active.
-Note: CloudFoundry defines the `instance_id` in the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+Note: CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
 It is used for logs and metrics emitted by CloudFoundry. It is
 supposed to contain the application instance index for applications
 deployed on the runtime.

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

@@ -78,8 +78,13 @@
 """
 The name of a collection (table, container) within the database.
 Note: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix.
-For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured.
+
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
+
+For batch operations, if the individual operations are known to have the same collection name
+then that collection name SHOULD be used.
+
 This attribute has stability level RELEASE CANDIDATE.
 """
 
@@ -98,19 +103,30 @@
 Cosmos client connection mode.
 """
 
+DB_COSMOSDB_CONSISTENCY_LEVEL: Final = "db.cosmosdb.consistency_level"
+"""
+Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels).
+"""
+
 DB_COSMOSDB_CONTAINER: Final = "db.cosmosdb.container"
 """
 Deprecated: Replaced by `db.collection.name`.
 """
 
 DB_COSMOSDB_OPERATION_TYPE: Final = "db.cosmosdb.operation_type"
 """
-Cosmos DB Operation Type.
+Deprecated: No replacement at this time.
+"""
+
+DB_COSMOSDB_REGIONS_CONTACTED: Final = "db.cosmosdb.regions_contacted"
+"""
+List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call.
+Note: Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location).
 """
 
 DB_COSMOSDB_REQUEST_CHARGE: Final = "db.cosmosdb.request_charge"
 """
-RU consumed for that operation.
+Request units consumed for the operation.
 """
 
 DB_COSMOSDB_REQUEST_CONTENT_LENGTH: Final = (
@@ -195,17 +211,38 @@
 DB_OPERATION_NAME: Final = "db.operation.name"
 """
 The name of the operation or command being executed.
-Note: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query.
-For batch operations, if the individual operations are known to have the same operation name then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable.
+Note: It is RECOMMENDED to capture the value as provided by the application
+without attempting to do any case normalization.
+
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
+
+For batch operations, if the individual operations are known to have the same operation name
+then that operation name SHOULD be used prepended by `BATCH `,
+otherwise `db.operation.name` SHOULD be `BATCH` or some other database
+system specific term if more applicable.
+
+This attribute has stability level RELEASE CANDIDATE.
+"""
+
+DB_OPERATION_PARAMETER_TEMPLATE: Final = "db.operation.parameter"
+"""
+A database operation parameter, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value.
+Note: If a parameter has no name and instead is referenced only by index, then `<key>` SHOULD be the 0-based index.
+If `db.query.text` is also captured, then `db.operation.parameter.<key>` SHOULD match up with the parameterized placeholders present in `db.query.text`.
 This attribute has stability level RELEASE CANDIDATE.
 """
 
 DB_QUERY_PARAMETER_TEMPLATE: Final = "db.query.parameter"
 """
-A query parameter used in `db.query.text`, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value.
-Note: Query parameters should only be captured when `db.query.text` is parameterized with placeholders.
-If a parameter has no name and instead is referenced only by index, then `<key>` SHOULD be the 0-based index.
+Deprecated: Replaced by `db.operation.parameter`.
+"""
+
+DB_QUERY_SUMMARY: Final = "db.query.summary"
+"""
+Low cardinality representation of a database query text.
+Note: `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+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-text) section.
 This attribute has stability level RELEASE CANDIDATE.
 """
 
@@ -223,6 +260,11 @@
 Deprecated: Replaced by `db.namespace`.
 """
 
+DB_RESPONSE_RETURNED_ROWS: Final = "db.response.returned_rows"
+"""
+Number of rows returned by the operation.
+"""
+
 DB_RESPONSE_STATUS_CODE: Final = "db.response.status_code"
 """
 Database response status code.
@@ -298,11 +340,27 @@ class DbClientConnectionsStateValues(Enum):
 
 class DbCosmosdbConnectionModeValues(Enum):
     GATEWAY = "gateway"
-    """Gateway (HTTP) connections mode."""
+    """Gateway (HTTP) connection."""
     DIRECT = "direct"
     """Direct connection."""
 
 
+class DbCosmosdbConsistencyLevelValues(Enum):
+    STRONG = "Strong"
+    """strong."""
+    BOUNDED_STALENESS = "BoundedStaleness"
+    """bounded_staleness."""
+    SESSION = "Session"
+    """session."""
+    EVENTUAL = "Eventual"
+    """eventual."""
+    CONSISTENT_PREFIX = "ConsistentPrefix"
+    """consistent_prefix."""
+
+
+@deprecated(
+    reason="The attribute db.cosmosdb.operation_type is deprecated - No replacement at this time"
+)  # type: ignore
 class DbCosmosdbOperationTypeValues(Enum):
     BATCH = "batch"
     """batch."""

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

@@ -28,8 +28,8 @@
 This implies that resources carrying the following attribute combinations MUST be
 considered to be identifying the same service:
 
-* `service.name=frontend`, `deployment.environment.name=production`
-* `service.name=frontend`, `deployment.environment.name=staging`.
+- `service.name=frontend`, `deployment.environment.name=production`
+- `service.name=frontend`, `deployment.environment.name=staging`.
 """
 
 DEPLOYMENT_ID: Final = "deployment.id"

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

@@ -48,7 +48,7 @@
 FAAS_INSTANCE: Final = "faas.instance"
 """
 The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version.
-Note: * **AWS Lambda:** Use the (full) log stream name.
+Note: - **AWS Lambda:** Use the (full) log stream name.
 """
 
 FAAS_INVOCATION_ID: Final = "faas.invocation_id"
@@ -93,7 +93,7 @@
 definition of function name MUST be used for this attribute
 (and consequently the span name) for the listed cloud providers/products:
 
-* **Azure:**  The full name `<FUNCAPP>/<FUNC>`, i.e., function app name
+- **Azure:**  The full name `<FUNCAPP>/<FUNC>`, i.e., function app name
   followed by a forward slash followed by the function name (this form
   can also be seen in the resource JSON for the function).
   This means that a span attribute MUST be used, as an Azure function
@@ -116,13 +116,13 @@
 The immutable version of the function being executed.
 Note: Depending on the cloud provider and platform, use:
 
-* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html)
+- **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html)
   (an integer represented as a decimal string).
-* **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions)
+- **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions)
   (i.e., the function name plus the revision suffix).
-* **Google Cloud Functions:** The value of the
+- **Google Cloud Functions:** The value of the
   [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically).
-* **Azure Functions:** Not applicable. Do not set this attribute.
+- **Azure Functions:** Not applicable. Do not set this attribute.
 """
 
 

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

@@ -12,27 +12,72 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from enum import Enum
 from typing import Final
 
+FEATURE_FLAG_CONTEXT_ID: Final = "feature_flag.context.id"
+"""
+The unique identifier for the flag evaluation context. For example, the targeting key.
+"""
+
+FEATURE_FLAG_EVALUATION_ERROR_MESSAGE: Final = (
+    "feature_flag.evaluation.error.message"
+)
+"""
+A message explaining the nature of an error occurring during flag evaluation.
+"""
+
+FEATURE_FLAG_EVALUATION_REASON: Final = "feature_flag.evaluation.reason"
+"""
+The reason code which shows how a feature flag value was determined.
+"""
+
 FEATURE_FLAG_KEY: Final = "feature_flag.key"
 """
-The unique identifier of the feature flag.
+The lookup key of the feature flag.
 """
 
 FEATURE_FLAG_PROVIDER_NAME: Final = "feature_flag.provider_name"
 """
-The name of the service provider that performs the flag evaluation.
+Identifies the feature flag provider.
+"""
+
+FEATURE_FLAG_SET_ID: Final = "feature_flag.set.id"
+"""
+The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs.
 """
 
 FEATURE_FLAG_VARIANT: Final = "feature_flag.variant"
 """
-SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used.
+A semantic identifier for an evaluated flag value.
 Note: A semantic identifier, commonly referred to as a variant, provides a means
 for referring to a value without including the value itself. This can
 provide additional context for understanding the meaning behind a value.
 For example, the variant `red` maybe be used for the value `#c05543`.
+"""
 
-A stringified version of the value can be used in situations where a
-semantic identifier is unavailable. String representation of the value
-should be determined by the implementer.
+FEATURE_FLAG_VERSION: Final = "feature_flag.version"
+"""
+The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset.
 """
+
+
+class FeatureFlagEvaluationReasonValues(Enum):
+    STATIC = "static"
+    """The resolved value is static (no dynamic evaluation)."""
+    DEFAULT = "default"
+    """The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result)."""
+    TARGETING_MATCH = "targeting_match"
+    """The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting."""
+    SPLIT = "split"
+    """The resolved value was the result of pseudorandom assignment."""
+    CACHED = "cached"
+    """The resolved value was retrieved from cache."""
+    DISABLED = "disabled"
+    """The resolved value was the result of the flag being disabled in the management system."""
+    UNKNOWN = "unknown"
+    """The reason for the resolved value could not be determined."""
+    STALE = "stale"
+    """The resolved value is non-authoritative or possibly out of date."""
+    ERROR = "error"
+    """The resolved value was the result of an error."""

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

@@ -36,7 +36,7 @@
     "gen_ai.openai.request.service_tier"
 )
 """
-The service tier requested. May be a specific tier, detault, or auto.
+The service tier requested. May be a specific tier, default, or auto.
 """
 
 GEN_AI_OPENAI_RESPONSE_SERVICE_TIER: Final = (
@@ -46,6 +46,13 @@
 The service tier used for the response.
 """
 
+GEN_AI_OPENAI_RESPONSE_SYSTEM_FINGERPRINT: Final = (
+    "gen_ai.openai.response.system_fingerprint"
+)
+"""
+A fingerprint to track any eventual change in the Generative AI environment.
+"""
+
 GEN_AI_OPERATION_NAME: Final = "gen_ai.operation.name"
 """
 The name of the operation being performed.
@@ -57,6 +64,12 @@
 Deprecated: Removed, no replacement at this time.
 """
 
+GEN_AI_REQUEST_ENCODING_FORMATS: Final = "gen_ai.request.encoding_formats"
+"""
+The encoding formats requested in an embeddings operation, if specified.
+Note: In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request.
+"""
+
 GEN_AI_REQUEST_FREQUENCY_PENALTY: Final = "gen_ai.request.frequency_penalty"
 """
 The frequency penalty setting for the GenAI request.
@@ -173,6 +186,8 @@ class GenAiOperationNameValues(Enum):
     """Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)."""
     TEXT_COMPLETION = "text_completion"
     """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)."""
 
 
 class GenAiSystemValues(Enum):
@@ -184,6 +199,12 @@ class GenAiSystemValues(Enum):
     """Anthropic."""
     COHERE = "cohere"
     """Cohere."""
+    AZ_AI_INFERENCE = "az.ai.inference"
+    """Azure AI Inference."""
+    IBM_WATSONX_AI = "ibm.watsonx.ai"
+    """IBM Watsonx AI."""
+    AWS_BEDROCK = "aws.bedrock"
+    """AWS Bedrock."""
 
 
 class GenAiTokenTypeValues(Enum):