From 810aa2f95ac6d698782789a13e3d19ae469ec283 Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Wed, 24 Jan 2024 08:47:17 +1100 Subject: [PATCH] generate semconv 1.24.0 (#1219) * generate semconv 1.24.0 generate latest semconv version, and add back Trace and Resource attribute values which seem to have been dropped in a previous change. * document source repo release urls * remove redundant semconv deprecations two trace attributes were deleted then added back to upstream semconv, so remove our ones. --- script/semantic-conventions/semconv.sh | 38 +- .../templates/trace_deprecations.php.partial | 25 +- src/SemConv/ResourceAttributeValues.php | 349 ++++ src/SemConv/ResourceAttributes.php | 20 +- src/SemConv/TraceAttributeValues.php | 1466 +++++++++++++++++ src/SemConv/TraceAttributes.php | 403 ++++- 6 files changed, 2228 insertions(+), 73 deletions(-) create mode 100644 src/SemConv/ResourceAttributeValues.php create mode 100644 src/SemConv/TraceAttributeValues.php diff --git a/script/semantic-conventions/semconv.sh b/script/semantic-conventions/semconv.sh index b51029df2..824c008cd 100755 --- a/script/semantic-conventions/semconv.sh +++ b/script/semantic-conventions/semconv.sh @@ -5,6 +5,10 @@ # Supported semantic conventions: # - Trace # - Resource +# +# Source repositories: +# - https://github.com/open-telemetry/semantic-conventions/releases +# - https://github.com/open-telemetry/build-tools/releases SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" ROOT_DIR="${SCRIPT_DIR}/../../" @@ -12,7 +16,7 @@ SPEC_DIR="${ROOT_DIR}/var/semantic-conventions" CODE_DIR="${ROOT_DIR}/src/SemConv" # freeze the spec & generator tools versions to make SemanticAttributes generation reproducible -SEMCONV_VERSION=${SEMCONV_VERSION:=1.23.1} +SEMCONV_VERSION=${SEMCONV_VERSION:=1.24.0} SPEC_VERSION=v$SEMCONV_VERSION SCHEMA_URL=https://opentelemetry.io/schemas/$SEMCONV_VERSION GENERATOR_VERSION=0.23.0 @@ -65,4 +69,36 @@ docker run --rm \ -Dclass="Resource" \ -DschemaUrl=$SCHEMA_URL +# Trace attribute values +docker run --rm \ + -v "${SPEC_DIR}/model:/source" \ + -v "${SCRIPT_DIR}/templates:/templates" \ + -v "${CODE_DIR}:/output" \ + -u "${UID}" \ + otel/semconvgen:$GENERATOR_VERSION \ + --only span,event,attribute_group,scope \ + --yaml-root /source \ + code \ + --template /templates/AttributeValues.php.j2 \ + --output "/output/TraceAttributeValues.php" \ + -Dnamespace="OpenTelemetry\\SemConv" \ + -Dclass="Trace" \ + -DschemaUrl=$SCHEMA_URL + +# Resource attribute values +docker run --rm \ + -v "${SPEC_DIR}/model:/source" \ + -v "${SCRIPT_DIR}/templates:/templates" \ + -v "${CODE_DIR}:/output" \ + -u "${UID}" \ + otel/semconvgen:$GENERATOR_VERSION \ + --only resource \ + --yaml-root /source \ + code \ + --template /templates/AttributeValues.php.j2 \ + --output "/output/ResourceAttributeValues.php" \ + -Dnamespace="OpenTelemetry\\SemConv" \ + -Dclass="Resource" \ + -DschemaUrl=$SCHEMA_URL + rm -rf "${SPEC_DIR}" || true diff --git a/script/semantic-conventions/templates/trace_deprecations.php.partial b/script/semantic-conventions/templates/trace_deprecations.php.partial index d891b93bf..51e28cb4c 100644 --- a/script/semantic-conventions/templates/trace_deprecations.php.partial +++ b/script/semantic-conventions/templates/trace_deprecations.php.partial @@ -28,11 +28,6 @@ */ public const HTTP_SERVER_NAME = 'http.server_name'; - /** - * @deprecated - */ - public const HTTP_USER_AGENT = 'http.user_agent'; - /** * @deprecated */ @@ -93,11 +88,6 @@ */ public const HTTP_CLIENT_IP = 'http.client_ip'; - /** - * @deprecated - */ - public const HTTP_FLAVOR = 'http.flavor'; - /** * @deprecated */ @@ -207,3 +197,18 @@ * @deprecated */ public const THREAD_DAEMON = 'thread.daemon'; + + /** + * @deprecated + */ + public const EVENT_DOMAIN = 'event.domain'; + + /** + * @deprecated + */ + public const SYSTEM_DISK_DIRECTION = 'system.disk.direction'; + + /** + * @deprecated + */ + public const SYSTEM_NETWORK_DIRECTION = 'system.network.direction'; diff --git a/src/SemConv/ResourceAttributeValues.php b/src/SemConv/ResourceAttributeValues.php new file mode 100644 index 000000000..8d36316c0 --- /dev/null +++ b/src/SemConv/ResourceAttributeValues.php @@ -0,0 +1,349 @@ + + *
  • `service.name=frontend`, `deployment.environment=production`
    • + *
  • `service.name=frontend`, `deployment.environment=staging`.
    • + * + * * @example staging * @example production */ @@ -322,7 +330,7 @@ interface ResourceAttributes /** * The model identifier for the device. * - * 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. + * 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. * * @example iPhone3,4 * @example SM-G920F @@ -332,7 +340,7 @@ interface ResourceAttributes /** * The marketing name for the device model. * - * It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. + * It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. * * @example iPhone 6s Plus * @example Samsung Galaxy S6 @@ -465,9 +473,10 @@ interface ResourceAttributes public const HOST_CPU_CACHE_L2_SIZE = 'host.cpu.cache.l2.size'; /** - * Numeric value specifying the family or generation of the CPU. + * Family or generation of the CPU. * * @example 6 + * @example PA-RISC 1.1e */ public const HOST_CPU_FAMILY = 'host.cpu.family'; @@ -475,6 +484,7 @@ interface ResourceAttributes * Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. * * @example 6 + * @example 9000/778/B180L */ public const HOST_CPU_MODEL_ID = 'host.cpu.model.id'; @@ -852,7 +862,7 @@ interface ResourceAttributes public const PROCESS_OWNER = 'process.owner'; /** - * Parent Process identifier (PID). + * Parent Process identifier (PPID). * * @example 111 */ diff --git a/src/SemConv/TraceAttributeValues.php b/src/SemConv/TraceAttributeValues.php new file mode 100644 index 000000000..45334eb19 --- /dev/null +++ b/src/SemConv/TraceAttributeValues.php @@ -0,0 +1,1466 @@ + - *
  • 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.
    • - * + * If the request fails with an error before response status code was sent or received, + * `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) + * or a component-specific low cardinality error identifier.If response status code was sent or received and status indicates an error according to HTTP span status definition, + * `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier.The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + * Instrumentations SHOULD document the list of errors they report.The cardinality of `error.type` within one instrumentation library SHOULD be low, but + * 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 request has completed successfully, instrumentations SHOULD NOT set `error.type`. * * @example timeout * @example java.net.UnknownHostException @@ -669,17 +727,12 @@ interface TraceAttributes public const ERROR_TYPE = 'error.type'; /** - * The domain identifies the business context for the events. + * Identifies the class / type of event. * - * Events across different domains may have same `event.name`, yet be unrelated events. - */ - public const EVENT_DOMAIN = 'event.domain'; - - /** - * The name identifies the event. + * Event names are subject to the same rules as attribute names. Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. * - * @example click - * @example exception + * @example browser.mouse.click + * @example device.app.lifecycle */ public const EVENT_NAME = 'event.name'; @@ -694,7 +747,7 @@ interface TraceAttributes * 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 above.It follows that an exception may still escape the scope of the span + * as done in the example for recording span exceptions.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. @@ -863,6 +916,11 @@ interface TraceAttributes */ public const GRAPHQL_OPERATION_TYPE = 'graphql.operation.type'; + /** + * Deprecated, use `network.protocol.name` instead. + */ + public const HTTP_FLAVOR = 'http.flavor'; + /** * Deprecated, use `http.request.method` instead. * @@ -990,6 +1048,15 @@ interface TraceAttributes */ public const HTTP_URL = 'http.url'; + /** + * Deprecated, use `user_agent.original` instead. + * + * @deprecated Deprecated, use `user_agent.original` instead.. + * @example CERN-LineMode/2.15 libwww/2.17b3 + * @example Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1 + */ + public const HTTP_USER_AGENT = 'http.user_agent'; + /** * This attribute represents the state the application has transitioned into at the occurrence of the event. * @@ -1155,6 +1222,13 @@ interface TraceAttributes */ public const MESSAGING_DESTINATION_PUBLISH_NAME = 'messaging.destination_publish.name'; + /** + * The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. + * + * @example ordering_key + */ + public const MESSAGING_GCP_PUBSUB_MESSAGE_ORDERING_KEY = 'messaging.gcp_pubsub.message.ordering_key'; + /** * Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. * @@ -1299,13 +1373,7 @@ interface TraceAttributes public const MESSAGING_ROCKETMQ_NAMESPACE = 'messaging.rocketmq.namespace'; /** - * A string identifying the messaging system. - * - * @example kafka - * @example rabbitmq - * @example rocketmq - * @example activemq - * @example AmazonSQS + * An identifier for the messaging system being used. See below for a list of well-known identifiers. */ public const MESSAGING_SYSTEM = 'messaging.system'; @@ -1451,6 +1519,13 @@ interface TraceAttributes */ public const NETWORK_CONNECTION_TYPE = 'network.connection.type'; + /** + * The network IO operation direction. + * + * @example transmit + */ + public const NETWORK_IO_DIRECTION = 'network.io.direction'; + /** * Local address of the network connection - IP address or Unix domain socket name. * @@ -1511,7 +1586,7 @@ interface TraceAttributes * different processes could be listening on TCP port 12345 and UDP port 12345. * * @example tcp - * @example udp + * @example unix */ public const NETWORK_TRANSPORT = 'network.transport'; @@ -1624,9 +1699,9 @@ interface TraceAttributes public const RPC_SYSTEM = 'rpc.system'; /** - * Host identifier of the "URI origin" HTTP request is sent to. + * Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. * - * If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + * When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. * * @example example.com * @example 10.1.2.80 @@ -1635,7 +1710,7 @@ interface TraceAttributes public const SERVER_ADDRESS = 'server.address'; /** - * Port identifier of the "URI origin" HTTP request is sent to. + * Server port number. * * When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. * @@ -1659,6 +1734,22 @@ interface TraceAttributes */ public const SESSION_PREVIOUS_ID = 'session.previous_id'; + /** + * SignalR HTTP connection closure status. + * + * @example app_shutdown + * @example timeout + */ + public const SIGNALR_CONNECTION_STATUS = 'signalr.connection.status'; + + /** + * SignalR transport type. + * + * @example web_sockets + * @example long_polling + */ + public const SIGNALR_TRANSPORT = 'signalr.transport'; + /** * Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. * @@ -1707,13 +1798,6 @@ interface TraceAttributes */ public const SYSTEM_DEVICE = 'system.device'; - /** - * The disk operation direction. - * - * @example read - */ - public const SYSTEM_DISK_DIRECTION = 'system.disk.direction'; - /** * The filesystem mode. * @@ -1750,13 +1834,6 @@ interface TraceAttributes */ public const SYSTEM_MEMORY_STATE = 'system.memory.state'; - /** - * . - * - * @example transmit - */ - public const SYSTEM_NETWORK_DIRECTION = 'system.network.direction'; - /** * A stateless protocol MUST NOT set this attribute. * @@ -1806,6 +1883,213 @@ interface TraceAttributes */ public const THREAD_NAME = 'thread.name'; + /** + * String indicating the cipher used during the current connection. + * + * The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the registered TLS Cipher Suits. + * + * @example TLS_RSA_WITH_3DES_EDE_CBC_SHA + * @example TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 + */ + public const TLS_CIPHER = 'tls.cipher'; + + /** + * PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. + * + * @example MII... + */ + public const TLS_CLIENT_CERTIFICATE = 'tls.client.certificate'; + + /** + * Array of PEM-encoded certificates that make up the certificate chain offered by the client. This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain. + * + * @example MII... + * @example MI... + */ + public const TLS_CLIENT_CERTIFICATE_CHAIN = 'tls.client.certificate_chain'; + + /** + * Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. + * + * @example 0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC + */ + public const TLS_CLIENT_HASH_MD5 = 'tls.client.hash.md5'; + + /** + * Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. + * + * @example 9E393D93138888D288266C2D915214D1D1CCEB2A + */ + public const TLS_CLIENT_HASH_SHA1 = 'tls.client.hash.sha1'; + + /** + * Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. + * + * @example 0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0 + */ + public const TLS_CLIENT_HASH_SHA256 = 'tls.client.hash.sha256'; + + /** + * Distinguished name of subject of the issuer of the x.509 certificate presented by the client. + * + * @example CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com + */ + public const TLS_CLIENT_ISSUER = 'tls.client.issuer'; + + /** + * A hash that identifies clients based on how they perform an SSL/TLS handshake. + * + * @example d4e5b18d6b55c71272893221c96ba240 + */ + public const TLS_CLIENT_JA3 = 'tls.client.ja3'; + + /** + * Date/Time indicating when client certificate is no longer considered valid. + * + * @example 2021-01-01T00:00:00.000Z + */ + public const TLS_CLIENT_NOT_AFTER = 'tls.client.not_after'; + + /** + * Date/Time indicating when client certificate is first considered valid. + * + * @example 1970-01-01T00:00:00.000Z + */ + public const TLS_CLIENT_NOT_BEFORE = 'tls.client.not_before'; + + /** + * Also called an SNI, this tells the server which hostname to which the client is attempting to connect to. + * + * @example opentelemetry.io + */ + public const TLS_CLIENT_SERVER_NAME = 'tls.client.server_name'; + + /** + * Distinguished name of subject of the x.509 certificate presented by the client. + * + * @example CN=myclient, OU=Documentation Team, DC=example, DC=com + */ + public const TLS_CLIENT_SUBJECT = 'tls.client.subject'; + + /** + * Array of ciphers offered by the client during the client hello. + * + * @example "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..." + */ + public const TLS_CLIENT_SUPPORTED_CIPHERS = 'tls.client.supported_ciphers'; + + /** + * String indicating the curve used for the given cipher, when applicable. + * + * @example secp256r1 + */ + public const TLS_CURVE = 'tls.curve'; + + /** + * Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel. + * + * @example True + */ + public const TLS_ESTABLISHED = 'tls.established'; + + /** + * String indicating the protocol being tunneled. Per the values in the IANA registry, this string should be lower case. + * + * @example http/1.1 + */ + public const TLS_NEXT_PROTOCOL = 'tls.next_protocol'; + + /** + * Normalized lowercase protocol name parsed from original string of the negotiated SSL/TLS protocol version. + */ + public const TLS_PROTOCOL_NAME = 'tls.protocol.name'; + + /** + * Numeric part of the version parsed from the original string of the negotiated SSL/TLS protocol version. + * + * @example 1.2 + * @example 3 + */ + public const TLS_PROTOCOL_VERSION = 'tls.protocol.version'; + + /** + * Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation. + * + * @example True + */ + public const TLS_RESUMED = 'tls.resumed'; + + /** + * PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. + * + * @example MII... + */ + public const TLS_SERVER_CERTIFICATE = 'tls.server.certificate'; + + /** + * Array of PEM-encoded certificates that make up the certificate chain offered by the server. This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain. + * + * @example MII... + * @example MI... + */ + public const TLS_SERVER_CERTIFICATE_CHAIN = 'tls.server.certificate_chain'; + + /** + * Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. + * + * @example 0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC + */ + public const TLS_SERVER_HASH_MD5 = 'tls.server.hash.md5'; + + /** + * Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. + * + * @example 9E393D93138888D288266C2D915214D1D1CCEB2A + */ + public const TLS_SERVER_HASH_SHA1 = 'tls.server.hash.sha1'; + + /** + * Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. + * + * @example 0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0 + */ + public const TLS_SERVER_HASH_SHA256 = 'tls.server.hash.sha256'; + + /** + * Distinguished name of subject of the issuer of the x.509 certificate presented by the client. + * + * @example CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com + */ + public const TLS_SERVER_ISSUER = 'tls.server.issuer'; + + /** + * A hash that identifies servers based on how they perform an SSL/TLS handshake. + * + * @example d4e5b18d6b55c71272893221c96ba240 + */ + public const TLS_SERVER_JA3S = 'tls.server.ja3s'; + + /** + * Date/Time indicating when server certificate is no longer considered valid. + * + * @example 2021-01-01T00:00:00.000Z + */ + public const TLS_SERVER_NOT_AFTER = 'tls.server.not_after'; + + /** + * Date/Time indicating when server certificate is first considered valid. + * + * @example 1970-01-01T00:00:00.000Z + */ + public const TLS_SERVER_NOT_BEFORE = 'tls.server.not_before'; + + /** + * Distinguished name of subject of the x.509 certificate presented by the server. + * + * @example CN=myserver, OU=Documentation Team, DC=example, DC=com + */ + public const TLS_SERVER_SUBJECT = 'tls.server.subject'; + /** * The URI fragment component. * @@ -1887,11 +2171,6 @@ interface TraceAttributes */ public const HTTP_SERVER_NAME = 'http.server_name'; - /** - * @deprecated - */ - public const HTTP_USER_AGENT = 'http.user_agent'; - /** * @deprecated */ @@ -1952,11 +2231,6 @@ interface TraceAttributes */ public const HTTP_CLIENT_IP = 'http.client_ip'; - /** - * @deprecated - */ - public const HTTP_FLAVOR = 'http.flavor'; - /** * @deprecated */ @@ -2066,4 +2340,19 @@ interface TraceAttributes * @deprecated */ public const THREAD_DAEMON = 'thread.daemon'; + + /** + * @deprecated + */ + public const EVENT_DOMAIN = 'event.domain'; + + /** + * @deprecated + */ + public const SYSTEM_DISK_DIRECTION = 'system.disk.direction'; + + /** + * @deprecated + */ + public const SYSTEM_NETWORK_DIRECTION = 'system.network.direction'; }