Generate semantic conventions 1.31.0 (#4471)

* Generate semantic conventions 1.31.0

We cannot bump weaver because something changed in the format of the
notes and requires update in the jinja templates.
Added trimming when rendering metrics to fix rendering of multiline
brief attributes that broke rendering of hw_metrics.

* Add changelog

Author: xrmx

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- semantic-conventions: Bump to 1.31.0
+  ([#4471](https://github.com/open-telemetry/opentelemetry-python/pull/4471))
 - Add type annotations to context's attach & detach
   ([#4346](https://github.com/open-telemetry/opentelemetry-python/pull/4346))
 - Fix OTLP encoders missing instrumentation scope schema url and attributes

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

@@ -35,6 +35,11 @@
 The pipeline run goes through these states during its lifecycle.
 """
 
+CICD_PIPELINE_RUN_URL_FULL: Final = "cicd.pipeline.run.url.full"
+"""
+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_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://wikipedia.org/wiki/Pipeline_(computing)) in a pipeline. Other terms for tasks include commands, steps, and procedures.
@@ -47,7 +52,7 @@
 
 CICD_PIPELINE_TASK_RUN_URL_FULL: Final = "cicd.pipeline.task.run.url.full"
 """
-The [URL](https://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 task run, providing the complete address in order to locate and identify the pipeline task run.
 """
 
 CICD_PIPELINE_TASK_TYPE: Final = "cicd.pipeline.task.type"

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

@@ -45,7 +45,7 @@
 
 CLOUD_RESOURCE_ID: Final = "cloud.resource_id"
 """
-Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP).
+Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://google.aip.dev/122#full-resource-names) on GCP).
 Note: On some cloud providers, it may not be possible to determine the full ID at startup,
 so it may be necessary to set `cloud.resource_id` as a span attribute instead.
 

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

@@ -31,7 +31,7 @@
 
 CODE_FILEPATH: Final = "code.filepath"
 """
-Deprecated, use `code.file.path` instead.
+Deprecated: Replaced by `code.file.path`.
 """
 
 CODE_FUNCTION: Final = "code.function"
@@ -41,7 +41,22 @@
 
 CODE_FUNCTION_NAME: Final = "code.function.name"
 """
-The method or function name, or equivalent (usually rightmost part of the code unit's name).
+The method or function fully-qualified name without arguments. The value should fit the natural representation of the language runtime, which is also likely the same used within `code.stacktrace` attribute value.
+Note: Values and format depends on each language runtime, thus it is impossible to provide an exhaustive list of examples.
+The values are usually the same (or prefixes of) the ones found in native stack trace representation stored in
+`code.stacktrace` without information on arguments.
+
+Examples:
+
+* Java method: `com.example.MyHttpService.serveRequest`
+* Java anonymous class method: `com.mycompany.Main$1.myMethod`
+* Java lambda method: `com.mycompany.Main$$Lambda/0x0000748ae4149c00.myMethod`
+* PHP function: `GuzzleHttp\\Client::transfer
+* Go function: `github.com/my/repo/pkg.foo.func5`
+* Elixir: `OpenTelemetry.Ctx.new`
+* Erlang: `opentelemetry_ctx:new`
+* Rust: `playground::my_module::my_cool_func`
+* C function: `fopen`.
 """
 
 CODE_LINE_NUMBER: Final = "code.line.number"
@@ -56,10 +71,10 @@
 
 CODE_NAMESPACE: Final = "code.namespace"
 """
-The "namespace" within which `code.function.name` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function.name` form a unique identifier for the code unit.
+Deprecated: Value should be included in `code.function.name` which is expected to be a fully-qualified name.
 """
 
 CODE_STACKTRACE: Final = "code.stacktrace"
 """
-A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG.
+A stacktrace as a string in the natural representation for the language runtime. The representation is identical to [`exception.stacktrace`](/docs/exceptions/exceptions-spans.md#stacktrace-representation).
 """

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

@@ -15,6 +15,11 @@
 from enum import Enum
 from typing import Final
 
+CPU_LOGICAL_NUMBER: Final = "cpu.logical_number"
+"""
+The logical CPU number [0..n-1].
+"""
+
 CPU_MODE: Final = "cpu.mode"
 """
 The mode of the CPU.

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

@@ -77,13 +77,14 @@
 DB_COLLECTION_NAME: Final = "db.collection.name"
 """
 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.
+Note: It is RECOMMENDED to capture the value as provided by the application
+without attempting to do any case normalization.
 
 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.
+when the database system supports cross-table queries in non-batch operations.
 
-For batch operations, if the individual operations are known to have the same collection name
-then that collection name SHOULD be used.
+For batch operations, if the individual operations are known to have the same
+collection name then that collection name SHOULD be used.
 """
 
 DB_CONNECTION_STRING: Final = "db.connection_string"
@@ -209,7 +210,7 @@
 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.
+when the database system supports cross-table queries in non-batch operations.
 
 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 `,
@@ -233,13 +234,13 @@
 """
 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.
+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](../database/database-spans.md#generating-a-summary-of-the-query-text) section.
 """
 
 DB_QUERY_TEXT: Final = "db.query.text"
 """
 The database query being executed.
-Note: For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+Note: For sanitization see [Sanitization of `db.query.text`](../database/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.
 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.
 """

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

@@ -16,7 +16,20 @@
 
 ENDUSER_ID: Final = "enduser.id"
 """
-Deprecated: Replaced by `user.id` attribute.
+Unique identifier of an end user in the system. It maybe a username, email address, or other identifier.
+Note: Unique identifier of an end user in the system.
+
+> [!Warning]
+> This field contains sensitive (PII) information.
+"""
+
+ENDUSER_PSEUDO_ID: Final = "enduser.pseudo.id"
+"""
+Pseudonymous identifier of an end user. This identifier should be a random value that is not directly linked or associated with the end user's actual identity.
+Note: Pseudonymous identifier of an end user.
+
+> [!Warning]
+> This field contains sensitive (linkable PII) information.
 """
 
 ENDUSER_ROLE: Final = "enduser.role"

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

@@ -15,6 +15,23 @@
 from enum import Enum
 from typing import Final
 
+from deprecated import deprecated
+
+GEN_AI_AGENT_DESCRIPTION: Final = "gen_ai.agent.description"
+"""
+Free-form description of the GenAI agent provided by the application.
+"""
+
+GEN_AI_AGENT_ID: Final = "gen_ai.agent.id"
+"""
+The unique identifier of the GenAI agent.
+"""
+
+GEN_AI_AGENT_NAME: Final = "gen_ai.agent.name"
+"""
+Human-readable name of the GenAI agent provided by the application.
+"""
+
 GEN_AI_COMPLETION: Final = "gen_ai.completion"
 """
 Deprecated: Removed, no replacement at this time.
@@ -24,7 +41,7 @@
     "gen_ai.openai.request.response_format"
 )
 """
-The response format that is requested.
+Deprecated: Replaced by `gen_ai.output.type`.
 """
 
 GEN_AI_OPENAI_REQUEST_SEED: Final = "gen_ai.openai.request.seed"
@@ -59,11 +76,24 @@
 Note: If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
 """
 
+GEN_AI_OUTPUT_TYPE: Final = "gen_ai.output.type"
+"""
+Represents the content type requested by the client.
+Note: This attribute SHOULD be used when the client requests output of a specific type. The model may return zero or more outputs of this type.
+This attribute specifies the output modality and not the actual output format. For example, if an image is requested, the actual output could be a URL pointing to an image file.
+Additional output format details may be recorded in the future in the `gen_ai.output.{type}.*` attributes.
+"""
+
 GEN_AI_PROMPT: Final = "gen_ai.prompt"
 """
 Deprecated: Removed, no replacement at this time.
 """
 
+GEN_AI_REQUEST_CHOICE_COUNT: Final = "gen_ai.request.choice.count"
+"""
+The target number of candidate completions to return.
+"""
+
 GEN_AI_REQUEST_ENCODING_FORMATS: Final = "gen_ai.request.encoding_formats"
 """
 The encoding formats requested in an embeddings operation, if specified.
@@ -151,6 +181,26 @@
 The type of token being counted.
 """
 
+GEN_AI_TOOL_CALL_ID: Final = "gen_ai.tool.call.id"
+"""
+The tool call identifier.
+"""
+
+GEN_AI_TOOL_NAME: Final = "gen_ai.tool.name"
+"""
+Name of the tool utilized by the agent.
+"""
+
+GEN_AI_TOOL_TYPE: Final = "gen_ai.tool.type"
+"""
+Type of the tool utilized by the agent.
+Note: Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems.
+  Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment.
+Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic.
+  Client-side operations are actions taken on the user's end or within the client application.
+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_COMPLETION_TOKENS: Final = "gen_ai.usage.completion_tokens"
 """
 Deprecated: Replaced by `gen_ai.usage.output_tokens` attribute.
@@ -172,6 +222,9 @@
 """
 
 
+@deprecated(
+    reason="The attribute gen_ai.openai.request.response_format is deprecated - Replaced by `gen_ai.output.type`"
+)  # type: ignore
 class GenAiOpenaiRequestResponseFormatValues(Enum):
     TEXT = "text"
     """Text response format."""
@@ -195,6 +248,21 @@ 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)."""
+    CREATE_AGENT = "create_agent"
+    """Create GenAI agent."""
+    EXECUTE_TOOL = "execute_tool"
+    """Execute a tool."""
+
+
+class GenAiOutputTypeValues(Enum):
+    TEXT = "text"
+    """Plain text."""
+    JSON = "json"
+    """JSON object with known or unknown schema."""
+    IMAGE = "image"
+    """Image."""
+    SPEECH = "speech"
+    """Speech."""
 
 
 class GenAiSystemValues(Enum):
@@ -232,4 +300,6 @@ class GenAiTokenTypeValues(Enum):
     INPUT = "input"
     """Input tokens (prompt, input, etc.)."""
     COMPLETION = "output"
+    """Deprecated: Replaced by `output`."""
+    OUTPUT = "output"
     """Output tokens (completion, response, etc.)."""

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

@@ -94,6 +94,16 @@
 The UID of the Deployment.
 """
 
+K8S_HPA_NAME: Final = "k8s.hpa.name"
+"""
+The name of the horizontal pod autoscaler.
+"""
+
+K8S_HPA_UID: Final = "k8s.hpa.uid"
+"""
+The UID of the horizontal pod autoscaler.
+"""
+
 K8S_JOB_NAME: Final = "k8s.job.name"
 """
 The name of the Job.
@@ -161,6 +171,26 @@
 The UID of the ReplicaSet.
 """
 
+K8S_REPLICATIONCONTROLLER_NAME: Final = "k8s.replicationcontroller.name"
+"""
+The name of the replication controller.
+"""
+
+K8S_REPLICATIONCONTROLLER_UID: Final = "k8s.replicationcontroller.uid"
+"""
+The UID of the replication controller.
+"""
+
+K8S_RESOURCEQUOTA_NAME: Final = "k8s.resourcequota.name"
+"""
+The name of the resource quota.
+"""
+
+K8S_RESOURCEQUOTA_UID: Final = "k8s.resourcequota.uid"
+"""
+The UID of the resource quota.
+"""
+
 K8S_STATEFULSET_NAME: Final = "k8s.statefulset.name"
 """
 The name of the StatefulSet.

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

@@ -18,5 +18,5 @@
 """
 The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known.
 Note: Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests).
-An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest).
+An example can be found in [Example Image Manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md#example-image-manifest).
 """