From 824083faa0b359b7d868d9d399032fa11bac0df6 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Mon, 2 Dec 2024 12:35:40 +0100 Subject: [PATCH 1/2] opentelemetry-semantic-conventions: Bump semantic conventions to 1.29.0 --- .../_incubating/attributes/cicd_attributes.py | 4 +- .../attributes/cloud_attributes.py | 6 +- .../attributes/cloudfoundry_attributes.py | 2 +- .../_incubating/attributes/db_attributes.py | 80 ++++++- .../attributes/deployment_attributes.py | 4 +- .../_incubating/attributes/faas_attributes.py | 12 +- .../attributes/feature_flag_attributes.py | 57 ++++- .../attributes/gen_ai_attributes.py | 23 +- .../_incubating/attributes/geo_attributes.py | 68 ++++++ .../_incubating/attributes/k8s_attributes.py | 6 +- .../attributes/messaging_attributes.py | 2 +- .../attributes/network_attributes.py | 5 + .../attributes/process_attributes.py | 15 +- .../attributes/service_attributes.py | 2 +- .../_incubating/attributes/test_attributes.py | 4 +- .../attributes/user_agent_attributes.py | 14 ++ .../_incubating/attributes/vcs_attributes.py | 138 +++++++++++- .../_incubating/metrics/container_metrics.py | 22 ++ .../semconv/_incubating/metrics/db_metrics.py | 59 +++++ .../_incubating/metrics/k8s_metrics.py | 112 +++++++++ .../_incubating/metrics/process_metrics.py | 12 +- .../_incubating/metrics/system_metrics.py | 22 ++ .../_incubating/metrics/vcs_metrics.py | 213 ++++++++++++++++++ .../semconv/attributes/error_attributes.py | 4 +- .../semconv/attributes/network_attributes.py | 11 +- .../semconv/attributes/url_attributes.py | 39 +++- .../src/opentelemetry/semconv/schemas.py | 5 + scripts/semconv/generate.sh | 2 +- .../templates/registry/semantic_attributes.j2 | 4 +- 29 files changed, 883 insertions(+), 64 deletions(-) create mode 100644 opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/geo_attributes.py create mode 100644 opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/vcs_metrics.py 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 f761ddf7fa0..674d8cfe9d3 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 @@ -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" 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 6836db55365..11b912d6605 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 @@ -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//resourceGroups//providers/Microsoft.Web/sites//functions/`. This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cloudfoundry_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cloudfoundry_attributes.py index 19fc6843e58..31b2d85a654 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/cloudfoundry_attributes.py +++ b/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. 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 2f3b5bae7e8..85e10235e1f 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 @@ -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,6 +103,11 @@ 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`. @@ -105,12 +115,18 @@ 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 `` 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 `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` 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 `` 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 `` 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.""" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/deployment_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/deployment_attributes.py index 3909329c763..a37626c2a6f 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/deployment_attributes.py +++ b/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" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/faas_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/faas_attributes.py index 473b6542732..22a9b24c96b 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/faas_attributes.py +++ b/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 `/`, i.e., function app name +- **Azure:** The full name `/`, 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. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/feature_flag_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/feature_flag_attributes.py index 57bf93ff624..30b56abbb39 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/feature_flag_attributes.py +++ b/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.""" 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 dbaf4525215..46c6d1bcedb 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 @@ -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): diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/geo_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/geo_attributes.py new file mode 100644 index 00000000000..573e52384d9 --- /dev/null +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/geo_attributes.py @@ -0,0 +1,68 @@ +# 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 enum import Enum +from typing import Final + +GEO_CONTINENT_CODE: Final = "geo.continent.code" +""" +Two-letter code representing continent’s name. +""" + +GEO_COUNTRY_ISO_CODE: Final = "geo.country.iso_code" +""" +Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://wikipedia.org/wiki/ISO_3166-1#Codes)). +""" + +GEO_LOCALITY_NAME: Final = "geo.locality.name" +""" +Locality name. Represents the name of a city, town, village, or similar populated place. +""" + +GEO_LOCATION_LAT: Final = "geo.location.lat" +""" +Latitude of the geo location in [WGS84](https://wikipedia.org/wiki/World_Geodetic_System#WGS84). +""" + +GEO_LOCATION_LON: Final = "geo.location.lon" +""" +Longitude of the geo location in [WGS84](https://wikipedia.org/wiki/World_Geodetic_System#WGS84). +""" + +GEO_POSTAL_CODE: Final = "geo.postal_code" +""" +Postal code associated with the location. Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. +""" + +GEO_REGION_ISO_CODE: Final = "geo.region.iso_code" +""" +Region ISO code ([ISO 3166-2](https://wikipedia.org/wiki/ISO_3166-2)). +""" + + +class GeoContinentCodeValues(Enum): + AF = "AF" + """Africa.""" + AN = "AN" + """Antarctica.""" + AS = "AS" + """Asia.""" + EU = "EU" + """Europe.""" + NA = "NA" + """North America.""" + OC = "OC" + """Oceania.""" + SA = "SA" + """South America.""" 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 e72d0ca616b..40d824894e7 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 @@ -39,9 +39,9 @@ Which states: > If generated according to one of the mechanisms defined in Rec. - ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be - different from all other UUIDs generated before 3603 A.D., or is - extremely likely to be different (depending on the mechanism chosen). +> ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be +> different from all other UUIDs generated before 3603 A.D., or is +> extremely likely to be different (depending on the mechanism chosen). Therefore, UIDs between clusters should be extremely unlikely to conflict. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/messaging_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/messaging_attributes.py index 8a58729cde7..88b374b484c 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/messaging_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/messaging_attributes.py @@ -26,7 +26,7 @@ A unique identifier for the client that consumes or produces a message. """ -# MESSAGING_CLIENT_ID : Final = "messaging.client_id" +# MESSAGING_CLIENT_ID: Final = "messaging.client_id" # Deprecated: Replaced by `messaging.client.id`. MESSAGING_CONSUMER_GROUP_NAME: Final = "messaging.consumer.group.name" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/network_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/network_attributes.py index 0742e6e6a5f..a569a2881a0 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/network_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/network_attributes.py @@ -47,6 +47,11 @@ The internet connection type. """ +NETWORK_INTERFACE_NAME: Final = "network.interface.name" +""" +The network interface name. +""" + NETWORK_IO_DIRECTION: Final = "network.io.direction" """ The network IO operation direction. 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 ca6c8b399b7..cc2c25481e9 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 @@ -63,11 +63,18 @@ The Go build ID as retrieved by `go tool buildid `. """ +PROCESS_EXECUTABLE_BUILD_ID_HTLHASH: Final = ( + "process.executable.build_id.htlhash" +) +""" +Profiling specific build ID for executables. See the OTel specification for Profiles for more information. +""" + PROCESS_EXECUTABLE_BUILD_ID_PROFILING: Final = ( "process.executable.build_id.profiling" ) """ -Profiling specific build ID for executables. See the OTel specification for Profiles for more information. +Deprecated: Replaced by `process.executable.build_id.htlhash`. """ PROCESS_EXECUTABLE_NAME: Final = "process.executable.name" @@ -100,6 +107,12 @@ Whether the process is connected to an interactive shell. """ +PROCESS_LINUX_CGROUP: Final = "process.linux.cgroup" +""" +The control group associated with the process. +Note: Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc//cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file. +""" + PROCESS_OWNER: Final = "process.owner" """ The username of the user that owns the process. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/service_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/service_attributes.py index 4019b483cef..f50686ff67d 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/service_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/service_attributes.py @@ -29,7 +29,7 @@ UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is needed. Similar to what can be seen in the man page for the -[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying +[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) file, the underlying data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it or not via another resource attribute. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/test_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/test_attributes.py index 43e017ff8d0..201c9bd8764 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/test_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/test_attributes.py @@ -17,7 +17,7 @@ TEST_CASE_NAME: Final = "test.case.name" """ -The fully qualified human readable name of the [test case](https://en.wikipedia.org/wiki/Test_case). +The fully qualified human readable name of the [test case](https://wikipedia.org/wiki/Test_case). """ TEST_CASE_RESULT_STATUS: Final = "test.case.result.status" @@ -27,7 +27,7 @@ TEST_SUITE_NAME: Final = "test.suite.name" """ -The human readable name of a [test suite](https://en.wikipedia.org/wiki/Test_suite). +The human readable name of a [test suite](https://wikipedia.org/wiki/Test_suite). """ TEST_SUITE_RUN_STATUS: Final = "test.suite.run.status" 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 2583a1d3145..a2b133cfe6c 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 @@ -12,6 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. +from enum import Enum from typing import Final USER_AGENT_NAME: Final = "user_agent.name" @@ -25,8 +26,21 @@ Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.user_agent_attributes.USER_AGENT_ORIGINAL`. """ +USER_AGENT_SYNTHETIC_TYPE: Final = "user_agent.synthetic.type" +""" +Specifies the category of synthetic traffic, such as tests or bots. +Note: This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +""" + USER_AGENT_VERSION: Final = "user_agent.version" """ Version of the user-agent extracted from original. Usually refers to the browser's version. Note: [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name`. """ + + +class UserAgentSyntheticTypeValues(Enum): + BOT = "bot" + """Bot source.""" + TEST = "test" + """Synthetic test source.""" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/vcs_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/vcs_attributes.py index e075ceb9cca..fcb1bee01b5 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/vcs_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/vcs_attributes.py @@ -15,22 +15,34 @@ from enum import Enum from typing import Final -VCS_REPOSITORY_CHANGE_ID: Final = "vcs.repository.change.id" +from deprecated import deprecated + +VCS_CHANGE_ID: Final = "vcs.change.id" """ -The ID of the change (pull request/merge request) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. +The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. """ -VCS_REPOSITORY_CHANGE_TITLE: Final = "vcs.repository.change.title" +VCS_CHANGE_STATE: Final = "vcs.change.state" """ -The human readable title of the change (pull request/merge request). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. +The state of the change (pull request/merge request/changelist). """ -VCS_REPOSITORY_REF_NAME: Final = "vcs.repository.ref.name" +VCS_CHANGE_TITLE: Final = "vcs.change.title" +""" +The human readable title of the change (pull request/merge request/changelist). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. +""" + +VCS_LINE_CHANGE_TYPE: Final = "vcs.line_change.type" +""" +The type of line change being measured on a branch or change. +""" + +VCS_REF_BASE_NAME: Final = "vcs.ref.base.name" """ The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. """ -VCS_REPOSITORY_REF_REVISION: Final = "vcs.repository.ref.revision" +VCS_REF_BASE_REVISION: Final = "vcs.ref.base.revision" """ The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. Note: The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), @@ -39,24 +51,132 @@ not necessarily have to be a hash; it can simply define a [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where -it is identical to the `ref.name`, it SHOULD still be included. It is +it is identical to the `ref.base.name`, it SHOULD still be included. It is up to the implementer to decide which value to set as the revision based on the VCS system and situational context. """ -VCS_REPOSITORY_REF_TYPE: Final = "vcs.repository.ref.type" +VCS_REF_BASE_TYPE: Final = "vcs.ref.base.type" +""" +The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. +""" + +VCS_REF_HEAD_NAME: Final = "vcs.ref.head.name" +""" +The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. +""" + +VCS_REF_HEAD_REVISION: Final = "vcs.ref.head.revision" +""" +The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. +Note: The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a +[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +it is identical to the `ref.head.name`, it SHOULD still be included. It is +up to the implementer to decide which value to set as the revision +based on the VCS system and situational context. +""" + +VCS_REF_HEAD_TYPE: Final = "vcs.ref.head.type" """ The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. """ +VCS_REF_TYPE: Final = "vcs.ref.type" +""" +The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. +""" + +VCS_REPOSITORY_CHANGE_ID: Final = "vcs.repository.change.id" +""" +Deprecated: Deprecated, use `vcs.change.id` instead. +""" + +VCS_REPOSITORY_CHANGE_TITLE: Final = "vcs.repository.change.title" +""" +Deprecated: Deprecated, use `vcs.change.title` instead. +""" + +VCS_REPOSITORY_REF_NAME: Final = "vcs.repository.ref.name" +""" +Deprecated: Deprecated, use `vcs.ref.head.name` instead. +""" + +VCS_REPOSITORY_REF_REVISION: Final = "vcs.repository.ref.revision" +""" +Deprecated: Deprecated, use `vcs.ref.head.revision` instead. +""" + +VCS_REPOSITORY_REF_TYPE: Final = "vcs.repository.ref.type" +""" +Deprecated: Deprecated, use `vcs.ref.head.type` instead. +""" + VCS_REPOSITORY_URL_FULL: Final = "vcs.repository.url.full" """ -The [URL](https://en.wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. +The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. +""" + +VCS_REVISION_DELTA_DIRECTION: Final = "vcs.revision_delta.direction" +""" +The type of revision comparison. """ +class VcsChangeStateValues(Enum): + OPEN = "open" + """Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments.""" + WIP = "wip" + """WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes.""" + CLOSED = "closed" + """Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request.""" + MERGED = "merged" + """Merged indicates that the change has been successfully integrated into the target codebase.""" + + +class VcsLineChangeTypeValues(Enum): + ADDED = "added" + """How many lines were added.""" + REMOVED = "removed" + """How many lines were removed.""" + + +class VcsRefBaseTypeValues(Enum): + BRANCH = "branch" + """[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch).""" + TAG = "tag" + """[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag).""" + + +class VcsRefHeadTypeValues(Enum): + BRANCH = "branch" + """[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch).""" + TAG = "tag" + """[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag).""" + + +class VcsRefTypeValues(Enum): + BRANCH = "branch" + """[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch).""" + TAG = "tag" + """[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag).""" + + +@deprecated( + reason="The attribute vcs.repository.ref.type is deprecated - Deprecated, use `vcs.ref.head.type` instead" +) # type: ignore class VcsRepositoryRefTypeValues(Enum): BRANCH = "branch" """[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch).""" TAG = "tag" """[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag).""" + + +class VcsRevisionDeltaDirectionValues(Enum): + BEHIND = "behind" + """How many revisions the change is behind the target ref.""" + AHEAD = "ahead" + """How many revisions the change is ahead of the target ref.""" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/container_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/container_metrics.py index 76b09419dec..ca4a91317a0 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/container_metrics.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/container_metrics.py @@ -128,3 +128,25 @@ def create_container_network_io(meter: Meter) -> Counter: description="Network bytes for the container.", unit="By", ) + + +CONTAINER_UPTIME: Final = "container.uptime" +""" +The time the container has been running +Instrument: gauge +Unit: s +Note: Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. +The actual accuracy would depend on the instrumentation and operating system. +""" + + +def create_container_uptime( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The time the container has been running""" + return meter.create_observable_gauge( + name=CONTAINER_UPTIME, + callbacks=callbacks, + description="The time the container has been running", + unit="s", + ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/db_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/db_metrics.py index 077207616a7..24ac4527ef0 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/db_metrics.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/db_metrics.py @@ -313,6 +313,48 @@ def create_db_client_connections_wait_time(meter: Meter) -> Histogram: ) +DB_CLIENT_COSMOSDB_ACTIVE_INSTANCE_COUNT: Final = ( + "db.client.cosmosdb.active_instance.count" +) +""" +Number of active client instances +Instrument: updowncounter +Unit: {instance} +""" + + +def create_db_client_cosmosdb_active_instance_count( + meter: Meter, +) -> UpDownCounter: + """Number of active client instances""" + return meter.create_up_down_counter( + name=DB_CLIENT_COSMOSDB_ACTIVE_INSTANCE_COUNT, + description="Number of active client instances", + unit="{instance}", + ) + + +DB_CLIENT_COSMOSDB_OPERATION_REQUEST_CHARGE: Final = ( + "db.client.cosmosdb.operation.request_charge" +) +""" +[Request charge](https://learn.microsoft.com/azure/cosmos-db/request-units) consumed by the operation +Instrument: histogram +Unit: {request_unit} +""" + + +def create_db_client_cosmosdb_operation_request_charge( + meter: Meter, +) -> Histogram: + """[Request charge](https://learn.microsoft.com/azure/cosmos-db/request-units) consumed by the operation""" + return meter.create_histogram( + name=DB_CLIENT_COSMOSDB_OPERATION_REQUEST_CHARGE, + description="[Request charge](https://learn.microsoft.com/azure/cosmos-db/request-units) consumed by the operation", + unit="{request_unit}", + ) + + DB_CLIENT_OPERATION_DURATION: Final = "db.client.operation.duration" """ Duration of database client operations @@ -329,3 +371,20 @@ def create_db_client_operation_duration(meter: Meter) -> Histogram: description="Duration of database client operations.", unit="s", ) + + +DB_CLIENT_RESPONSE_RETURNED_ROWS: Final = "db.client.response.returned_rows" +""" +The actual number of records returned by the database operation +Instrument: histogram +Unit: {row} +""" + + +def create_db_client_response_returned_rows(meter: Meter) -> Histogram: + """The actual number of records returned by the database operation""" + return meter.create_histogram( + name=DB_CLIENT_RESPONSE_RETURNED_ROWS, + description="The actual number of records returned by the database operation.", + unit="{row}", + ) 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 feb85ab17c4..38fa254e767 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 @@ -97,6 +97,62 @@ def create_k8s_node_memory_usage( ) +K8S_NODE_NETWORK_ERRORS: Final = "k8s.node.network.errors" +""" +Node network errors +Instrument: counter +Unit: {error} +""" + + +def create_k8s_node_network_errors(meter: Meter) -> Counter: + """Node network errors""" + return meter.create_counter( + name=K8S_NODE_NETWORK_ERRORS, + description="Node network errors", + unit="{error}", + ) + + +K8S_NODE_NETWORK_IO: Final = "k8s.node.network.io" +""" +Network bytes for the Node +Instrument: counter +Unit: By +""" + + +def create_k8s_node_network_io(meter: Meter) -> Counter: + """Network bytes for the Node""" + return meter.create_counter( + name=K8S_NODE_NETWORK_IO, + description="Network bytes for the Node", + unit="By", + ) + + +K8S_NODE_UPTIME: Final = "k8s.node.uptime" +""" +The time the Node has been running +Instrument: gauge +Unit: s +Note: Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. +The actual accuracy would depend on the instrumentation and operating system. +""" + + +def create_k8s_node_uptime( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The time the Node has been running""" + return meter.create_observable_gauge( + name=K8S_NODE_UPTIME, + callbacks=callbacks, + description="The time the Node has been running", + unit="s", + ) + + K8S_POD_CPU_TIME: Final = "k8s.pod.cpu.time" """ Total CPU time consumed @@ -155,3 +211,59 @@ def create_k8s_pod_memory_usage( description="Memory usage of the Pod", unit="By", ) + + +K8S_POD_NETWORK_ERRORS: Final = "k8s.pod.network.errors" +""" +Pod network errors +Instrument: counter +Unit: {error} +""" + + +def create_k8s_pod_network_errors(meter: Meter) -> Counter: + """Pod network errors""" + return meter.create_counter( + name=K8S_POD_NETWORK_ERRORS, + description="Pod network errors", + unit="{error}", + ) + + +K8S_POD_NETWORK_IO: Final = "k8s.pod.network.io" +""" +Network bytes for the Pod +Instrument: counter +Unit: By +""" + + +def create_k8s_pod_network_io(meter: Meter) -> Counter: + """Network bytes for the Pod""" + return meter.create_counter( + name=K8S_POD_NETWORK_IO, + description="Network bytes for the Pod", + unit="By", + ) + + +K8S_POD_UPTIME: Final = "k8s.pod.uptime" +""" +The time the Pod has been running +Instrument: gauge +Unit: s +Note: Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. +The actual accuracy would depend on the instrumentation and operating system. +""" + + +def create_k8s_pod_uptime( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The time the Pod has been running""" + return meter.create_observable_gauge( + name=K8S_POD_UPTIME, + callbacks=callbacks, + description="The time the Pod has been running", + unit="s", + ) 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 881776c217b..3b7f5012114 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 @@ -216,16 +216,20 @@ def create_process_thread_count(meter: Meter) -> UpDownCounter: PROCESS_UPTIME: Final = "process.uptime" """ The time the process has been running -Instrument: counter +Instrument: gauge Unit: s -Note: Instrumentations SHOULD use counter with type `double` and measure uptime with at least millisecond precision. +Note: Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. +The actual accuracy would depend on the instrumentation and operating system. """ -def create_process_uptime(meter: Meter) -> Counter: +def create_process_uptime( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: """The time the process has been running""" - return meter.create_counter( + return meter.create_observable_gauge( name=PROCESS_UPTIME, + callbacks=callbacks, description="The time the process has been running.", unit="s", ) 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 8851929dd3f..0c894bd2ff3 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 @@ -591,3 +591,25 @@ def create_system_process_created(meter: Meter) -> Counter: description="Total number of processes created over uptime of the host", unit="{process}", ) + + +SYSTEM_UPTIME: Final = "system.uptime" +""" +The time the system has been running +Instrument: gauge +Unit: s +Note: Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. +The actual accuracy would depend on the instrumentation and operating system. +""" + + +def create_system_uptime( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The time the system has been running""" + return meter.create_observable_gauge( + name=SYSTEM_UPTIME, + callbacks=callbacks, + description="The time the system has been running", + unit="s", + ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/vcs_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/vcs_metrics.py new file mode 100644 index 00000000000..03e1882e724 --- /dev/null +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/vcs_metrics.py @@ -0,0 +1,213 @@ +# 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, + Meter, + ObservableGauge, + Observation, + UpDownCounter, +) + +# pylint: disable=invalid-name +CallbackT = Union[ + Callable[[CallbackOptions], Iterable[Observation]], + Generator[Iterable[Observation], CallbackOptions, None], +] + +VCS_CHANGE_COUNT: Final = "vcs.change.count" +""" +The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged) +Instrument: updowncounter +Unit: {change} +""" + + +def create_vcs_change_count(meter: Meter) -> UpDownCounter: + """The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged)""" + return meter.create_up_down_counter( + name=VCS_CHANGE_COUNT, + description="The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged)", + unit="{change}", + ) + + +VCS_CHANGE_DURATION: Final = "vcs.change.duration" +""" +The time duration a change (pull request/merge request/changelist) has been in a given state +Instrument: gauge +Unit: s +""" + + +def create_vcs_change_duration( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The time duration a change (pull request/merge request/changelist) has been in a given state""" + return meter.create_observable_gauge( + name=VCS_CHANGE_DURATION, + callbacks=callbacks, + description="The time duration a change (pull request/merge request/changelist) has been in a given state.", + unit="s", + ) + + +VCS_CHANGE_TIME_TO_APPROVAL: Final = "vcs.change.time_to_approval" +""" +The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval +Instrument: gauge +Unit: s +""" + + +def create_vcs_change_time_to_approval( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval""" + return meter.create_observable_gauge( + name=VCS_CHANGE_TIME_TO_APPROVAL, + callbacks=callbacks, + description="The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval", + unit="s", + ) + + +VCS_CONTRIBUTOR_COUNT: Final = "vcs.contributor.count" +""" +The number of unique contributors to a repository +Instrument: gauge +Unit: {contributor} +""" + + +def create_vcs_contributor_count( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The number of unique contributors to a repository""" + return meter.create_observable_gauge( + name=VCS_CONTRIBUTOR_COUNT, + callbacks=callbacks, + description="The number of unique contributors to a repository", + unit="{contributor}", + ) + + +VCS_REF_COUNT: Final = "vcs.ref.count" +""" +The number of refs of type branch or tag in a repository +Instrument: updowncounter +Unit: {ref} +""" + + +def create_vcs_ref_count(meter: Meter) -> UpDownCounter: + """The number of refs of type branch or tag in a repository""" + return meter.create_up_down_counter( + name=VCS_REF_COUNT, + description="The number of refs of type branch or tag in a repository", + unit="{ref}", + ) + + +VCS_REF_LINES_DELTA: Final = "vcs.ref.lines_delta" +""" +The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute +Instrument: gauge +Unit: {line} +Note: This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, +instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). +If number of lines added/removed should be calculated from the start of time, then `vcs.ref.base.name` SHOULD be set to an empty string. +""" + + +def create_vcs_ref_lines_delta( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute""" + return meter.create_observable_gauge( + name=VCS_REF_LINES_DELTA, + callbacks=callbacks, + description="The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute", + unit="{line}", + ) + + +VCS_REF_REVISIONS_DELTA: Final = "vcs.ref.revisions_delta" +""" +The number of revisions (commits) a ref (branch) is ahead/behind the branch from the `vcs.ref.base.name` attribute +Instrument: gauge +Unit: {revision} +Note: This metric should be reported for each `vcs.revision_delta.direction` value. For example if branch `a` is 3 commits behind and 2 commits ahead of `trunk`, +instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`. +""" + + +def create_vcs_ref_revisions_delta( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """The number of revisions (commits) a ref (branch) is ahead/behind the branch from the `vcs.ref.base.name` attribute""" + return meter.create_observable_gauge( + name=VCS_REF_REVISIONS_DELTA, + callbacks=callbacks, + description="The number of revisions (commits) a ref (branch) is ahead/behind the branch from the `vcs.ref.base.name` attribute", + unit="{revision}", + ) + + +VCS_REF_TIME: Final = "vcs.ref.time" +""" +Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch` +Instrument: gauge +Unit: s +""" + + +def create_vcs_ref_time( + meter: Meter, callbacks: Optional[Sequence[CallbackT]] +) -> ObservableGauge: + """Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch`""" + return meter.create_observable_gauge( + name=VCS_REF_TIME, + callbacks=callbacks, + description="Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch`", + unit="s", + ) + + +VCS_REPOSITORY_COUNT: Final = "vcs.repository.count" +""" +The number of repositories in an organization +Instrument: updowncounter +Unit: {repository} +""" + + +def create_vcs_repository_count(meter: Meter) -> UpDownCounter: + """The number of repositories in an organization""" + return meter.create_up_down_counter( + name=VCS_REPOSITORY_COUNT, + description="The number of repositories in an organization", + unit="{repository}", + ) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/error_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/error_attributes.py index 6d667c8db90..6ffd2b9bcf3 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/error_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/error_attributes.py @@ -35,8 +35,8 @@ If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it's RECOMMENDED to: -* Use a domain-specific attribute -* Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/network_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/network_attributes.py index 9d10cf8ca02..b585467bfb3 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/network_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/network_attributes.py @@ -15,6 +15,11 @@ from enum import Enum from typing import Final +NETWORK_INTERFACE_NAME: Final = "network.interface.name" +""" +The network interface name. +""" + NETWORK_LOCAL_ADDRESS: Final = "network.local.address" """ Local address of the network connection - IP address or Unix domain socket name. @@ -37,7 +42,7 @@ NETWORK_PROTOCOL_NAME: Final = "network.protocol.name" """ -[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. +[OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. Note: The value SHOULD be normalized to lowercase. """ @@ -49,7 +54,7 @@ NETWORK_TRANSPORT: Final = "network.transport" """ -[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). +[OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). Note: The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since @@ -59,7 +64,7 @@ NETWORK_TYPE: Final = "network.type" """ -[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. +[OSI network layer](https://wikipedia.org/wiki/Network_layer) or non-OSI equivalent. Note: The value SHOULD be normalized to lowercase. """ 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 29f853ee0e8..1a5baeeb4c0 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py @@ -22,9 +22,29 @@ URL_FULL: Final = "url.full" """ Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986). -Note: For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. +Note: For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment +is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. + +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. +In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. + +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + +Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +![Experimental](https://img.shields.io/badge/-experimental-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) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`https://www.example.com/path?color=blue&sig=REDACTED`. """ URL_PATH: Final = "url.path" @@ -37,6 +57,19 @@ """ 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) +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) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`q=OpenTelemetry&sig=REDACTED`. """ URL_SCHEME: Final = "url.scheme" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py index a565194705f..8171ef67e32 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/schemas.py @@ -41,5 +41,10 @@ class Schemas(Enum): The URL of the OpenTelemetry schema version 1.28.0. """ + V1_29_0 = "https://opentelemetry.io/schemas/1.29.0" + """ + The URL of the OpenTelemetry schema version 1.29.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 643bcc3c2a8..637e077c85c 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.28.0 +SEMCONV_VERSION=1.29.0 SEMCONV_VERSION_TAG=v$SEMCONV_VERSION OTEL_WEAVER_IMG_VERSION=v0.10.0 INCUBATING_DIR=_incubating diff --git a/scripts/semconv/templates/registry/semantic_attributes.j2 b/scripts/semconv/templates/registry/semantic_attributes.j2 index 1cc155712bd..5b89d0ceb68 100644 --- a/scripts/semconv/templates/registry/semantic_attributes.j2 +++ b/scripts/semconv/templates/registry/semantic_attributes.j2 @@ -53,7 +53,7 @@ from typing import Final {%- set multiline = attribute.name not in ctx.excluded_attributes -%} {%- set doc_string = write_docstring(attr_name, attribute.brief, attribute.note, attribute.deprecated, attribute.stability, multiline)-%} {%- set prefix = "" if multiline else "# " -%} -{{prefix}}{{attr_name}} : Final = "{{attribute.name}}" +{{prefix}}{{attr_name}}: Final = "{{attribute.name}}" {{prefix}}{{doc_string}} {% endfor %} @@ -70,4 +70,4 @@ class {{class_name}}(Enum): {{member_name}} = {{ member.value | print_member_value }} {% if doc_string %}"""{{doc_string}}"""{% endif %} {%- endfor %} -{% endfor %} \ No newline at end of file +{% endfor %} From 291ae6cfada24ce2171ed7c08077b2240a84ffc8 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Mon, 2 Dec 2024 12:41:54 +0100 Subject: [PATCH 2/2] Add changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 60759fb58ef..09ad03d8258 100644 --- a/CHANGELOG.md +++ b/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)