diff --git a/CHANGELOG.md b/CHANGELOG.md index 1932c54ab8..e0d88827a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Increment the: * [EXPORTER] OTLP http exporter allow concurrency session ([#1209](https://github.com/open-telemetry/opentelemetry-cpp/pull/1209)) * [EXT] `curl::HttpClient` use `curl_multi_handle` instead of creating a thread for every request and it's able to reuse connections now. ([#1317](https://github.com/open-telemetry/opentelemetry-cpp/pull/1317)) +* [SEMANTIC CONVENTIONS] Upgrade to version 1.12.0 [#873](https://github.com/open-telemetry/opentelemetry-cpp/pull/873) ## [1.4.1] 2022-06-19 diff --git a/RELEASING.md b/RELEASING.md index 2725298a7f..8246e8fe44 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -2,24 +2,27 @@ ## Pre Release -1: Make sure all relevant changes for this release are included under +1: Upgrade to latest [semantic-conventions](docs/semantic-conventions.md) +if required. + +2: Make sure all relevant changes for this release are included under `Unreleased` section in `CHANGELOG.md` and are in language that non-contributors to the project can understand. -2: Run the pre-release script. It creates a branch `pre_release_` and +3: Run the pre-release script. It creates a branch `pre_release_` and updates `CHANGELOG.md` with the ``: ```sh ./buildscripts/pre_release.sh -t ``` -3: Verify that CHANGELOG.md is updated properly: +4: Verify that CHANGELOG.md is updated properly: ```sh git diff main ``` -4: Push the changes to upstream and create a Pull Request on GitHub. Be sure to +5: Push the changes to upstream and create a Pull Request on GitHub. Be sure to include the curated changes from the [Changelog](./CHANGELOG.md) in the description. diff --git a/api/include/opentelemetry/trace/semantic_conventions.h b/api/include/opentelemetry/trace/semantic_conventions.h index 0330253ba9..c5ea46aa1c 100644 --- a/api/include/opentelemetry/trace/semantic_conventions.h +++ b/api/include/opentelemetry/trace/semantic_conventions.h @@ -21,7 +21,7 @@ namespace SemanticConventions /** * The URL of the OpenTelemetry schema for these keys and values. */ -static constexpr const char *SCHEMA_URL = "https://opentelemetry.io/schemas/1.9.0"; +static constexpr const char *SCHEMA_URL = "https://opentelemetry.io/schemas/1.12.0"; /** * The full invoked ARN as provided on the {@code Context} passed to the function ({@code @@ -32,6 +32,40 @@ static constexpr const char *SCHEMA_URL = "https://opentelemetry.io/schemas/1.9. */ static constexpr const char *AWS_LAMBDA_INVOKED_ARN = "aws.lambda.invoked_arn"; +/** + * The event_id + * uniquely identifies the event. + */ +static constexpr const char *CLOUDEVENTS_EVENT_ID = "cloudevents.event_id"; + +/** + * The source + * identifies the context in which an event happened. + */ +static constexpr const char *CLOUDEVENTS_EVENT_SOURCE = "cloudevents.event_source"; + +/** + * The version of + * the CloudEvents specification which the event uses. + */ +static constexpr const char *CLOUDEVENTS_EVENT_SPEC_VERSION = "cloudevents.event_spec_version"; + +/** + * The event_type + * contains a value describing the type of event related to the originating occurrence. + */ +static constexpr const char *CLOUDEVENTS_EVENT_TYPE = "cloudevents.event_type"; + +/** + * The subject of + * the event in the context of the event producer (identified by source). + */ +static constexpr const char *CLOUDEVENTS_EVENT_SUBJECT = "cloudevents.event_subject"; + /** * Parent-child Reference type * @@ -207,7 +241,7 @@ is passed to a Context manager's {@code __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 +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 even if the {@code 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.
    • @@ -321,6 +355,10 @@ static constexpr const char *NET_PEER_PORT = "net.peer.port"; /** * Remote hostname or similar, see note below. + * + *

    Notes: +

    • {@code net.peer.name} SHOULD NOT be set if capturing it would require an extra DNS + lookup.
    */ static constexpr const char *NET_PEER_NAME = "net.peer.name"; @@ -522,6 +560,11 @@ static constexpr const char *HTTP_RESPONSE_CONTENT_LENGTH = "http.response_conte static constexpr const char *HTTP_RESPONSE_CONTENT_LENGTH_UNCOMPRESSED = "http.response_content_length_uncompressed"; +/** + * The ordinal number of request re-sending attempt. + */ +static constexpr const char *HTTP_RETRY_COUNT = "http.retry_count"; + /** * The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( {@code net.host.name} @@ -827,7 +870,7 @@ static constexpr const char *MESSAGING_ROCKETMQ_CONSUMPTION_MODEL = "messaging.rocketmq.consumption_model"; /** - * A string identifying the remoting system. + * A string identifying the remoting system. See below for a list of well-known identifiers. */ static constexpr const char *RPC_SYSTEM = "rpc.system"; @@ -1160,12 +1203,14 @@ static constexpr const char *LTE_CA = "lte_ca"; namespace HttpFlavorValues { -/** HTTP 1.0. */ +/** HTTP/1.0. */ static constexpr const char *HTTP_1_0 = "1.0"; -/** HTTP 1.1. */ +/** HTTP/1.1. */ static constexpr const char *HTTP_1_1 = "1.1"; -/** HTTP 2. */ +/** HTTP/2. */ static constexpr const char *HTTP_2_0 = "2.0"; +/** HTTP/3. */ +static constexpr const char *HTTP_3_0 = "3.0"; /** SPDY protocol. */ static constexpr const char *SPDY = "SPDY"; /** QUIC protocol. */ @@ -1208,6 +1253,18 @@ static constexpr const char *CLUSTERING = "clustering"; static constexpr const char *BROADCASTING = "broadcasting"; } // namespace MessagingRocketmqConsumptionModelValues +namespace RpcSystemValues +{ +/** gRPC. */ +static constexpr const char *GRPC = "grpc"; +/** Java RMI. */ +static constexpr const char *JAVA_RMI = "java_rmi"; +/** .NET WCF. */ +static constexpr const char *DOTNET_WCF = "dotnet_wcf"; +/** Apache Dubbo. */ +static constexpr const char *APACHE_DUBBO = "apache_dubbo"; +} // namespace RpcSystemValues + namespace RpcGrpcStatusCodeValues { /** OK. */ diff --git a/buildscripts/semantic-convention/generate.sh b/buildscripts/semantic-convention/generate.sh index 2cf1d6c3fd..48fc0ba0b2 100755 --- a/buildscripts/semantic-convention/generate.sh +++ b/buildscripts/semantic-convention/generate.sh @@ -10,7 +10,7 @@ SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" ROOT_DIR="${SCRIPT_DIR}/../../" # freeze the spec & generator tools versions to make SemanticAttributes generation reproducible -SEMCONV_VERSION=1.9.0 +SEMCONV_VERSION=1.12.0 SPEC_VERSION=v$SEMCONV_VERSION SCHEMA_URL=https://opentelemetry.io/schemas/$SEMCONV_VERSION GENERATOR_VERSION=0.7.0 diff --git a/docs/semantic-conventions.md b/docs/semantic-conventions.md new file mode 100644 index 0000000000..6240fe893a --- /dev/null +++ b/docs/semantic-conventions.md @@ -0,0 +1,80 @@ +# Semantic Conventions + +## Tooling + +The following files + +* [trace/semantic_conventions.h](/api/include/opentelemetry/trace/semantic_conventions.h) +* [sdk/resource/semantic_conventions.h](/sdk/include/opentelemetry/sdk/resource/semantic_conventions.h) + +are generated automatically. + +The source data is in YAML format, located in the +[specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/README.md). + +A code [generator](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/README.md) +parses the YAML data from the specs, +and generate code for various languages using a template engine. + +For opentelemetry-cpp, the templates are located in +[buildscripts](/buildscripts/semantic-convention/templates/SemanticAttributes.h.j2). + +A [generate.sh](/buildscripts/semantic-convention/generate.sh) script +downloads the specs, invokes the generator using Docker, +and generates code for opentelemetry-cpp. + +## Instructions + +### Find latest specifications + +Check for the latest +[specification](https://github.com/open-telemetry/opentelemetry-specification/releases) +release, and note the release tag number. + +For example, tag v1.12.0 + +### Use latest specifications + +Set the `SEMCONV_VERSION` number in the [generate.sh](/buildscripts/semantic-convention/generate.sh) script. + +For example, + +``` +SEMCONV_VERSION=1.12.0 +``` + + +### Generate code + +Run the generate.sh script. + +Inspect the generated files, +to verify they were updated (check the version number in SCHEMA_URL). + +For example, + +``` +static constexpr const char *SCHEMA_URL = "https://opentelemetry.io/schemas/1.12.0"; +``` + + +### Format code + +Apply clang-format. + + +### Update CHANGELOG + +Add a `CHANGELOG` entry for the semantic conventions. + +For example, + +``` +* [SEMANTIC CONVENTIONS] Upgrade to version 1.12.0 +``` + + +### Commit + +Commit and file a PR. + diff --git a/sdk/include/opentelemetry/sdk/resource/semantic_conventions.h b/sdk/include/opentelemetry/sdk/resource/semantic_conventions.h index a93ac05a1c..28d5438653 100644 --- a/sdk/include/opentelemetry/sdk/resource/semantic_conventions.h +++ b/sdk/include/opentelemetry/sdk/resource/semantic_conventions.h @@ -23,7 +23,44 @@ namespace SemanticConventions /** * The URL of the OpenTelemetry schema for these keys and values. */ -static constexpr const char *SCHEMA_URL = "https://opentelemetry.io/schemas/1.9.0"; +static constexpr const char *SCHEMA_URL = "https://opentelemetry.io/schemas/1.12.0"; + +/** + * Array of brand name and version separated by a space + * + *

    Notes: +

    • This value is intended to be taken from the UA client hints API + (navigator.userAgentData.brands).
    + */ +static constexpr const char *BROWSER_BRANDS = "browser.brands"; + +/** + * The platform on which the browser is running + * + *

    Notes: +

    • This value is intended to be taken from the UA client hints API +(navigator.userAgentData.platform). If unavailable, the legacy {@code 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. Note that some (but not all) of these values can overlap with values in the os.type and os.name attributes. However, for consistency, the values in the +{@code browser.platform} attribute should capture the exact value that the user agent provides.
      • +
    + */ +static constexpr const char *BROWSER_PLATFORM = "browser.platform"; + +/** + * Full user-agent string provided by the browser + * + *

    Notes: +

    • The user-agent value SHOULD be provided only from browsers that do not have a mechanism + to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the + value, the legacy {@code navigator.userAgent} API can be used.
    + */ +static constexpr const char *BROWSER_USER_AGENT = "browser.user_agent"; /** * Name of the cloud provider. @@ -228,10 +265,19 @@ static constexpr const char *DEVICE_MANUFACTURER = "device.manufacturer"; * The name of the single function that this runtime instance executes. * *

    Notes: -

    • 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 - code.namespace}/{@code code.function} span attributes).
    +
    • 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 +code.namespace}/{@code code.function} 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:
    • Azure: The full name {@code /}, 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 {@code faas.id} attribute).
      • +
    */ static constexpr const char *FAAS_NAME = "faas.name"; @@ -239,20 +285,23 @@ static constexpr const char *FAAS_NAME = "faas.name"; * The unique ID of the single function that this runtime instance executes. * *

    Notes: -

    +Resource ID of the invoked function, not the function app, having the form +{@code +/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. + */ static constexpr const char *FAAS_ID = "faas.id"; @@ -706,7 +755,7 @@ static constexpr const char *DRAGONFLYBSD = "dragonflybsd"; static constexpr const char *HPUX = "hpux"; /** AIX (Advanced Interactive eXecutive). */ static constexpr const char *AIX = "aix"; -/** Oracle Solaris. */ +/** SunOS, Oracle Solaris. */ static constexpr const char *SOLARIS = "solaris"; /** IBM z/OS. */ static constexpr const char *Z_OS = "z_os";