diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ad85761939..4dd7d0c7981 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cicd_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cicd_attributes.py index e1a469bc307..945fc81dc9c 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cicd_attributes.py +++ b/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" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cloud_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cloud_attributes.py index 97047a063fd..e32cf8d7d18 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cloud_attributes.py +++ b/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. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/code_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/code_attributes.py index 4a058e16ede..1ca1ecb2b88 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/code_attributes.py +++ b/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). """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cpu_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cpu_attributes.py index 8fcaef32ef6..e960e203ae2 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cpu_attributes.py +++ b/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. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/db_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/db_attributes.py index fdbd372cea0..bc9b7f33f12 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/db_attributes.py +++ b/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. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/enduser_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/enduser_attributes.py index 1fb02f8d54f..809404407bb 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/enduser_attributes.py +++ b/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" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/gen_ai_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/gen_ai_attributes.py index ad88911cabb..70b1feb1f15 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/gen_ai_attributes.py +++ b/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.).""" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/k8s_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/k8s_attributes.py index 1eb92df8f4b..9d79cd9bd7a 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/k8s_attributes.py +++ b/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. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/oci_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/oci_attributes.py index 51da3e92c5c..ba721dffeed 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/oci_attributes.py +++ b/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). """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/otel_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/otel_attributes.py index c58c750f06e..d8b5eefe4d4 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/otel_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/otel_attributes.py @@ -17,6 +17,31 @@ from deprecated import deprecated +OTEL_COMPONENT_NAME: Final = "otel.component.name" +""" +A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. +Note: Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. + +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.component.type` refers to the corresponding attribute value of the component. + +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. +""" + +OTEL_COMPONENT_TYPE: Final = "otel.component.type" +""" +A name identifying the type of the OpenTelemetry component. +Note: If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. +""" + OTEL_LIBRARY_NAME: Final = "otel.library.name" """ Deprecated: Use the `otel.scope.name` attribute. @@ -37,6 +62,11 @@ Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.otel_attributes.OTEL_SCOPE_VERSION`. """ +OTEL_SPAN_SAMPLING_RESULT: Final = "otel.span.sampling_result" +""" +The result value of the sampler for this span. +""" + OTEL_STATUS_CODE: Final = "otel.status_code" """ Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.otel_attributes.OTEL_STATUS_CODE`. @@ -48,6 +78,28 @@ """ +class OtelComponentTypeValues(Enum): + BATCHING_SPAN_PROCESSOR = "batching_span_processor" + """The builtin SDK Batching Span Processor.""" + SIMPLE_SPAN_PROCESSOR = "simple_span_processor" + """The builtin SDK Simple Span Processor.""" + OTLP_GRPC_SPAN_EXPORTER = "otlp_grpc_span_exporter" + """OTLP span exporter over gRPC with protobuf serialization.""" + OTLP_HTTP_SPAN_EXPORTER = "otlp_http_span_exporter" + """OTLP span exporter over HTTP with protobuf serialization.""" + OTLP_HTTP_JSON_SPAN_EXPORTER = "otlp_http_json_span_exporter" + """OTLP span exporter over HTTP with JSON serialization.""" + + +class OtelSpanSamplingResultValues(Enum): + DROP = "DROP" + """The span is not sampled and not recording.""" + RECORD_ONLY = "RECORD_ONLY" + """The span is not sampled, but recording.""" + RECORD_AND_SAMPLE = "RECORD_AND_SAMPLE" + """The span is sampled and recording.""" + + @deprecated( reason="Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.otel_attributes.OtelStatusCodeValues`." ) # type: ignore diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/process_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/process_attributes.py index 113861bef61..9011c68f789 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/process_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/process_attributes.py @@ -79,7 +79,7 @@ PROCESS_EXECUTABLE_NAME: Final = "process.executable.name" """ -The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. +The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. """ PROCESS_EXECUTABLE_PATH: Final = "process.executable.path" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/rpc_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/rpc_attributes.py index de037e0d385..ff5b035a8c8 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/rpc_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/rpc_attributes.py @@ -17,7 +17,7 @@ RPC_CONNECT_RPC_ERROR_CODE: Final = "rpc.connect_rpc.error_code" """ -The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. +The [error codes](https://connectrpc.com//docs/protocol/#error-codes) of the Connect request. Error codes are always string values. """ RPC_CONNECT_RPC_REQUEST_METADATA_TEMPLATE: Final = ( diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/system_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/system_attributes.py index caf1bc7d319..aae23bf9912 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/system_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/system_attributes.py @@ -19,7 +19,7 @@ SYSTEM_CPU_LOGICAL_NUMBER: Final = "system.cpu.logical_number" """ -The logical CPU number [0..n-1]. +Deprecated, use `cpu.logical_number` instead. """ SYSTEM_CPU_STATE: Final = "system.cpu.state" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/tls_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/tls_attributes.py index 43c525bdc3b..fa2b9169267 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/tls_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/tls_attributes.py @@ -98,12 +98,12 @@ TLS_PROTOCOL_NAME: Final = "tls.protocol.name" """ -Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES). +Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://docs.openssl.org/1.1.1/man3/SSL_get_version/#return-values). """ TLS_PROTOCOL_VERSION: Final = "tls.protocol.version" """ -Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES). +Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://docs.openssl.org/1.1.1/man3/SSL_get_version/#return-values). """ TLS_RESUMED: Final = "tls.resumed" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/url_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/url_attributes.py index ebc92a1cf1b..57d1de86bba 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/url_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/url_attributes.py @@ -61,7 +61,7 @@ URL_REGISTERED_DOMAIN: Final = "url.registered_domain" """ The highest registered url domain, stripped of the subdomain. -Note: This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. +Note: This value can be determined precisely with the [public suffix list](https://publicsuffix.org/). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. """ URL_SCHEME: Final = "url.scheme" @@ -83,5 +83,5 @@ URL_TOP_LEVEL_DOMAIN: Final = "url.top_level_domain" """ The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is `com`. -Note: This value can be determined precisely with the [public suffix list](http://publicsuffix.org). +Note: This value can be determined precisely with the [public suffix list](https://publicsuffix.org/). """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/user_agent_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/user_agent_attributes.py index a2b133cfe6c..6c9e26997cc 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/user_agent_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/user_agent_attributes.py @@ -26,6 +26,18 @@ Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.user_agent_attributes.USER_AGENT_ORIGINAL`. """ +USER_AGENT_OS_NAME: Final = "user_agent.os.name" +""" +Human readable operating system name. +Note: For mapping user agent strings to OS names, libraries such as [ua-parser](https://github.com/ua-parser) can be utilized. +""" + +USER_AGENT_OS_VERSION: Final = "user_agent.os.version" +""" +The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). +Note: For mapping user agent strings to OS versions, libraries such as [ua-parser](https://github.com/ua-parser) can be utilized. +""" + USER_AGENT_SYNTHETIC_TYPE: Final = "user_agent.synthetic.type" """ Specifies the category of synthetic traffic, such as tests or bots. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/cpu_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/cpu_metrics.py new file mode 100644 index 00000000000..86bc5a678cd --- /dev/null +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/cpu_metrics.py @@ -0,0 +1,94 @@ +# Copyright The OpenTelemetry Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +from typing import ( + Callable, + Final, + Generator, + Iterable, + Optional, + Sequence, + Union, +) + +from opentelemetry.metrics import ( + CallbackOptions, + Counter, + Meter, + ObservableGauge, + Observation, +) + +# pylint: disable=invalid-name +CallbackT = Union[ + Callable[[CallbackOptions], Iterable[Observation]], + Generator[Iterable[Observation], CallbackOptions, None], +] + +CPU_FREQUENCY: Final = "cpu.frequency" +""" +Operating frequency of the logical CPU in Hertz +Instrument: gauge +Unit: Hz +""" + + +def create_cpu_frequency( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """Operating frequency of the logical CPU in Hertz""" + return meter.create_observable_gauge( + name=CPU_FREQUENCY, + callbacks=callbacks, + description="Operating frequency of the logical CPU in Hertz.", + unit="Hz", + ) + + +CPU_TIME: Final = "cpu.time" +""" +Seconds each logical CPU spent on each mode +Instrument: counter +Unit: s +""" + + +def create_cpu_time(meter: Meter) -> Counter: + """Seconds each logical CPU spent on each mode""" + return meter.create_counter( + name=CPU_TIME, + description="Seconds each logical CPU spent on each mode", + unit="s", + ) + + +CPU_UTILIZATION: Final = "cpu.utilization" +""" +For each logical CPU, the utilization is calculated as the change in cumulative CPU time (cpu.time) over a measurement interval, divided by the elapsed time +Instrument: gauge +Unit: 1 +""" + + +def create_cpu_utilization( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """For each logical CPU, the utilization is calculated as the change in cumulative CPU time (cpu.time) over a measurement interval, divided by the elapsed time""" + return meter.create_observable_gauge( + name=CPU_UTILIZATION, + callbacks=callbacks, + description="For each logical CPU, the utilization is calculated as the change in cumulative CPU time (cpu.time) over a measurement interval, divided by the elapsed time.", + unit="1", + ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/hw_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/hw_metrics.py index ca615236e7a..d06890fd2f0 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/hw_metrics.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/hw_metrics.py @@ -72,6 +72,85 @@ def create_hw_errors(meter: Meter) -> Counter: ) +HW_HOST_AMBIENT_TEMPERATURE: Final = "hw.host.ambient_temperature" +""" +Ambient (external) temperature of the physical host +Instrument: gauge +Unit: Cel +""" + + +def create_hw_host_ambient_temperature( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """Ambient (external) temperature of the physical host""" + return meter.create_observable_gauge( + name=HW_HOST_AMBIENT_TEMPERATURE, + callbacks=callbacks, + description="Ambient (external) temperature of the physical host", + unit="Cel", + ) + + +HW_HOST_ENERGY: Final = "hw.host.energy" +""" +Total energy consumed by the entire physical host, in joules +Instrument: counter +Unit: J +Note: The overall energy usage of a host MUST be reported using the specific `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic `hw.energy` and `hw.power` described in the previous section, to prevent summing up overlapping values. +""" + + +def create_hw_host_energy(meter: Meter) -> Counter: + """Total energy consumed by the entire physical host, in joules""" + return meter.create_counter( + name=HW_HOST_ENERGY, + description="Total energy consumed by the entire physical host, in joules", + unit="J", + ) + + +HW_HOST_HEATING_MARGIN: Final = "hw.host.heating_margin" +""" +By how many degrees Celsius the temperature of the physical host can be increased, before reaching a warning threshold on one of the internal sensors +Instrument: gauge +Unit: Cel +""" + + +def create_hw_host_heating_margin( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """By how many degrees Celsius the temperature of the physical host can be increased, before reaching a warning threshold on one of the internal sensors""" + return meter.create_observable_gauge( + name=HW_HOST_HEATING_MARGIN, + callbacks=callbacks, + description="By how many degrees Celsius the temperature of the physical host can be increased, before reaching a warning threshold on one of the internal sensors", + unit="Cel", + ) + + +HW_HOST_POWER: Final = "hw.host.power" +""" +Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred) +Instrument: gauge +Unit: W +Note: The overall energy usage of a host MUST be reported using the specific `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic `hw.energy` and `hw.power` described in the previous section, to prevent summing up overlapping values. +""" + + +def create_hw_host_power( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred)""" + return meter.create_observable_gauge( + name=HW_HOST_POWER, + callbacks=callbacks, + description="Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred)", + unit="W", + ) + + HW_POWER: Final = "hw.power" """ Instantaneous power consumed by the component @@ -98,7 +177,7 @@ def create_hw_power( Operational status: `1` (true) or `0` (false) for each of the possible states Instrument: updowncounter Unit: 1 -Note: `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a [*StateSet* as defined in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. +Note: `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a [*StateSet* as defined in OpenMetrics](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/k8s_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/k8s_metrics.py index 4017520c842..760d4d55c7c 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/k8s_metrics.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/k8s_metrics.py @@ -206,7 +206,10 @@ def create_k8s_deployment_desired_pods(meter: Meter) -> UpDownCounter: Instrument: updowncounter Unit: {pod} Note: This metric aligns with the `currentReplicas` field of the -[K8s HorizontalPodAutoscalerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerstatus-v2-autoscaling). +[K8s HorizontalPodAutoscalerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerstatus-v2-autoscaling) + +This metric SHOULD, at a minimum, be reported against a +[`k8s.hpa`](../resource/k8s.md#horizontalpodautoscaler) resource. """ @@ -225,7 +228,10 @@ def create_k8s_hpa_current_pods(meter: Meter) -> UpDownCounter: Instrument: updowncounter Unit: {pod} Note: This metric aligns with the `desiredReplicas` field of the -[K8s HorizontalPodAutoscalerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerstatus-v2-autoscaling). +[K8s HorizontalPodAutoscalerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerstatus-v2-autoscaling) + +This metric SHOULD, at a minimum, be reported against a +[`k8s.hpa`](../resource/k8s.md#horizontalpodautoscaler) resource. """ @@ -244,7 +250,10 @@ def create_k8s_hpa_desired_pods(meter: Meter) -> UpDownCounter: Instrument: updowncounter Unit: {pod} Note: This metric aligns with the `maxReplicas` field of the -[K8s HorizontalPodAutoscalerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerspec-v2-autoscaling). +[K8s HorizontalPodAutoscalerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerspec-v2-autoscaling) + +This metric SHOULD, at a minimum, be reported against a +[`k8s.hpa`](../resource/k8s.md#horizontalpodautoscaler) resource. """ @@ -263,7 +272,10 @@ def create_k8s_hpa_max_pods(meter: Meter) -> UpDownCounter: Instrument: updowncounter Unit: {pod} Note: This metric aligns with the `minReplicas` field of the -[K8s HorizontalPodAutoscalerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerspec-v2-autoscaling). +[K8s HorizontalPodAutoscalerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerspec-v2-autoscaling) + +This metric SHOULD, at a minimum, be reported against a +[`k8s.hpa`](../resource/k8s.md#horizontalpodautoscaler) resource. """ @@ -348,7 +360,7 @@ def create_k8s_job_failed_pods(meter: Meter) -> UpDownCounter: Instrument: updowncounter Unit: {pod} Note: This metric aligns with the `parallelism` field of the -[K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch. +[K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch). This metric SHOULD, at a minimum, be reported against a [`k8s.job`](../resource/k8s.md#job) resource. @@ -685,43 +697,87 @@ def create_k8s_replicaset_desired_pods(meter: Meter) -> UpDownCounter: "k8s.replication_controller.available_pods" ) """ +Deprecated: Replaced by `k8s.replicationcontroller.available_pods`. +""" + + +def create_k8s_replication_controller_available_pods( + meter: Meter, +) -> UpDownCounter: + """Deprecated, use `k8s.replicationcontroller.available_pods` instead""" + return meter.create_up_down_counter( + name=K8S_REPLICATION_CONTROLLER_AVAILABLE_PODS, + description="Deprecated, use `k8s.replicationcontroller.available_pods` instead.", + unit="{pod}", + ) + + +K8S_REPLICATION_CONTROLLER_DESIRED_PODS: Final = ( + "k8s.replication_controller.desired_pods" +) +""" +Deprecated: Replaced by `k8s.replicationcontroller.desired_pods`. +""" + + +def create_k8s_replication_controller_desired_pods( + meter: Meter, +) -> UpDownCounter: + """Deprecated, use `k8s.replicationcontroller.desired_pods` instead""" + return meter.create_up_down_counter( + name=K8S_REPLICATION_CONTROLLER_DESIRED_PODS, + description="Deprecated, use `k8s.replicationcontroller.desired_pods` instead.", + unit="{pod}", + ) + + +K8S_REPLICATIONCONTROLLER_AVAILABLE_PODS: Final = ( + "k8s.replicationcontroller.available_pods" +) +""" Total number of available replica pods (ready for at least minReadySeconds) targeted by this replication controller Instrument: updowncounter Unit: {pod} Note: This metric aligns with the `availableReplicas` field of the -[K8s ReplicationControllerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicationcontrollerstatus-v1-core). +[K8s ReplicationControllerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicationcontrollerstatus-v1-core) + +This metric SHOULD, at a minimum, be reported against a +[`k8s.replicationcontroller`](../resource/k8s.md#replicationcontroller) resource. """ -def create_k8s_replication_controller_available_pods( +def create_k8s_replicationcontroller_available_pods( meter: Meter, ) -> UpDownCounter: """Total number of available replica pods (ready for at least minReadySeconds) targeted by this replication controller""" return meter.create_up_down_counter( - name=K8S_REPLICATION_CONTROLLER_AVAILABLE_PODS, + name=K8S_REPLICATIONCONTROLLER_AVAILABLE_PODS, description="Total number of available replica pods (ready for at least minReadySeconds) targeted by this replication controller", unit="{pod}", ) -K8S_REPLICATION_CONTROLLER_DESIRED_PODS: Final = ( - "k8s.replication_controller.desired_pods" +K8S_REPLICATIONCONTROLLER_DESIRED_PODS: Final = ( + "k8s.replicationcontroller.desired_pods" ) """ Number of desired replica pods in this replication controller Instrument: updowncounter Unit: {pod} Note: This metric aligns with the `replicas` field of the -[K8s ReplicationControllerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicationcontrollerspec-v1-core). +[K8s ReplicationControllerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicationcontrollerspec-v1-core) + +This metric SHOULD, at a minimum, be reported against a +[`k8s.replicationcontroller`](../resource/k8s.md#replicationcontroller) resource. """ -def create_k8s_replication_controller_desired_pods( +def create_k8s_replicationcontroller_desired_pods( meter: Meter, ) -> UpDownCounter: """Number of desired replica pods in this replication controller""" return meter.create_up_down_counter( - name=K8S_REPLICATION_CONTROLLER_DESIRED_PODS, + name=K8S_REPLICATIONCONTROLLER_DESIRED_PODS, description="Number of desired replica pods in this replication controller", unit="{pod}", ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/otel_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/otel_metrics.py new file mode 100644 index 00000000000..ab9a8f1ffe1 --- /dev/null +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/otel_metrics.py @@ -0,0 +1,162 @@ +# Copyright The OpenTelemetry Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +from typing import Final + +from opentelemetry.metrics import Counter, Meter, UpDownCounter + +OTEL_SDK_EXPORTER_SPAN_EXPORTED_COUNT: Final = ( + "otel.sdk.exporter.span.exported.count" +) +""" +The number of spans for which the export has finished, either successful or failed +Instrument: counter +Unit: {span} +Note: For successful exports, `error.type` MUST NOT be set. For failed exports, `error.type` must contain the failure cause. +For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. +If no rejection reason is available, `rejected` SHOULD be used as value for `error.type`. +""" + + +def create_otel_sdk_exporter_span_exported_count(meter: Meter) -> Counter: + """The number of spans for which the export has finished, either successful or failed""" + return meter.create_counter( + name=OTEL_SDK_EXPORTER_SPAN_EXPORTED_COUNT, + description="The number of spans for which the export has finished, either successful or failed", + unit="{span}", + ) + + +OTEL_SDK_EXPORTER_SPAN_INFLIGHT_COUNT: Final = ( + "otel.sdk.exporter.span.inflight.count" +) +""" +The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) +Instrument: updowncounter +Unit: {span} +Note: For successful exports, `error.type` MUST NOT be set. For failed exports, `error.type` must contain the failure cause. +""" + + +def create_otel_sdk_exporter_span_inflight_count( + meter: Meter, +) -> UpDownCounter: + """The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed)""" + return meter.create_up_down_counter( + name=OTEL_SDK_EXPORTER_SPAN_INFLIGHT_COUNT, + description="The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed)", + unit="{span}", + ) + + +OTEL_SDK_PROCESSOR_SPAN_PROCESSED_COUNT: Final = ( + "otel.sdk.processor.span.processed.count" +) +""" +The number of spans for which the processing has finished, either successful or failed +Instrument: counter +Unit: {span} +Note: For successful processing, `error.type` MUST NOT be set. For failed processing, `error.type` must contain the failure cause. +For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. +""" + + +def create_otel_sdk_processor_span_processed_count(meter: Meter) -> Counter: + """The number of spans for which the processing has finished, either successful or failed""" + return meter.create_counter( + name=OTEL_SDK_PROCESSOR_SPAN_PROCESSED_COUNT, + description="The number of spans for which the processing has finished, either successful or failed", + unit="{span}", + ) + + +OTEL_SDK_PROCESSOR_SPAN_QUEUE_CAPACITY: Final = ( + "otel.sdk.processor.span.queue.capacity" +) +""" +The maximum number of spans the queue of a given instance of an SDK span processor can hold +Instrument: updowncounter +Unit: {span} +Note: Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. +""" + + +def create_otel_sdk_processor_span_queue_capacity( + meter: Meter, +) -> UpDownCounter: + """The maximum number of spans the queue of a given instance of an SDK span processor can hold""" + return meter.create_up_down_counter( + name=OTEL_SDK_PROCESSOR_SPAN_QUEUE_CAPACITY, + description="The maximum number of spans the queue of a given instance of an SDK span processor can hold", + unit="{span}", + ) + + +OTEL_SDK_PROCESSOR_SPAN_QUEUE_SIZE: Final = ( + "otel.sdk.processor.span.queue.size" +) +""" +The number of spans in the queue of a given instance of an SDK span processor +Instrument: updowncounter +Unit: {span} +Note: Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. +""" + + +def create_otel_sdk_processor_span_queue_size(meter: Meter) -> UpDownCounter: + """The number of spans in the queue of a given instance of an SDK span processor""" + return meter.create_up_down_counter( + name=OTEL_SDK_PROCESSOR_SPAN_QUEUE_SIZE, + description="The number of spans in the queue of a given instance of an SDK span processor", + unit="{span}", + ) + + +OTEL_SDK_SPAN_ENDED_COUNT: Final = "otel.sdk.span.ended.count" +""" +The number of created spans for which the end operation was called +Instrument: counter +Unit: {span} +Note: For spans with `recording=true`: Implementations MUST record both `otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. +For spans with `recording=false`: If implementations decide to record this metric, they MUST also record `otel.sdk.span.live.count`. +""" + + +def create_otel_sdk_span_ended_count(meter: Meter) -> Counter: + """The number of created spans for which the end operation was called""" + return meter.create_counter( + name=OTEL_SDK_SPAN_ENDED_COUNT, + description="The number of created spans for which the end operation was called", + unit="{span}", + ) + + +OTEL_SDK_SPAN_LIVE_COUNT: Final = "otel.sdk.span.live.count" +""" +The number of created spans for which the end operation has not been called yet +Instrument: updowncounter +Unit: {span} +Note: For spans with `recording=true`: Implementations MUST record both `otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. +For spans with `recording=false`: If implementations decide to record this metric, they MUST also record `otel.sdk.span.ended.count`. +""" + + +def create_otel_sdk_span_live_count(meter: Meter) -> UpDownCounter: + """The number of created spans for which the end operation has not been called yet""" + return meter.create_up_down_counter( + name=OTEL_SDK_SPAN_LIVE_COUNT, + description="The number of created spans for which the end operation has not been called yet", + unit="{span}", + ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/process_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/process_metrics.py index 3b7f5012114..902d79de276 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/process_metrics.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/process_metrics.py @@ -42,7 +42,7 @@ """ Number of times the process has been context switched Instrument: counter -Unit: {count} +Unit: {context_switch} """ @@ -51,7 +51,7 @@ def create_process_context_switches(meter: Meter) -> Counter: return meter.create_counter( name=PROCESS_CONTEXT_SWITCHES, description="Number of times the process has been context switched.", - unit="{count}", + unit="{context_switch}", ) @@ -166,7 +166,7 @@ def create_process_network_io(meter: Meter) -> Counter: """ Number of file descriptors in use by the process Instrument: updowncounter -Unit: {count} +Unit: {file_descriptor} """ @@ -175,7 +175,7 @@ def create_process_open_file_descriptor_count(meter: Meter) -> UpDownCounter: return meter.create_up_down_counter( name=PROCESS_OPEN_FILE_DESCRIPTOR_COUNT, description="Number of file descriptors in use by the process.", - unit="{count}", + unit="{file_descriptor}", ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/system_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/system_metrics.py index e47b963e68a..df2a6571801 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/system_metrics.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/system_metrics.py @@ -40,20 +40,18 @@ SYSTEM_CPU_FREQUENCY: Final = "system.cpu.frequency" """ -Reports the current frequency of the CPU in Hz -Instrument: gauge -Unit: {Hz} +Deprecated: Replaced by `cpu.frequency`. """ def create_system_cpu_frequency( meter: Meter, callbacks: Optional[Sequence[CallbackT]] ) -> ObservableGauge: - """Reports the current frequency of the CPU in Hz""" + """Deprecated. Use `cpu.frequency` instead""" return meter.create_observable_gauge( name=SYSTEM_CPU_FREQUENCY, callbacks=callbacks, - description="Reports the current frequency of the CPU in Hz", + description="Deprecated. Use `cpu.frequency` instead.", unit="{Hz}", ) @@ -96,37 +94,33 @@ def create_system_cpu_physical_count(meter: Meter) -> UpDownCounter: SYSTEM_CPU_TIME: Final = "system.cpu.time" """ -Seconds each logical CPU spent on each mode -Instrument: counter -Unit: s +Deprecated: Replaced by `cpu.time`. """ def create_system_cpu_time(meter: Meter) -> Counter: - """Seconds each logical CPU spent on each mode""" + """Deprecated. Use `cpu.time` instead""" return meter.create_counter( name=SYSTEM_CPU_TIME, - description="Seconds each logical CPU spent on each mode", + description="Deprecated. Use `cpu.time` instead.", unit="s", ) SYSTEM_CPU_UTILIZATION: Final = "system.cpu.utilization" """ -Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs -Instrument: gauge -Unit: 1 +Deprecated: Replaced by `cpu.utilization`. """ def create_system_cpu_utilization( meter: Meter, callbacks: Optional[Sequence[CallbackT]] ) -> ObservableGauge: - """Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs""" + """Deprecated. Use `cpu.utilization` instead""" return meter.create_observable_gauge( name=SYSTEM_CPU_UTILIZATION, callbacks=callbacks, - description="Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs", + description="Deprecated. Use `cpu.utilization` instead.", unit="1", ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py index 1a5baeeb4c0..404eef1b42c 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py @@ -32,7 +32,7 @@ Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. -![Experimental](https://img.shields.io/badge/-experimental-blue) +![Development](https://img.shields.io/badge/-development-blue) Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`: @@ -58,7 +58,7 @@ The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component. Note: Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. -![Experimental](https://img.shields.io/badge/-experimental-blue) +![Development](https://img.shields.io/badge/-development-blue) Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`: * [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py index edb05a563da..bea8b2cff4e 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py @@ -50,5 +50,10 @@ class Schemas(Enum): """ The URL of the OpenTelemetry schema version 1.30.0. """ + + V1_31_0 = "https://opentelemetry.io/schemas/1.31.0" + """ + The URL of the OpenTelemetry schema version 1.31.0. + """ # when generating new semantic conventions, # make sure to add new versions version here. diff --git a/scripts/semconv/generate.sh b/scripts/semconv/generate.sh index 0525f6ced1f..4effd3ff8fd 100755 --- a/scripts/semconv/generate.sh +++ b/scripts/semconv/generate.sh @@ -5,7 +5,7 @@ SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" ROOT_DIR="${SCRIPT_DIR}/../.." # freeze the spec version to make SemanticAttributes generation reproducible -SEMCONV_VERSION=1.30.0 +SEMCONV_VERSION=1.31.0 SEMCONV_VERSION_TAG=v$SEMCONV_VERSION OTEL_WEAVER_IMG_VERSION=v0.12.0 INCUBATING_DIR=_incubating diff --git a/scripts/semconv/templates/registry/semantic_metrics.j2 b/scripts/semconv/templates/registry/semantic_metrics.j2 index 49550cf538e..c57578d3d01 100644 --- a/scripts/semconv/templates/registry/semantic_metrics.j2 +++ b/scripts/semconv/templates/registry/semantic_metrics.j2 @@ -88,7 +88,7 @@ def create_{{ metric_name }}(meter: Meter) -> {{metric.instrument | map_text("py {%- if metric.instrument == "gauge" %} callbacks=callbacks, {%- endif %} - description="{{ c.str_or_empty(metric.brief) }}", + description="{{ c.str_or_empty(metric.brief|trim) }}", unit="{{ metric.unit }}", ) {%- endif -%}