From 8ccb8c3cf5b1ff65f6cd4227c140a5904f27a793 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Sun, 2 Jun 2024 09:39:43 -0700 Subject: [PATCH 1/3] Switch to weaver to generate semantic conventions --- .../_incubating/attributes/aws_attributes.py | 66 ++++----- .../attributes/browser_attributes.py | 2 +- .../attributes/cloud_attributes.py | 28 ++-- .../attributes/container_attributes.py | 4 +- .../_incubating/attributes/db_attributes.py | 8 +- .../attributes/deployment_attributes.py | 10 +- .../_incubating/attributes/dns_attributes.py | 2 +- .../attributes/error_attributes.py | 2 +- .../_incubating/attributes/faas_attributes.py | 40 +++--- .../attributes/feature_flag_attributes.py | 12 +- .../_incubating/attributes/http_attributes.py | 20 +-- .../_incubating/attributes/k8s_attributes.py | 42 +++--- .../_incubating/attributes/log_attributes.py | 2 +- .../attributes/messaging_attributes.py | 15 +- .../attributes/network_attributes.py | 12 +- .../_incubating/attributes/oci_attributes.py | 2 +- .../_incubating/attributes/otel_attributes.py | 4 +- .../attributes/service_attributes.py | 50 +++---- .../attributes/system_attributes.py | 2 +- .../attributes/telemetry_attributes.py | 26 ++-- .../_incubating/attributes/url_attributes.py | 2 +- .../_incubating/metrics/process_metrics.py | 1 - .../_incubating/metrics/rpc_metrics.py | 16 +-- .../_incubating/metrics/system_metrics.py | 37 +++-- .../semconv/attributes/error_attributes.py | 24 ++-- .../attributes/exception_attributes.py | 26 ++-- .../semconv/attributes/http_attributes.py | 30 ++-- .../semconv/attributes/network_attributes.py | 6 +- .../attributes/telemetry_attributes.py | 10 +- .../semconv/attributes/url_attributes.py | 4 +- scripts/semconv/generate.sh | 51 +++---- scripts/semconv/templates/common.j2 | 26 ---- scripts/semconv/templates/registry/common.j2 | 42 ++++++ .../templates/registry/semantic_attributes.j2 | 72 ++++++++++ .../templates/registry/semantic_metrics.j2 | 96 +++++++++++++ .../semconv/templates/registry/weaver.yaml | 53 +++++++ .../semconv/templates/semantic_attributes.j2 | 96 ------------- scripts/semconv/templates/semantic_metrics.j2 | 136 ------------------ 38 files changed, 533 insertions(+), 544 deletions(-) delete mode 100644 scripts/semconv/templates/common.j2 create mode 100644 scripts/semconv/templates/registry/common.j2 create mode 100644 scripts/semconv/templates/registry/semantic_attributes.j2 create mode 100644 scripts/semconv/templates/registry/semantic_metrics.j2 create mode 100644 scripts/semconv/templates/registry/weaver.yaml delete mode 100644 scripts/semconv/templates/semantic_attributes.j2 delete mode 100644 scripts/semconv/templates/semantic_metrics.j2 diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/aws_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/aws_attributes.py index b8013202952..a208e56a601 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/aws_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/aws_attributes.py @@ -219,70 +219,70 @@ """ The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. Note: The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. - This applies to almost all S3 operations except `list-buckets`. +This applies to almost all S3 operations except `list-buckets`. """ AWS_S3_COPY_SOURCE: Final = "aws.s3.copy_source" """ The source object (in the form `bucket`/`key`) for the copy operation. Note: The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter - of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). - This applies in particular to the following operations: +of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). +This applies in particular to the following operations: - - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) - - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html). +- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html). """ AWS_S3_DELETE: Final = "aws.s3.delete" """ The delete request container that specifies the objects to be deleted. Note: The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. - The `delete` attribute corresponds to the `--delete` parameter of the - [delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). +The `delete` attribute corresponds to the `--delete` parameter of the +[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). """ AWS_S3_KEY: Final = "aws.s3.key" """ The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. Note: The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. - This applies in particular to the following operations: - - - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) - - [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) - - [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html) - - [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html) - - [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html) - - [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html) - - [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html) - - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) - - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) - - [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html) - - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) - - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html). +This applies in particular to the following operations: + +- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) +- [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) +- [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html) +- [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html) +- [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html) +- [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html) +- [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html) +- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) +- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) +- [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html) +- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) +- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html). """ AWS_S3_PART_NUMBER: Final = "aws.s3.part_number" """ The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. Note: The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. - The `part_number` attribute corresponds to the `--part-number` parameter of the - [upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). +and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. +The `part_number` attribute corresponds to the `--part-number` parameter of the +[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). """ AWS_S3_UPLOAD_ID: Final = "aws.s3.upload_id" """ Upload ID that identifies the multipart upload. Note: The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter - of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. - This applies in particular to the following operations: - - - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) - - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) - - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) - - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html). +of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. +This applies in particular to the following operations: + +- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) +- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) +- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) +- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html). """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/browser_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/browser_attributes.py index ea1dbd4d108..7cb14085c35 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/browser_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/browser_attributes.py @@ -36,5 +36,5 @@ """ The platform on which the browser is running. Note: This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. - The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. +The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. """ 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 ba42890a832..507aac0aea7 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 @@ -47,22 +47,22 @@ """ 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). 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. +so it may be necessary to set `cloud.resource_id` as a span attribute instead. - 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: +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). - 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 invokable 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, - *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 - a TracerProvider. +* **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 invokable 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, + *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 + a TracerProvider. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/container_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/container_attributes.py index cfa98a7a692..c83847ed034 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/container_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/container_attributes.py @@ -45,8 +45,8 @@ """ Runtime specific image identifier. Usually a hash algorithm followed by a UUID. Note: Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. - K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. - The ID is assigned by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. +K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. +The ID is assigned by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. """ CONTAINER_IMAGE_NAME: Final = "container.image.name" 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 671be74ec4d..7263e7b9e66 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 @@ -66,7 +66,7 @@ """ The name of a collection (table, container) within the database. Note: If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. - It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. """ DB_CONNECTION_STRING: Final = "db.connection_string" @@ -161,8 +161,8 @@ """ The name of the database, fully qualified within the server address and port. Note: If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. - Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. - It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. """ DB_OPERATION: Final = "db.operation" @@ -180,7 +180,7 @@ """ The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being 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. +If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. """ DB_QUERY_TEXT: Final = "db.query.text" 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 da93768810e..3890c5b71e4 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 @@ -18,10 +18,10 @@ """ Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). Note: `deployment.environment` does not affect the uniqueness constraints defined through - the `service.namespace`, `service.name` and `service.instance.id` resource attributes. - This implies that resources carrying the following attribute combinations MUST be - considered to be identifying the same service: +the `service.namespace`, `service.name` and `service.instance.id` resource attributes. +This implies that resources carrying the following attribute combinations MUST be +considered to be identifying the same service: - * `service.name=frontend`, `deployment.environment=production` - * `service.name=frontend`, `deployment.environment=staging`. +* `service.name=frontend`, `deployment.environment=production` +* `service.name=frontend`, `deployment.environment=staging`. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py index cfb00bcf307..95961b176f3 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py @@ -17,5 +17,5 @@ DNS_QUESTION_NAME: Final = "dns.question.name" """ The name being queried. -Note: If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \\t, \\r, and \\n respectively. +Note: If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/error_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/error_attributes.py index cbd436f053c..d3d33ff395c 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/error_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/error_attributes.py @@ -26,4 +26,4 @@ @deprecated(reason="Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.error_attributes.ErrorTypeValues`.") # type: ignore class ErrorTypeValues(Enum): OTHER = "_OTHER" - """A fallback error value to be used when the instrumentation doesn't define a custom value.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.error_attributes.ErrorTypeValues.OTHER`.""" 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 0603c23f004..473b6542732 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 @@ -84,21 +84,21 @@ """ The name of the single function that this runtime instance executes. Note: This is the name of the function as configured/deployed on the FaaS - platform and is usually different from the name of the callback - function (which may be stored in the - [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) - span attributes). +platform and is usually different from the name of the callback +function (which may be stored in the +[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) +span attributes). - For some cloud providers, the above definition is ambiguous. The following - definition of function name MUST be used for this attribute - (and consequently the span name) for the listed cloud providers/products: +For some cloud providers, the above definition is ambiguous. The following +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 - 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 - app can host multiple functions that would usually share - a TracerProvider (see also the `cloud.resource_id` attribute). +* **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 + app can host multiple functions that would usually share + a TracerProvider (see also the `cloud.resource_id` attribute). """ FAAS_TIME: Final = "faas.time" @@ -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) - (an integer represented as a decimal string). - * **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 - [`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. +* **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) + (i.e., the function name plus the revision suffix). +* **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. """ 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 f5a37f04c95..57bf93ff624 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 @@ -28,11 +28,11 @@ """ SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. 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`. +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. +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. """ diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/http_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/http_attributes.py index c2ef97e3d6f..7d86af7f2ce 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/http_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/http_attributes.py @@ -178,22 +178,22 @@ class HttpFlavorValues(Enum): @deprecated(reason="Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues`.") # type: ignore class HttpRequestMethodValues(Enum): CONNECT = "CONNECT" - """CONNECT method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.CONNECT`.""" DELETE = "DELETE" - """DELETE method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.DELETE`.""" GET = "GET" - """GET method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.GET`.""" HEAD = "HEAD" - """HEAD method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.HEAD`.""" OPTIONS = "OPTIONS" - """OPTIONS method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.OPTIONS`.""" PATCH = "PATCH" - """PATCH method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.PATCH`.""" POST = "POST" - """POST method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.POST`.""" PUT = "PUT" - """PUT method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.PUT`.""" TRACE = "TRACE" - """TRACE method.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.TRACE`.""" OTHER = "_OTHER" - """Any HTTP method that the instrumentation has no prior knowledge of.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.http_attributes.HttpRequestMethodValues.OTHER`.""" 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 f5faf841811..6cfbb491f54 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 @@ -23,27 +23,27 @@ """ A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. Note: K8s doesn't have support for obtaining a cluster ID. If this is ever - added, we will recommend collecting the `k8s.cluster.uid` through the - official APIs. In the meantime, we are able to use the `uid` of the - `kube-system` namespace as a proxy for cluster ID. Read on for the - rationale. - - Every object created in a K8s cluster is assigned a distinct UID. The - `kube-system` namespace is used by Kubernetes itself and will exist - for the lifetime of the cluster. Using the `uid` of the `kube-system` - namespace is a reasonable proxy for the K8s ClusterID as it will only - change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are - UUIDs as standardized by - [ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). - 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). - - Therefore, UIDs between clusters should be extremely unlikely to - conflict. +added, we will recommend collecting the `k8s.cluster.uid` through the +official APIs. In the meantime, we are able to use the `uid` of the +`kube-system` namespace as a proxy for cluster ID. Read on for the +rationale. + +Every object created in a K8s cluster is assigned a distinct UID. The +`kube-system` namespace is used by Kubernetes itself and will exist +for the lifetime of the cluster. Using the `uid` of the `kube-system` +namespace is a reasonable proxy for the K8s ClusterID as it will only +change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are +UUIDs as standardized by +[ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). +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). + +Therefore, UIDs between clusters should be extremely unlikely to +conflict. """ K8S_CONTAINER_NAME: Final = "k8s.container.name" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/log_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/log_attributes.py index 24d3df97363..ae713923b48 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/log_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/log_attributes.py @@ -44,7 +44,7 @@ """ A unique identifier for the Log Record. Note: If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. - The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. +The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. """ 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 c8cb1073ba8..df8386bfa9c 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,9 +26,10 @@ A unique identifier for the client that consumes or produces a message. """ -# MESSAGING_CLIENT_ID: Final = "messaging.client_id" - -# Deprecated: Replaced by `messaging.client.id`. +# MESSAGING_CLIENT_ID : Final = "messaging.client_id" +""" +Deprecated: Replaced by `messaging.client.id`. +""" MESSAGING_DESTINATION_ANONYMOUS: Final = "messaging.destination.anonymous" """ @@ -39,7 +40,7 @@ """ The message destination name. Note: Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If - the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. +the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. """ MESSAGING_DESTINATION_PARTITION_ID: Final = ( @@ -73,7 +74,7 @@ """ The name of the original destination the message was published to. Note: The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If - the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. +the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. """ MESSAGING_EVENTHUBS_CONSUMER_GROUP: Final = ( @@ -150,7 +151,7 @@ """ The size of the message body in bytes. Note: This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed - body size should be used. +body size should be used. """ MESSAGING_MESSAGE_CONVERSATION_ID: Final = "messaging.message.conversation_id" @@ -162,7 +163,7 @@ """ The size of the message body and metadata in bytes. Note: This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed - size should be used. +size should be used. """ MESSAGING_MESSAGE_ID: Final = "messaging.message.id" 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 2e595a72e2e..76b804a04da 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 @@ -161,18 +161,18 @@ class NetworkIoDirectionValues(Enum): @deprecated(reason="Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTransportValues`.") # type: ignore class NetworkTransportValues(Enum): TCP = "tcp" - """TCP.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTransportValues.TCP`.""" UDP = "udp" - """UDP.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTransportValues.UDP`.""" PIPE = "pipe" - """Named or anonymous pipe.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTransportValues.PIPE`.""" UNIX = "unix" - """Unix domain socket.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTransportValues.UNIX`.""" @deprecated(reason="Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTypeValues`.") # type: ignore class NetworkTypeValues(Enum): IPV4 = "ipv4" - """IPv4.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTypeValues.IPV4`.""" IPV6 = "ipv6" - """IPv6.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.network_attributes.NetworkTypeValues.IPV6`.""" 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 22c05bc4aea..51da3e92c5c 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://docs.docker.com/registry/spec/manifest-v2-2/#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 321dee6a7e6..b74c7094876 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 @@ -51,6 +51,6 @@ @deprecated(reason="Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.otel_attributes.OtelStatusCodeValues`.") # type: ignore class OtelStatusCodeValues(Enum): OK = "OK" - """The operation has been validated by an Application developer or Operator to have completed successfully.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.otel_attributes.OtelStatusCodeValues.OK`.""" ERROR = "ERROR" - """The operation contains an error.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.otel_attributes.OtelStatusCodeValues.ERROR`.""" 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 d1c729368be..4019b483cef 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 @@ -18,31 +18,31 @@ """ The string ID of the service instance. Note: MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words - `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to - distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled - service). - - Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC - 4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of - this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and - SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. - - 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 - 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. - - For applications running behind an application server (like unicorn), we do not recommend using one identifier - for all processes participating in the application. Instead, it's recommended each division (e.g. a worker - thread in unicorn) to have its own instance.id. - - It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the - service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will - likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. - However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance - for that telemetry. This is typically the case for scraping receivers, as they know the target address and - port. +`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to +distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled +service). + +Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC +4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of +this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and +SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. + +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 +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. + +For applications running behind an application server (like unicorn), we do not recommend using one identifier +for all processes participating in the application. Instead, it's recommended each division (e.g. a worker +thread in unicorn) to have its own instance.id. + +It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the +service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will +likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. +However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance +for that telemetry. This is typically the case for scraping receivers, as they know the target address and +port. """ SERVICE_NAME: Final = "service.name" 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 0f24440638c..f93a62c7bca 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 @@ -135,7 +135,7 @@ class SystemMemoryStateValues(Enum): FREE = "free" """free.""" SHARED = "shared" - """shared.""" + """Deprecated: Removed, report shared memory usage with `metric.system.memory.shared` metric.""" BUFFERS = "buffers" """buffers.""" CACHED = "cached" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/telemetry_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/telemetry_attributes.py index 44107c053a3..f871f19cfd0 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/telemetry_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/telemetry_attributes.py @@ -21,7 +21,7 @@ """ The name of the auto instrumentation agent or distribution, if used. Note: Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to - a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. +a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. """ TELEMETRY_DISTRO_VERSION: Final = "telemetry.distro.version" @@ -48,26 +48,26 @@ @deprecated(reason="Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues`.") # type: ignore class TelemetrySdkLanguageValues(Enum): CPP = "cpp" - """cpp.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.CPP`.""" DOTNET = "dotnet" - """dotnet.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.DOTNET`.""" ERLANG = "erlang" - """erlang.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.ERLANG`.""" GO = "go" - """go.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.GO`.""" JAVA = "java" - """java.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.JAVA`.""" NODEJS = "nodejs" - """nodejs.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.NODEJS`.""" PHP = "php" - """php.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.PHP`.""" PYTHON = "python" - """python.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.PYTHON`.""" RUBY = "ruby" - """ruby.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.RUBY`.""" RUST = "rust" - """rust.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.RUST`.""" SWIFT = "swift" - """swift.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.SWIFT`.""" WEBJS = "webjs" - """webjs.""" + """Deprecated in favor of stable :py:const:`opentelemetry.semconv.attributes.telemetry_attributes.TelemetrySdkLanguageValues.WEBJS`.""" 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 89ce57bd788..ebc92a1cf1b 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 @@ -40,7 +40,7 @@ """ Unmodified original URL as seen in the event source. Note: In network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. This field is meant to represent the URL as it was observed, complete or not. - `url.original` might contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case password and username SHOULD NOT be redacted and attribute's value SHOULD remain the same. +`url.original` might contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case password and username SHOULD NOT be redacted and attribute's value SHOULD remain the same. """ URL_PATH: Final = "url.path" 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 bfcdac86afb..4d499c74966 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 @@ -38,7 +38,6 @@ Generator[Iterable[Observation], CallbackOptions, None], ] - PROCESS_CONTEXT_SWITCHES: Final = "process.context_switches" """ Number of times the process has been context switched diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/rpc_metrics.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/rpc_metrics.py index ec05ff14bb0..e3f4ad6edd8 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/rpc_metrics.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/metrics/rpc_metrics.py @@ -23,9 +23,9 @@ Instrument: histogram Unit: ms Note: While streaming RPCs may record this metric as start-of-batch - to end-of-batch, it's hard to interpret in practice. +to end-of-batch, it's hard to interpret in practice. - **Streaming**: N/A. +**Streaming**: N/A. """ @@ -63,7 +63,7 @@ def create_rpc_client_request_size(meter: Meter) -> Histogram: Unit: {count} Note: Should be 1 for all non-streaming RPCs. - **Streaming**: This metric is required for server and client streaming RPCs. +**Streaming**: This metric is required for server and client streaming RPCs. """ @@ -101,7 +101,7 @@ def create_rpc_client_response_size(meter: Meter) -> Histogram: Unit: {count} Note: Should be 1 for all non-streaming RPCs. - **Streaming**: This metric is required for server and client streaming RPCs. +**Streaming**: This metric is required for server and client streaming RPCs. """ @@ -120,9 +120,9 @@ def create_rpc_client_responses_per_rpc(meter: Meter) -> Histogram: Instrument: histogram Unit: ms Note: While streaming RPCs may record this metric as start-of-batch - to end-of-batch, it's hard to interpret in practice. +to end-of-batch, it's hard to interpret in practice. - **Streaming**: N/A. +**Streaming**: N/A. """ @@ -160,7 +160,7 @@ def create_rpc_server_request_size(meter: Meter) -> Histogram: Unit: {count} Note: Should be 1 for all non-streaming RPCs. - **Streaming** : This metric is required for server and client streaming RPCs. +**Streaming** : This metric is required for server and client streaming RPCs. """ @@ -198,7 +198,7 @@ def create_rpc_server_response_size(meter: Meter) -> Histogram: Unit: {count} Note: Should be 1 for all non-streaming RPCs. - **Streaming**: This metric is required for server and client streaming RPCs. +**Streaming**: This metric is required for server and client streaming RPCs. """ 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 3d193ef1801..3854306461b 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 @@ -38,7 +38,6 @@ Generator[Iterable[Observation], CallbackOptions, None], ] - SYSTEM_CPU_FREQUENCY: Final = "system.cpu.frequency" """ Reports the current frequency of the CPU in Hz @@ -152,10 +151,10 @@ def create_system_disk_io(meter: Meter) -> Counter: Unit: s Note: The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as: - - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) - - Windows: The complement of - ["Disk\\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) - performance counter: `uptime * (100 - "Disk\\% Idle Time") / 100`. +- Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) +- Windows: The complement of + ["Disk\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + performance counter: `uptime * (100 - "Disk\% Idle Time") / 100`. """ @@ -190,8 +189,8 @@ def create_system_disk_merged(meter: Meter) -> Counter: Unit: s Note: Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as: - - Linux: Fields 7 & 11 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) - - Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes). +- Linux: Fields 7 & 11 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) +- Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes). """ @@ -258,10 +257,10 @@ def create_system_filesystem_utilization( Instrument: updowncounter Unit: By Note: This is an alternative to `system.memory.usage` metric with `state=free`. - Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values. - This is supposed to be more accurate than just "free" memory. - For reference, see the calculations [here](https://superuser.com/a/980821). - See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). +Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values. +This is supposed to be more accurate than just "free" memory. +For reference, see the calculations [here](https://superuser.com/a/980821). +See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). """ @@ -298,7 +297,7 @@ def create_system_memory_limit(meter: Meter) -> UpDownCounter: Instrument: updowncounter Unit: By Note: Equivalent of `shared` from [`free` command](https://man7.org/linux/man-pages/man1/free.1.html) or - `Shmem` from [`/proc/meminfo`](https://man7.org/linux/man-pages/man5/proc.5.html)". +`Shmem` from [`/proc/meminfo`](https://man7.org/linux/man-pages/man5/proc.5.html)". """ @@ -317,7 +316,7 @@ def create_system_memory_shared(meter: Meter) -> UpDownCounter: Instrument: updowncounter Unit: By Note: The sum over all `system.memory.state` values SHOULD equal the total memory - available on the system, that is `system.memory.limit`. +available on the system, that is `system.memory.limit`. """ @@ -370,9 +369,9 @@ def create_system_network_connections(meter: Meter) -> UpDownCounter: Unit: {packet} Note: Measured as: - - Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)) - - Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) - from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). +- Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)) +- Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). """ @@ -392,9 +391,9 @@ def create_system_network_dropped(meter: Meter) -> Counter: Unit: {error} Note: Measured as: - - Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). - - Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) - from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). +- Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). +- Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). """ 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 5b5069a46e7..6d667c8db90 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/error_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/error_attributes.py @@ -20,23 +20,23 @@ Describes a class of error the operation ended with. Note: The `error.type` SHOULD be predictable, and SHOULD have low cardinality. - When `error.type` is set to a type (e.g., an exception type), its - canonical class name identifying the type within the artifact SHOULD be used. +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. - Instrumentations SHOULD document the list of errors they report. +Instrumentations SHOULD document the list of errors they report. - The cardinality of `error.type` within one instrumentation library SHOULD be low. - Telemetry consumers that aggregate data from multiple instrumentation libraries and applications - should be prepared for `error.type` to have high cardinality at query time when no - additional filters are applied. +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. - If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. - If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), - it's RECOMMENDED to: +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/exception_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/exception_attributes.py index 1d1ebe84155..d51921c382d 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/exception_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/exception_attributes.py @@ -18,21 +18,21 @@ """ SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. Note: An exception is considered to have escaped (or left) the scope of a span, - if that span is ended while the exception is still logically "in flight". - This may be actually "in flight" in some languages (e.g. if the exception - is passed to a Context manager's `__exit__` method in Python) but will - usually be caught at the point of recording the exception in most languages. +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. - It is usually not possible to determine at the point where an exception is thrown - whether it will escape the scope of a span. - However, it is trivial to know that an exception - will escape, if one checks for an active exception just before ending the span, - as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). - It follows that an exception may still escape the scope of the span - even if the `exception.escaped` attribute was not set or set to false, - since the event might have been recorded at a time where it was not - clear whether the exception will escape. +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. """ EXCEPTION_MESSAGE: Final = "exception.message" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/http_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/http_attributes.py index 5d9af09c8dd..bec7c0c750a 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/http_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/http_attributes.py @@ -19,27 +19,27 @@ """ HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. Note: Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. - The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. - The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. +The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. """ HTTP_REQUEST_METHOD: Final = "http.request.method" """ HTTP request method. Note: HTTP request method value SHOULD be "known" to the instrumentation. - By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) - and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. - If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override - the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named - OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods - (this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). - HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. - Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. - Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. """ HTTP_REQUEST_METHOD_ORIGINAL: Final = "http.request.method_original" @@ -57,8 +57,8 @@ """ HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. Note: Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. - Users MAY explicitly configure instrumentations to capture them even though it is not recommended. - The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. """ HTTP_RESPONSE_STATUS_CODE: Final = "http.response.status_code" @@ -70,7 +70,7 @@ """ The matched route, that is, the path template in the format used by the respective server framework. Note: MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. - SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. """ 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 95476e35ce0..0181958a7c5 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/network_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/network_attributes.py @@ -52,9 +52,9 @@ [OSI transport layer](https://osi-model.com/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 - a port number is ambiguous without knowing the transport. For example - different processes could be listening on TCP port 12345 and UDP port 12345. +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. """ NETWORK_TYPE: Final = "network.type" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/telemetry_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/telemetry_attributes.py index 80686f9a77d..29aadeb72ba 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/telemetry_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/telemetry_attributes.py @@ -24,11 +24,11 @@ """ The name of the telemetry SDK as defined above. Note: The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. - If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the - `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point - or another suitable identifier depending on the language. - The identifier `opentelemetry` is reserved and MUST NOT be used in this case. - All custom identifiers SHOULD be stable across different versions of an implementation. +If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the +`telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point +or another suitable identifier depending on the language. +The identifier `opentelemetry` is reserved and MUST NOT be used in this case. +All custom identifiers SHOULD be stable across different versions of an implementation. """ TELEMETRY_SDK_VERSION: Final = "telemetry.sdk.version" 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 de32d49f665..29f853ee0e8 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes/url_attributes.py @@ -23,8 +23,8 @@ """ 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. +`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. """ URL_PATH: Final = "url.path" diff --git a/scripts/semconv/generate.sh b/scripts/semconv/generate.sh index 8c5dbdbea1b..9b52e9be8bf 100755 --- a/scripts/semconv/generate.sh +++ b/scripts/semconv/generate.sh @@ -1,13 +1,14 @@ #!/bin/bash set -e +set -x SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" -ROOT_DIR="${SCRIPT_DIR}/../../" +ROOT_DIR="${SCRIPT_DIR}/../.." # freeze the spec version to make SemanticAttributes generation reproducible SEMCONV_VERSION=1.26.0 SEMCONV_VERSION_TAG=v$SEMCONV_VERSION -OTEL_SEMCONV_GEN_IMG_VERSION=0.25.0 +OTEL_WEAVER_IMG_VERSION=0.7.0 INCUBATING_DIR=_incubating cd ${SCRIPT_DIR} @@ -29,49 +30,33 @@ if ! grep -q $SEMCONV_VERSION "$SCHEMAS_PY_PATH"; then exit 1 fi -# excluded namespaces will not be generated -# this behavior is fully controlled by jinja templates -EXCLUDED_NAMESPACES="jvm aspnetcore dotnet signalr ios android kestrel" - -# excluded attributes will be commented out in the generated code -# this behavior is fully controlled by jinja templates -EXCLUDED_ATTRIBUTES="messaging.client_id" - generate() { - TEMPLATE=$1 - OUTPUT_FILE=$2 + TARGET=$1 + OUTPUT=$2 FILTER=$3 - STABLE_PACKAGE=$4 docker run --rm \ -v ${SCRIPT_DIR}/semantic-conventions/model:/source \ -v ${SCRIPT_DIR}/templates:/templates \ -v ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/:/output \ - otel/semconvgen:$OTEL_SEMCONV_GEN_IMG_VERSION \ - -f /source \ - --continue-on-validation-errors \ - code \ - --template /templates/${TEMPLATE} \ - --output /output/${OUTPUT_FILE} \ - --file-per-group root_namespace \ - -Dfilter=${FILTER} \ - -Dstable_package=${STABLE_PACKAGE} \ - -Dexcluded_namespaces="$EXCLUDED_NAMESPACES" \ - -Dexcluded_attributes="$EXCLUDED_ATTRIBUTES" + otel/weaver:$OTEL_WEAVER_IMG_VERSION \ + registry \ + generate \ + --registry=/source \ + --templates=/templates \ + ${TARGET} \ + /output/${TARGET} \ + --param output=${OUTPUT} \ + --param filter=${FILTER} } # stable attributes and metrics mkdir -p ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/attributes -generate "semantic_attributes.j2" "attributes/{{snake_prefix}}_attributes.py" "is_stable" "" - mkdir -p ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/metrics -generate "semantic_metrics.j2" "metrics/{{snake_prefix}}_metrics.py" "is_stable" "" - -# all attributes and metrics -mkdir -p ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/$INCUBATING_DIR/attributes -generate "semantic_attributes.j2" "$INCUBATING_DIR/attributes/{{snake_prefix}}_attributes.py" "any" "opentelemetry.semconv.attributes" +generate "./" "./" "stable" -mkdir -p ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/$INCUBATING_DIR/metrics -generate "semantic_metrics.j2" "$INCUBATING_DIR/metrics/{{snake_prefix}}_metrics.py" "any" "opentelemetry.semconv.metrics" +mkdir -p ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/${INCUBATING_DIR}/attributes +mkdir -p ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/${INCUBATING_DIR}/metrics +generate "./" "./${INCUBATING_DIR}/" "any" cd "$ROOT_DIR" ${ROOT_DIR}/.tox/lint/bin/black --config pyproject.toml ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv diff --git a/scripts/semconv/templates/common.j2 b/scripts/semconv/templates/common.j2 deleted file mode 100644 index 8a1231f6e66..00000000000 --- a/scripts/semconv/templates/common.j2 +++ /dev/null @@ -1,26 +0,0 @@ -{%- macro file_header() -%} -# 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. - -{% endmacro -%} - -{%- macro to_docstring(str) -%} -{{ str | to_doc_brief | replace("\\", "\\\\") }} -{%- endmacro -%} - -{%- macro import_deprecated(semconv) -%} - {%- if (semconv | select("is_deprecated") | list | count > 0) or (filter == "any" and semconv | select("is_stable") | list | count > 0) %} -from deprecated import deprecated - {%- endif %} -{%- endmacro-%} diff --git a/scripts/semconv/templates/registry/common.j2 b/scripts/semconv/templates/registry/common.j2 new file mode 100644 index 00000000000..ae58c211fd4 --- /dev/null +++ b/scripts/semconv/templates/registry/common.j2 @@ -0,0 +1,42 @@ +{%- macro file_header() -%} +# 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. + +{% endmacro -%} + +{%- macro to_const_name(attr_name) -%} +{{attr_name | upper | replace('.', '_')}} +{%- endmacro %} + +{%- macro str_or_empty(str) -%} +{% if str is none %}{{""}}{% else %}{{str}}{% endif %} +{%- endmacro %} + +{%- macro remove_trailing_dots(str) -%} +{%- if str[-1:] == '.' -%}{{ remove_trailing_dots(str[:-1]) }}{%- else -%}{{ str }}{%- endif -%} +{%- endmacro -%} + +{%- macro comment_with_prefix(str, prefix) -%} +{{remove_trailing_dots(str | trim(' \n')) | comment_with_prefix(prefix)}} +{%- endmacro %} + +{%- macro import_deprecated(semconv) -%} + {%- if (semconv | select("deprecated") | list | count > 0) or (ctx.filter == "any" and semconv | select("stable") | list | count > 0) -%} +from deprecated import deprecated + {%- endif -%} +{%- endmacro-%} + +{%- macro print_value(type, value) -%} +{%- if type == "string" -%}"{{value}}"{%-else-%}{{value}}{%-endif-%} +{%- endmacro -%} diff --git a/scripts/semconv/templates/registry/semantic_attributes.j2 b/scripts/semconv/templates/registry/semantic_attributes.j2 new file mode 100644 index 00000000000..80fcdf7d783 --- /dev/null +++ b/scripts/semconv/templates/registry/semantic_attributes.j2 @@ -0,0 +1,72 @@ +# 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 + +{% set file_name = ctx.output + (ctx.root_namespace | kebab_case | replace('-', '_')) ~ "_attributes.py" -%} +{{- template.set_file_name(file_name) -}} +{%- import 'common.j2' as c %} + +{% set attributes = ctx.attributes | list %} +{% set enum_attributes = attributes | select("enum") | rejectattr("name", "in", ctx.excluded_attributes) | list %} +{% if enum_attributes | count > 0 %}from enum import Enum{% endif %} +{{c.import_deprecated(enum_attributes)}} + +{%- macro attribute_name(attribute) -%} +{{c.to_const_name(attribute.name)}}{%- if "template" in attribute.type -%}_TEMPLATE{%- endif -%} +{%- endmacro -%} + +{%- macro stable_class_ref(const_name, separator) -%} +{{ctx.stable_package_name}}.{{ctx.root_namespace}}_attributes{{separator}}{{const_name}} +{%- endmacro %} + +{%- macro write_docstring(name, brief, note, deprecated, stability, prefix) -%} + {%- if c.str_or_empty(deprecated)|length -%} +{{prefix}}Deprecated: {{c.comment_with_prefix(deprecated, prefix)}}. + {%- elif ctx.filter == "any" and stability == "stable" -%} +{{prefix}}Deprecated in favor of stable :py:const:`{{stable_class_ref(name, '.')}}`. + {%- elif c.str_or_empty(brief)|length -%} +{{prefix}}{{c.comment_with_prefix(brief, prefix)}}. + {%- if c.str_or_empty(note)|length %} +{{prefix}}Note: {{c.comment_with_prefix(note, prefix)}}. + {%- endif -%} + {%- endif -%} +{%- endmacro -%} + +{% for attribute in attributes %} +{% set attr_name = attribute_name(attribute) %} +{%- set prefix = "# " if attribute.name in ctx.excluded_attributes else "" -%} +{%- set doc_string=write_docstring(attr_name, attribute.brief, attribute.note, attribute.deprecated, attribute.stability, "")-%} +{{prefix}}{{attr_name}} : Final = "{{attribute.name}}" +{%- if doc_string %} +""" +{{doc_string}} +""" +{%- endif %} +{% endfor %} + +{% for attribute in enum_attributes %}{%- set class_name = attribute.name | pascal_case ~ "Values" -%} +{%- if attribute is deprecated %} +@deprecated(reason="The attribute {{attribute.name}} is deprecated - {{ c.comment_with_prefix(attribute.deprecated, "") }}") # type: ignore + {%- elif attribute.stability == "stable" and ctx.filter == "any" %} +@deprecated(reason="Deprecated in favor of stable :py:const:`{{stable_class_ref(class_name, '.')}}`.") # type: ignore + {%- endif %} +class {{class_name}}(Enum): + {%- for member in attribute.type.members %} + {% set member_name = c.to_const_name(member.id) -%} + {%- set doc_string=write_docstring(class_name + '.' + member_name, member.brief or member.id, "", member.deprecated, member.stability, "")-%} + {{member_name}} = {{c.print_value(attribute.type | instantiated_type, member.value) }} + {% if doc_string %}"""{{doc_string}}"""{% endif %} + {%- endfor %} +{% endfor %} \ No newline at end of file diff --git a/scripts/semconv/templates/registry/semantic_metrics.j2 b/scripts/semconv/templates/registry/semantic_metrics.j2 new file mode 100644 index 00000000000..0fe6a61eb89 --- /dev/null +++ b/scripts/semconv/templates/registry/semantic_metrics.j2 @@ -0,0 +1,96 @@ +# 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. + +{% set file_name = ctx.output + ctx.root_namespace | kebab_case | replace('-', '_') ~ "_metrics.py" -%} +{{- template.set_file_name(file_name) -}} + +{% import 'common.j2' as c -%} + +{%- macro stable_class_ref(const_name, separator) -%} +{{ctx.stable_package_name}}.{{ctx.root_namespace}}_metrics{{separator}}{{const_name}} +{%- endmacro %} + +{%- macro write_docstring(metric, const_name, prefix) -%} + {%- if metric is deprecated %} +{{prefix}}Deprecated: {{c.comment_with_prefix(metric.deprecated, prefix)}}. + {%- elif ctx.filter == "any" and metric.stability == "stable" %} +{{prefix}}Deprecated in favor of stable :py:const:`{{stable_class_ref(const_name, '.')}}`. + {%- else -%} + {%- if c.str_or_empty(metric.brief)|length %} +{{prefix}}{{c.comment_with_prefix(metric.brief, prefix)}} + {%- endif %} +{{prefix}}Instrument: {{ metric.instrument }} +{{prefix}}Unit: {{ metric.unit }} + {%- if c.str_or_empty(metric.note)|length %} +{{prefix}}Note: {{c.comment_with_prefix(metric.note, prefix)}}. + {%- endif -%} + {%- endif -%} +{%- endmacro -%} + +{%- macro import_instrument_classes(metrics) -%} + {% if ctx.filter == "any" %} +from opentelemetry.metrics import Meter + + {%- set instruments = ["counter", "histogram", "updowncounter"]-%} + {%- for i in instruments -%} + {%- if ctx.metrics | selectattr("instrument", "equalto", i) | list | count > 0 %} +from opentelemetry.metrics import {{i | map_text("py_instrument_to_type")}} + {%- endif -%} + {%- endfor-%} + + {%- if ctx.metrics | selectattr("instrument", "equalto", "gauge") | list | count > 0 %} +from typing import Callable, Generator, Iterable, Optional, Sequence, Union +from opentelemetry.metrics import CallbackOptions, ObservableGauge, Observation + +# pylint: disable=invalid-name +CallbackT = Union[ + Callable[[CallbackOptions], Iterable[Observation]], + Generator[Iterable[Observation], CallbackOptions, None], +] + {%- endif %} + + {%- endif -%} +{%- endmacro %} + +from typing import Final +{{ import_instrument_classes(filtered_metrics) }} + +{%- for metric in ctx.metrics | sort(attribute="metric_name") %} +{% set const_name = c.to_const_name(metric.metric_name) %} +{{const_name}}: Final = "{{metric.metric_name}}" +{%- set doc_string=write_docstring(metric, const_name, "")-%}{%- if doc_string %} +"""{{doc_string}} +"""{% endif %} + +{% if ctx.filter == "any" %} +{% set metric_name = metric.metric_name | replace(".", "_") %} +{%- if metric.instrument == "gauge" %} +def create_{{ metric_name }}(meter: Meter, callbacks: Optional[Sequence[CallbackT]]) -> {{metric.instrument | map_text("py_instrument_to_type")}}: +{%- else %} +def create_{{ metric_name }}(meter: Meter) -> {{metric.instrument | map_text("py_instrument_to_type")}}: +{%- endif %} + {%- if c.str_or_empty(metric.brief) |length %} + """{{ c.comment_with_prefix(metric.brief, "") }}""" + {% endif -%} + return meter.create_{{ metric.instrument | map_text("py_instrument_to_factory")}}( + name={{ const_name }}, + {%- if metric.instrument == "gauge" %} + callbacks=callbacks, + {%- endif %} + description="{{ c.str_or_empty(metric.brief) }}", + unit="{{ metric.unit }}", + ) + {%- endif -%} + +{% endfor %} diff --git a/scripts/semconv/templates/registry/weaver.yaml b/scripts/semconv/templates/registry/weaver.yaml new file mode 100644 index 00000000000..dd7f708beb2 --- /dev/null +++ b/scripts/semconv/templates/registry/weaver.yaml @@ -0,0 +1,53 @@ +params: + # excluded namespaces will not be generated + # this behavior is fully controlled by jinja templates + excluded_namespaces: [ios, aspnetcore, signalr, android, dotnet, jvm, kestrel] + + # excluded attributes will be commented out in the generated code + # this behavior is fully controlled by jinja templates + excluded_attributes: ["messaging.client_id"] + + stable_package_name: opentelemetry.semconv + +templates: + - pattern: semantic_attributes.j2 + filter: > + semconv_grouped_attributes({ + "exclude_root_namespace": $excluded_namespaces, + "exclude_stability": if $filter == "any" then [] else ["experimental"] end, + }) + | map({ + root_namespace: .root_namespace, + attributes: .attributes, + output: $output + "attributes/", + stable_package_name: $stable_package_name + ".attributes", + filter: $filter, + excluded_attributes: $excluded_attributes[] + }) + application_mode: each + - pattern: semantic_metrics.j2 + filter: > + semconv_grouped_metrics({ + "exclude_root_namespace": $excluded_namespaces, + "exclude_stability": if $filter == "any" then [] else ["experimental"] end, + }) + | map({ + root_namespace: .root_namespace, + metrics: .metrics, + output: $output + "metrics/", + stable_package_name: $stable_package_name + ".metrics", + filter: $filter + }) + application_mode: each +text_maps: + py_instrument_to_factory: + counter: counter + histogram: histogram + updowncounter: up_down_counter + gauge: observable_gauge + py_instrument_to_type: + counter: Counter + histogram: Histogram + updowncounter: UpDownCounter + gauge: ObservableGauge + diff --git a/scripts/semconv/templates/semantic_attributes.j2 b/scripts/semconv/templates/semantic_attributes.j2 deleted file mode 100644 index b660445b52f..00000000000 --- a/scripts/semconv/templates/semantic_attributes.j2 +++ /dev/null @@ -1,96 +0,0 @@ -{# -# 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. -#} - -{%- import 'common.j2' as common -%} - -{%- macro stable_class_ref(const_name, separator) -%} -{{stable_package}}.{{root_namespace}}_attributes{{separator}}{{const_name}} -{%- endmacro %} - -{%- macro attribute_name(attribute) -%} - {%- if attribute | is_template -%} - {{attribute.fqn | to_const_name}}_TEMPLATE - {%- else -%} - {{attribute.fqn | to_const_name}} - {%- endif -%} -{%- endmacro -%} - -{%- macro attribute_brief(attribute, prefix) -%} -{%- if not prefix %}""" -{%- endif %} - {%- if attribute | is_deprecated %} -{{ prefix }}Deprecated: {{ common.to_docstring(attribute.deprecated) }}. - {%- elif attribute | is_stable and filter == "any" %} -{{ prefix }}Deprecated in favor of stable :py:const:`{{stable_class_ref(attribute_name(attribute), '.')}}`. - {%- else %} -{{ prefix }}{{ common.to_docstring(attribute.brief) }}. - {%- if attribute.note %} -{{ prefix }}Note: {{ common.to_docstring(attribute.note | indent)}}. - {%- endif -%} - {%- endif %} -{%- if not prefix %} -"""{%- endif %} -{%- endmacro -%} - -{%- if root_namespace not in excluded_namespaces.split(' ') -%} -{%- set excluded_attributes_list = excluded_attributes.split(' ') -%} -{%- if filter != 'any' -%} -{%- set filtered_attributes = attributes_and_templates | select(filter) | list -%} -{%- else -%} -{%- set filtered_attributes = attributes_and_templates | list %} -{%- endif -%} -{%- if filtered_attributes | count > 0 -%} - -{{ common.file_header()}} - -{%- if filter != 'any' -%} -{%- set filtered_enum_attributes = enum_attributes | select(filter) | list %} -{%- else -%} -{%- set filtered_enum_attributes = enum_attributes | list %} -{%- endif -%} - -from typing import Final - -{{common.import_deprecated(filtered_enum_attributes)}} - -{% if filtered_enum_attributes | count > 0 %} - -from enum import Enum - -{% else %} - -{% endif %} - -{% for attribute in filtered_attributes -%} -{%- set prefix = "# " if attribute.fqn in excluded_attributes else "" -%} -{{prefix}}{{attribute_name(attribute)}}: Final = "{{attribute.fqn}}" -{{attribute_brief(attribute, prefix)}} - -{% endfor %} -{%- for attribute in filtered_enum_attributes | rejectattr("fqn", "in", excluded_attributes) -%} -{%- set class_name = attribute.fqn | to_camelcase(True) ~ "Values" -%} - {%- if attribute | is_deprecated %} -@deprecated(reason="The attribute {{attribute.fqn}} is deprecated - {{ common.to_docstring(attribute.deprecated) }}") # type: ignore - {%- elif attribute | is_stable and filter == "any" %} -@deprecated(reason="Deprecated in favor of stable :py:const:`{{stable_class_ref(class_name, '.')}}`.") # type: ignore - {%- endif %} -class {{class_name}}(Enum): - {%- for member in attribute.attr_type.members %} - {{ member.member_id | to_const_name }} = {{ attribute | print_member_value(member) }} - """{{ common.to_docstring(member.brief) }}.""" - {%- endfor %} -{%- endfor -%} -{%- endif -%} -{%- endif -%} diff --git a/scripts/semconv/templates/semantic_metrics.j2 b/scripts/semconv/templates/semantic_metrics.j2 deleted file mode 100644 index e436df2aa5b..00000000000 --- a/scripts/semconv/templates/semantic_metrics.j2 +++ /dev/null @@ -1,136 +0,0 @@ -{# -# 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. -#} - -{%- import 'common.j2' as common -%} - -{%- macro to_python_instrument_factory(instrument) -%} - {%- if instrument == "counter" -%} - counter - {%- elif instrument == "histogram" -%} - histogram - {%- elif instrument == "updowncounter" -%} - up_down_counter - {%- elif instrument == "gauge" -%} - observable_gauge - {%- endif -%} -{%- endmacro %} -{%- macro to_python_instrument_type(instrument) -%} - {%- if instrument == "counter" -%} - Counter - {%- elif instrument == "histogram" -%} - Histogram - {%- elif instrument == "updowncounter" -%} - UpDownCounter - {%- elif instrument == "gauge" -%} - ObservableGauge - {%- endif -%} -{%- endmacro %} - -{%- macro stable_class_ref(const_name, separator) -%} -{{stable_package}}.{{root_namespace}}_metrics{{separator}}{{const_name}} -{%- endmacro %} - -{%- macro metric_brief(metric, const_name) -%} -""" - {%- if metric | is_deprecated %} -Deprecated: {{ common.to_docstring(metric.deprecated)}}. - {%- elif metric | is_stable and filter == "any" %} -Deprecated in favor of stable :py:const:`{{stable_class_ref(const_name, '.')}}`. - {%- else -%} - {%- set brief = common.to_docstring(metric.brief) -%} - {%- if brief != "" %} -{{brief}} - {%- endif %} -Instrument: {{ metric.instrument }} -Unit: {{ metric.unit }} - {%- if metric.note %} -Note: {{ common.to_docstring(metric.note | indent) }}. - {%- endif -%} - {%- endif %} -""" -{%- endmacro -%} - -{%- macro import_instrument_classes(metrics) -%} - {% if filter == "any" %} -from opentelemetry.metrics import Meter - -{%- if metrics | selectattr("instrument", "equalto", "histogram") | list | count > 0 %} -from opentelemetry.metrics import Histogram - {%- endif %} - - {%- if metrics | selectattr("instrument", "equalto", "updowncounter") | list | count > 0 %} -from opentelemetry.metrics import UpDownCounter - {%- endif %} - - {%- if metrics | selectattr("instrument", "equalto", "counter") | list | count > 0 %} -from opentelemetry.metrics import Counter - {%- endif %} - - {%- if metrics | selectattr("instrument", "equalto", "gauge") | list | count > 0 %} -from typing import Callable, Generator, Iterable, Optional, Sequence, Union -from opentelemetry.metrics import CallbackOptions, ObservableGauge, Observation - -# pylint: disable=invalid-name -CallbackT = Union[ - Callable[[CallbackOptions], Iterable[Observation]], - Generator[Iterable[Observation], CallbackOptions, None], -] - {%- endif %} - {%- endif -%} -{%- endmacro-%} - -{%- if root_namespace not in excluded_namespaces -%} - {%- if filter != 'any' -%} -{%- set filtered_metrics = metrics | select(filter) | list -%} - {%- else -%} -{%- set filtered_metrics = metrics -%} - {%- endif -%} - - {%- if filtered_metrics | count > 0 -%} - -{{ common.file_header()}} - -from typing import Final -{{ import_instrument_classes(filtered_metrics) }} - - {%- for metric in filtered_metrics %} - -{% set const_name = metric.metric_name | to_const_name %} -{{const_name}}: Final = "{{metric.metric_name}}" -{{metric_brief(metric, metric.metric_name | to_const_name) }} - - {% if filter == "any" %} - {% set metric_name = metric.metric_name | replace(".", "_") %} - {%- if metric.instrument == "gauge" %} -def create_{{ metric_name }}(meter: Meter, callbacks: Optional[Sequence[CallbackT]]) -> {{to_python_instrument_type(metric.instrument)}}: - {%- else %} -def create_{{ metric_name }}(meter: Meter) -> {{to_python_instrument_type(metric.instrument)}}: - {%- endif %} - {%- set brief = common.to_docstring(metric.brief) -%} - {%- if brief != "" %} - """{{brief}}""" - {%- endif %} - return meter.create_{{to_python_instrument_factory(metric.instrument)}}( - name={{ const_name }}, - {%- if metric.instrument == "gauge" %} - callbacks=callbacks, - {%- endif %} - description="{{ metric.brief }}", - unit="{{ metric.unit }}", - ) - {%- endif -%} - {%- endfor -%} - {%- endif -%} -{%- endif -%} From 03d799562859375a8a93b09329c048fe42f73366 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 30 Jul 2024 09:10:40 -0700 Subject: [PATCH 2/3] review --- .../_incubating/attributes/dns_attributes.py | 2 +- .../attributes/messaging_attributes.py | 4 +-- .../_incubating/metrics/system_metrics.py | 4 +-- scripts/semconv/templates/registry/common.j2 | 2 +- .../templates/registry/semantic_attributes.j2 | 27 ++++++++++--------- 5 files changed, 19 insertions(+), 20 deletions(-) diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py index 95961b176f3..cfb00bcf307 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/dns_attributes.py @@ -17,5 +17,5 @@ DNS_QUESTION_NAME: Final = "dns.question.name" """ The name being queried. -Note: If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. +Note: If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \\t, \\r, and \\n respectively. """ 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 df8386bfa9c..9ac4205caa3 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 @@ -27,9 +27,7 @@ """ # MESSAGING_CLIENT_ID : Final = "messaging.client_id" -""" -Deprecated: Replaced by `messaging.client.id`. -""" +# Deprecated: Replaced by `messaging.client.id`. MESSAGING_DESTINATION_ANONYMOUS: Final = "messaging.destination.anonymous" """ 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 3854306461b..ba8d9402094 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 @@ -153,8 +153,8 @@ def create_system_disk_io(meter: Meter) -> Counter: - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) - Windows: The complement of - ["Disk\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) - performance counter: `uptime * (100 - "Disk\% Idle Time") / 100`. + ["Disk\\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + performance counter: `uptime * (100 - "Disk\\% Idle Time") / 100`. """ diff --git a/scripts/semconv/templates/registry/common.j2 b/scripts/semconv/templates/registry/common.j2 index ae58c211fd4..323e2bcdfa7 100644 --- a/scripts/semconv/templates/registry/common.j2 +++ b/scripts/semconv/templates/registry/common.j2 @@ -28,7 +28,7 @@ {%- endmacro -%} {%- macro comment_with_prefix(str, prefix) -%} -{{remove_trailing_dots(str | trim(' \n')) | comment_with_prefix(prefix)}} +{{remove_trailing_dots(str | trim(' \n')) | comment_with_prefix(prefix) | replace("\\", "\\\\")}} {%- endmacro %} {%- macro import_deprecated(semconv) -%} diff --git a/scripts/semconv/templates/registry/semantic_attributes.j2 b/scripts/semconv/templates/registry/semantic_attributes.j2 index 80fcdf7d783..fa7f80ca478 100644 --- a/scripts/semconv/templates/registry/semantic_attributes.j2 +++ b/scripts/semconv/templates/registry/semantic_attributes.j2 @@ -24,36 +24,37 @@ from typing import Final {{c.import_deprecated(enum_attributes)}} {%- macro attribute_name(attribute) -%} -{{c.to_const_name(attribute.name)}}{%- if "template" in attribute.type -%}_TEMPLATE{%- endif -%} +{{c.to_const_name(attribute.name)}}{%- if attribute.type is template_type -%}_TEMPLATE{%- endif -%} {%- endmacro -%} {%- macro stable_class_ref(const_name, separator) -%} {{ctx.stable_package_name}}.{{ctx.root_namespace}}_attributes{{separator}}{{const_name}} {%- endmacro %} -{%- macro write_docstring(name, brief, note, deprecated, stability, prefix) -%} +{%- macro write_docstring(name, brief, note, deprecated, stability, multiline) -%} +{%- if multiline %}""" +{% endif %} {%- if c.str_or_empty(deprecated)|length -%} -{{prefix}}Deprecated: {{c.comment_with_prefix(deprecated, prefix)}}. +{{prefix}}Deprecated: {{c.comment_with_prefix(deprecated, "")}}. {%- elif ctx.filter == "any" and stability == "stable" -%} {{prefix}}Deprecated in favor of stable :py:const:`{{stable_class_ref(name, '.')}}`. {%- elif c.str_or_empty(brief)|length -%} -{{prefix}}{{c.comment_with_prefix(brief, prefix)}}. +{{prefix}}{{c.comment_with_prefix(brief, "")}}. {%- if c.str_or_empty(note)|length %} -{{prefix}}Note: {{c.comment_with_prefix(note, prefix)}}. +{{prefix}}Note: {{c.comment_with_prefix(note, "")}}. {%- endif -%} {%- endif -%} +{%- if multiline %} +"""{%- endif %} {%- endmacro -%} {% for attribute in attributes %} {% set attr_name = attribute_name(attribute) %} -{%- set prefix = "# " if attribute.name in ctx.excluded_attributes else "" -%} -{%- set doc_string=write_docstring(attr_name, attribute.brief, attribute.note, attribute.deprecated, attribute.stability, "")-%} +{%- 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}}" -{%- if doc_string %} -""" -{{doc_string}} -""" -{%- endif %} +{{prefix}}{{doc_string}} {% endfor %} {% for attribute in enum_attributes %}{%- set class_name = attribute.name | pascal_case ~ "Values" -%} @@ -65,7 +66,7 @@ from typing import Final class {{class_name}}(Enum): {%- for member in attribute.type.members %} {% set member_name = c.to_const_name(member.id) -%} - {%- set doc_string=write_docstring(class_name + '.' + member_name, member.brief or member.id, "", member.deprecated, member.stability, "")-%} + {%- set doc_string=write_docstring(class_name + '.' + member_name, member.brief or member.id, "", member.deprecated, member.stability, false)-%} {{member_name}} = {{c.print_value(attribute.type | instantiated_type, member.value) }} {% if doc_string %}"""{{doc_string}}"""{% endif %} {%- endfor %} From 5603a50e2f9bc3e67f208cc819f2b009e7bd5c73 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 30 Jul 2024 14:27:27 -0700 Subject: [PATCH 3/3] Update scripts/semconv/generate.sh MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Emídio Neto <9735060+emdneto@users.noreply.github.com> --- scripts/semconv/generate.sh | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/scripts/semconv/generate.sh b/scripts/semconv/generate.sh index 9b52e9be8bf..26a582ac09e 100755 --- a/scripts/semconv/generate.sh +++ b/scripts/semconv/generate.sh @@ -1,6 +1,5 @@ #!/bin/bash -set -e -set -x +set -ex SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" ROOT_DIR="${SCRIPT_DIR}/../.."