diff --git a/CHANGELOG.md b/CHANGELOG.md index 041d7aaf594..3a311bbdaeb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased](https://github.com/open-telemetry/opentelemetry-python/compare/v1.3.0-0.22b0...HEAD) +- `opentelemetry-semantic-conventions` Generate semconv constants update for OTel Spec 1.5.0 + ([#1946](https://github.com/open-telemetry/opentelemetry-python/pull/1946)) ### Added - Dropped attributes/events/links count available exposed on ReadableSpans. diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/resource/__init__.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/resource/__init__.py index b1e76a77b6f..c8e27683ee0 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/resource/__init__.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/resource/__init__.py @@ -37,9 +37,9 @@ class ResourceAttributes: Note: Availability zones are called "zones" on Google Cloud. """ - CLOUD_INFRASTRUCTURE_SERVICE = "cloud.infrastructure_service" + CLOUD_PLATFORM = "cloud.platform" """ - The cloud infrastructure resource in use. + The cloud platform in use. Note: The prefix of the service SHOULD match the one specified in `cloud.provider`. """ @@ -68,6 +68,11 @@ class ResourceAttributes: The task definition family this task definition is a member of. """ + AWS_ECS_TASK_REVISION = "aws.ecs.task.revision" + """ + The revision for this task definition. + """ + AWS_EKS_CLUSTER_ARN = "aws.eks.cluster.arn" """ The ARN of an EKS cluster. @@ -126,25 +131,67 @@ class ResourceAttributes: Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) (aka deployment tier). """ + DEVICE_ID = "device.id" + """ + A unique identifier representing the device. + Note: The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. + """ + + DEVICE_MODEL_IDENTIFIER = "device.model.identifier" + """ + The model identifier for the device. + Note: It's recommended this value represents a machine readable version of the model identifier rather than the market or consumer-friendly name of the device. + """ + + DEVICE_MODEL_NAME = "device.model.name" + """ + The marketing name for the device model. + Note: It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. + """ + FAAS_NAME = "faas.name" """ - The name of the function being executed. + 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`](../../trace/semantic_conventions/span-general.md#source-code-attributes) span attributes). """ FAAS_ID = "faas.id" """ - The unique ID of the function being executed. - Note: For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function) field. + The unique ID of the single function that this runtime instance executes. + Note: Depending on the cloud provider, use: + +* **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/en-us/rest/api/resources/resources/get-by-id). + +On some providers, it may not be possible to determine the full ID at startup, +which is why this field cannot be made required. For example, on AWS the account ID +part of the ARN is not available without calling another AWS API +which may be deemed too slow for a short-running lambda function. +As an alternative, consider setting `faas.id` as a span attribute instead. """ FAAS_VERSION = "faas.version" """ - The version string of the function being executed as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). + 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:** 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. """ FAAS_INSTANCE = "faas.instance" """ - The execution environment ID as a string. + The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. + Note: * **AWS Lambda:** Use the (full) log stream name. """ FAAS_MAX_MEMORY = "faas.max_memory" @@ -293,6 +340,16 @@ class ResourceAttributes: Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. """ + OS_NAME = "os.name" + """ + Human readable operating system name. + """ + + OS_VERSION = "os.version" + """ + The version string of the operating system as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). + """ + PROCESS_PID = "process.pid" """ Process identifier (PID). @@ -386,6 +443,21 @@ class ResourceAttributes: The version string of the auto instrumentation agent, if used. """ + WEBENGINE_NAME = "webengine.name" + """ + The name of the web engine. + """ + + WEBENGINE_VERSION = "webengine.version" + """ + The version of the web engine. + """ + + WEBENGINE_DESCRIPTION = "webengine.description" + """ + Additional description of the web engine (e.g. detailed version and edition information). + """ + class CloudProviderValues(Enum): AWS = "aws" @@ -398,7 +470,7 @@ class CloudProviderValues(Enum): """Google Cloud Platform.""" -class CloudInfrastructureServiceValues(Enum): +class CloudPlatformValues(Enum): AWS_EC2 = "aws_ec2" """AWS Elastic Compute Cloud.""" @@ -411,13 +483,13 @@ class CloudInfrastructureServiceValues(Enum): AWS_LAMBDA = "aws_lambda" """AWS Lambda.""" - AWS_ELASTICBEANSTALK = "aws_elastic_beanstalk" + AWS_ELASTIC_BEANSTALK = "aws_elastic_beanstalk" """AWS Elastic Beanstalk.""" AZURE_VM = "azure_vm" """Azure Virtual Machines.""" - AZURE_CONTAINERINSTANCES = "azure_container_instances" + AZURE_CONTAINER_INSTANCES = "azure_container_instances" """Azure Container Instances.""" AZURE_AKS = "azure_aks" @@ -426,22 +498,22 @@ class CloudInfrastructureServiceValues(Enum): AZURE_FUNCTIONS = "azure_functions" """Azure Functions.""" - AZURE_APPSERVICE = "azure_app_service" + AZURE_APP_SERVICE = "azure_app_service" """Azure App Service.""" - GCP_COMPUTEENGINE = "gcp_compute_engine" + GCP_COMPUTE_ENGINE = "gcp_compute_engine" """Google Cloud Compute Engine (GCE).""" - GCP_CLOUDRUN = "gcp_cloud_run" + GCP_CLOUD_RUN = "gcp_cloud_run" """Google Cloud Run.""" - GCP_KUBERNETESENGINE = "gcp_kubernetes_engine" + GCP_KUBERNETES_ENGINE = "gcp_kubernetes_engine" """Google Cloud Kubernetes Engine (GKE).""" - GCP_CLOUDFUNCTIONS = "gcp_cloud_functions" + GCP_CLOUD_FUNCTIONS = "gcp_cloud_functions" """Google Cloud Functions (GCF).""" - GCP_APPENGINE = "gcp_app_engine" + GCP_APP_ENGINE = "gcp_app_engine" """Google Cloud App Engine (GAE).""" @@ -477,37 +549,37 @@ class HostArchValues(Enum): class OsTypeValues(Enum): - WINDOWS = "WINDOWS" + WINDOWS = "windows" """Microsoft Windows.""" - LINUX = "LINUX" + LINUX = "linux" """Linux.""" - DARWIN = "DARWIN" + DARWIN = "darwin" """Apple Darwin.""" - FREEBSD = "FREEBSD" + FREEBSD = "freebsd" """FreeBSD.""" - NETBSD = "NETBSD" + NETBSD = "netbsd" """NetBSD.""" - OPENBSD = "OPENBSD" + OPENBSD = "openbsd" """OpenBSD.""" - DRAGONFLYBSD = "DRAGONFLYBSD" + DRAGONFLYBSD = "dragonflybsd" """DragonFly BSD.""" - HPUX = "HPUX" + HPUX = "hpux" """HP-UX (Hewlett Packard Unix).""" - AIX = "AIX" + AIX = "aix" """AIX (Advanced Interactive eXecutive).""" - SOLARIS = "SOLARIS" + SOLARIS = "solaris" """Oracle Solaris.""" - ZOS = "ZOS" + Z_OS = "z_os" """IBM z/OS.""" diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/trace/__init__.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/trace/__init__.py index 02b8768f166..36184ca9557 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/trace/__init__.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/trace/__init__.py @@ -16,6 +16,12 @@ class SpanAttributes: + AWS_LAMBDA_INVOKED_ARN = "aws.lambda.invoked_arn" + """ + The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). + Note: This may be different from `faas.id` if an alias is involved. + """ + DB_SYSTEM = "db.system" """ An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. @@ -450,11 +456,155 @@ class SpanAttributes: The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. """ + RPC_SYSTEM = "rpc.system" + """ + The value `aws-api`. + """ + + RPC_SERVICE = "rpc.service" + """ + The name of the service to which a request is made, as returned by the AWS SDK. + Note: This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + """ + + RPC_METHOD = "rpc.method" + """ + The name of the operation corresponding to the request, as returned by the AWS SDK. + Note: This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + """ + + AWS_DYNAMODB_TABLE_NAMES = "aws.dynamodb.table_names" + """ + The keys in the `RequestItems` object field. + """ + + AWS_DYNAMODB_CONSUMED_CAPACITY = "aws.dynamodb.consumed_capacity" + """ + The JSON-serialized value of each item in the `ConsumedCapacity` response field. + """ + + AWS_DYNAMODB_ITEM_COLLECTION_METRICS = ( + "aws.dynamodb.item_collection_metrics" + ) + """ + The JSON-serialized value of the `ItemCollectionMetrics` response field. + """ + + AWS_DYNAMODB_PROVISIONED_READ_CAPACITY = ( + "aws.dynamodb.provisioned_read_capacity" + ) + """ + The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. + """ + + AWS_DYNAMODB_PROVISIONED_WRITE_CAPACITY = ( + "aws.dynamodb.provisioned_write_capacity" + ) + """ + The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. + """ + + AWS_DYNAMODB_CONSISTENT_READ = "aws.dynamodb.consistent_read" + """ + The value of the `ConsistentRead` request parameter. + """ + + AWS_DYNAMODB_PROJECTION = "aws.dynamodb.projection" + """ + The value of the `ProjectionExpression` request parameter. + """ + + AWS_DYNAMODB_LIMIT = "aws.dynamodb.limit" + """ + The value of the `Limit` request parameter. + """ + + AWS_DYNAMODB_ATTRIBUTES_TO_GET = "aws.dynamodb.attributes_to_get" + """ + The value of the `AttributesToGet` request parameter. + """ + + AWS_DYNAMODB_INDEX_NAME = "aws.dynamodb.index_name" + """ + The value of the `IndexName` request parameter. + """ + + AWS_DYNAMODB_SELECT = "aws.dynamodb.select" + """ + The value of the `Select` request parameter. + """ + + AWS_DYNAMODB_GLOBAL_SECONDARY_INDEXES = ( + "aws.dynamodb.global_secondary_indexes" + ) + """ + The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field. + """ + + AWS_DYNAMODB_LOCAL_SECONDARY_INDEXES = ( + "aws.dynamodb.local_secondary_indexes" + ) + """ + The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. + """ + + AWS_DYNAMODB_EXCLUSIVE_START_TABLE = "aws.dynamodb.exclusive_start_table" + """ + The value of the `ExclusiveStartTableName` request parameter. + """ + + AWS_DYNAMODB_TABLE_COUNT = "aws.dynamodb.table_count" + """ + The the number of items in the `TableNames` response parameter. + """ + + AWS_DYNAMODB_SCAN_FORWARD = "aws.dynamodb.scan_forward" + """ + The value of the `ScanIndexForward` request parameter. + """ + + AWS_DYNAMODB_SEGMENT = "aws.dynamodb.segment" + """ + The value of the `Segment` request parameter. + """ + + AWS_DYNAMODB_TOTAL_SEGMENTS = "aws.dynamodb.total_segments" + """ + The value of the `TotalSegments` request parameter. + """ + + AWS_DYNAMODB_COUNT = "aws.dynamodb.count" + """ + The value of the `Count` response parameter. + """ + + AWS_DYNAMODB_SCANNED_COUNT = "aws.dynamodb.scanned_count" + """ + The value of the `ScannedCount` response parameter. + """ + + AWS_DYNAMODB_ATTRIBUTE_DEFINITIONS = "aws.dynamodb.attribute_definitions" + """ + The JSON-serialized value of each item in the `AttributeDefinitions` request field. + """ + + AWS_DYNAMODB_GLOBAL_SECONDARY_INDEX_UPDATES = ( + "aws.dynamodb.global_secondary_index_updates" + ) + """ + The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. + """ + MESSAGING_OPERATION = "messaging.operation" """ A string identifying the kind of message consumption as defined in the [Operation names](#operation-names) section above. If the operation is "send", this attribute MUST NOT be set, since the operation can be inferred from the span kind in that case. """ + MESSAGING_RABBITMQ_ROUTING_KEY = "messaging.rabbitmq.routing_key" + """ + RabbitMQ message routing key. + """ + MESSAGING_KAFKA_MESSAGE_KEY = "messaging.kafka.message_key" """ Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message_id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. @@ -481,24 +631,29 @@ class SpanAttributes: A boolean that is true if the message is a tombstone. """ - RPC_SYSTEM = "rpc.system" + RPC_GRPC_STATUS_CODE = "rpc.grpc.status_code" """ - A string identifying the remoting system. + The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. """ - RPC_SERVICE = "rpc.service" + RPC_JSONRPC_VERSION = "rpc.jsonrpc.version" """ - The full name of the service being called, including its package name, if applicable. + Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. """ - RPC_METHOD = "rpc.method" + RPC_JSONRPC_REQUEST_ID = "rpc.jsonrpc.request_id" """ - The name of the method being called, must be equal to the $method part in the span name. + `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. """ - RPC_GRPC_STATUS_CODE = "rpc.grpc.status_code" + RPC_JSONRPC_ERROR_CODE = "rpc.jsonrpc.error_code" """ - The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + `error.code` property of response if it is an error response. + """ + + RPC_JSONRPC_ERROR_MESSAGE = "rpc.jsonrpc.error_message" + """ + `error.message` property of response if it is an error response. """ @@ -638,18 +793,24 @@ class DbSystemValues(Enum): ELASTICSEARCH = "elasticsearch" """Elasticsearch.""" + MEMCACHED = "memcached" + """Memcached.""" + + COCKROACHDB = "cockroachdb" + """CockroachDB.""" + class NetTransportValues(Enum): - IP_TCP = "IP.TCP" - """IP.TCP.""" + IP_TCP = "ip_tcp" + """ip_tcp.""" - IP_UDP = "IP.UDP" - """IP.UDP.""" + IP_UDP = "ip_udp" + """ip_udp.""" - IP = "IP" + IP = "ip" """Another IP-based protocol.""" - UNIX = "Unix" + UNIX = "unix" """Unix Domain socket. See below.""" PIPE = "pipe" @@ -663,38 +824,38 @@ class NetTransportValues(Enum): class DbCassandraConsistencyLevelValues(Enum): - ALL = "ALL" - """ALL.""" + ALL = "all" + """all.""" - EACH_QUORUM = "EACH_QUORUM" - """EACH_QUORUM.""" + EACH_QUORUM = "each_quorum" + """each_quorum.""" - QUORUM = "QUORUM" - """QUORUM.""" + QUORUM = "quorum" + """quorum.""" - LOCAL_QUORUM = "LOCAL_QUORUM" - """LOCAL_QUORUM.""" + LOCAL_QUORUM = "local_quorum" + """local_quorum.""" - ONE = "ONE" - """ONE.""" + ONE = "one" + """one.""" - TWO = "TWO" - """TWO.""" + TWO = "two" + """two.""" - THREE = "THREE" - """THREE.""" + THREE = "three" + """three.""" - LOCAL_ONE = "LOCAL_ONE" - """LOCAL_ONE.""" + LOCAL_ONE = "local_one" + """local_one.""" - ANY = "ANY" - """ANY.""" + ANY = "any" + """any.""" - SERIAL = "SERIAL" - """SERIAL.""" + SERIAL = "serial" + """serial.""" - LOCAL_SERIAL = "LOCAL_SERIAL" - """LOCAL_SERIAL.""" + LOCAL_SERIAL = "local_serial" + """local_serial.""" class FaasTriggerValues(Enum): @@ -755,7 +916,7 @@ class FaasInvokedProviderValues(Enum): """Amazon Web Services.""" AZURE = "azure" - """Amazon Web Services.""" + """Microsoft Azure.""" GCP = "gcp" """Google Cloud Platform.""" diff --git a/scripts/semconv/generate.sh b/scripts/semconv/generate.sh old mode 100644 new mode 100755 index 62c28ede5c9..ccf75a63649 --- a/scripts/semconv/generate.sh +++ b/scripts/semconv/generate.sh @@ -4,7 +4,8 @@ SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" ROOT_DIR="${SCRIPT_DIR}/../../" # freeze the spec version to make SemanticAttributes generation reproducible -SPEC_VERSION=v1.1.0 +SPEC_VERSION=v1.5.0 +OTEL_SEMCONV_GEN_IMG_VERSION=0.4.1 cd ${SCRIPT_DIR} @@ -22,7 +23,7 @@ docker run --rm \ -v ${SCRIPT_DIR}/opentelemetry-specification/semantic_conventions/trace:/source \ -v ${SCRIPT_DIR}/templates:/templates \ -v ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/trace/:/output \ - otel/semconvgen:0.2.1 \ + otel/semconvgen:$OTEL_SEMCONV_GEN_IMG_VERSION \ -f /source code \ --template /templates/semantic_attributes.j2 \ --output /output/__init__.py \ @@ -31,8 +32,8 @@ docker run --rm \ docker run --rm \ -v ${SCRIPT_DIR}/opentelemetry-specification/semantic_conventions/resource:/source \ -v ${SCRIPT_DIR}/templates:/templates \ - -v ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/resources/:/output \ - otel/semconvgen:0.2.1 \ + -v ${ROOT_DIR}/opentelemetry-semantic-conventions/src/opentelemetry/semconv/resource/:/output \ + otel/semconvgen:$OTEL_SEMCONV_GEN_IMG_VERSION \ -f /source code \ --template /templates/semantic_attributes.j2 \ --output /output/__init__.py \