Automatically generate semantic conventions from the spec (open-telem…

…etry#873)

Added documentation.

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
 

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_<new-tag>` and
+3: Run the pre-release script. It creates a branch `pre_release_<new-tag>` and
 updates `CHANGELOG.md` with the `<new-tag>`:
 
 ```sh
 ./buildscripts/pre_release.sh -t <new-tag>
 ```
 
-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.
 

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 <a href="https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id">event_id</a>
+ * uniquely identifies the event.
+ */
+static constexpr const char *CLOUDEVENTS_EVENT_ID = "cloudevents.event_id";
+
+/**
+ * The <a
+ * href="https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1">source</a>
+ * identifies the context in which an event happened.
+ */
+static constexpr const char *CLOUDEVENTS_EVENT_SOURCE = "cloudevents.event_source";
+
+/**
+ * The <a
+ * href="https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion">version of
+ * the CloudEvents specification</a> which the event uses.
+ */
+static constexpr const char *CLOUDEVENTS_EVENT_SPEC_VERSION = "cloudevents.event_spec_version";
+
+/**
+ * The <a
+ * href="https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type">event_type</a>
+ * contains a value describing the type of event related to the originating occurrence.
+ */
+static constexpr const char *CLOUDEVENTS_EVENT_TYPE = "cloudevents.event_type";
+
+/**
+ * The <a
+ * href="https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject">subject</a> 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.</li><li>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 <a href="#exception-end-example">example
+exception just before ending the span, as done in the <a href="#recording-an-exception">example
 above</a>.</li><li>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.</li> </ul>
@@ -321,6 +355,10 @@ static constexpr const char *NET_PEER_PORT = "net.peer.port";
 
 /**
  * Remote hostname or similar, see note below.
+ *
+ * <p>Notes:
+  <ul> <li>{@code net.peer.name} SHOULD NOT be set if capturing it would require an extra DNS
+ lookup.</li> </ul>
  */
 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. */

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

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.
+

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
+ *
+ * <p>Notes:
+  <ul> <li>This value is intended to be taken from the <a
+ href="https://wicg.github.io/ua-client-hints/#interface">UA client hints API</a>
+ (navigator.userAgentData.brands).</li> </ul>
+ */
+static constexpr const char *BROWSER_BRANDS = "browser.brands";
+
+/**
+ * The platform on which the browser is running
+ *
+ * <p>Notes:
+  <ul> <li>This value is intended to be taken from the <a
+href="https://wicg.github.io/ua-client-hints/#interface">UA client hints API</a>
+(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 <a
+href="https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform">W3C User-Agent Client Hints
+specification</a>. Note that some (but not all) of these values can overlap with values in the <a
+href="./os.md">os.type and os.name attributes</a>. However, for consistency, the values in the
+{@code browser.platform} attribute should capture the exact value that the user agent provides.</li>
+</ul>
+ */
+static constexpr const char *BROWSER_PLATFORM = "browser.platform";
+
+/**
+ * Full user-agent string provided by the browser
+ *
+ * <p>Notes:
+  <ul> <li>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.</li> </ul>
+ */
+static constexpr const char *BROWSER_USER_AGENT = "browser.user_agent";
 
 /**
  * Name of the cloud provider.
@@ -228,31 +265,43 @@ static constexpr const char *DEVICE_MANUFACTURER = "device.manufacturer";
  * The name of the single function that this runtime instance executes.
  *
  * <p>Notes:
-  <ul> <li>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 <a
- href="../../trace/semantic_conventions/span-general.md#source-code-attributes">{@code
- code.namespace}/{@code code.function}</a> span attributes).</li> </ul>
+  <ul> <li>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
+<a href="../../trace/semantic_conventions/span-general.md#source-code-attributes">{@code
+code.namespace}/{@code code.function}</a> span attributes).</li><li>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:</li><li><strong>Azure:</strong>  The full name {@code <FUNCAPP>/<FUNC>}, 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).</li>
+ </ul>
  */
 static constexpr const char *FAAS_NAME = "faas.name";
 
 /**
  * The unique ID of the single function that this runtime instance executes.
  *
  * <p>Notes:
-  <ul> <li>Depending on the cloud provider, use:</li><li><strong>AWS Lambda:</strong> The function
-<a href="https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html">ARN</a>.</li>
-<li>Take care not to use the &quot;invoked ARN&quot; directly but replace any
-<a href="https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html">alias suffix</a>
-with the resolved function version, as the same runtime instance may be invokable with multiple
-different aliases.</li><li><strong>GCP:</strong> The <a
+  <ul> <li>On some cloud providers, it may not be possible to determine the full ID at startup,
+so consider setting {@code faas.id} as a span attribute instead.</li><li>The exact value to use for
+{@code faas.id} depends on the cloud provider:</li><li><strong>AWS Lambda:</strong> The function <a
+href="https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html">ARN</a>. Take care
+not to use the &quot;invoked ARN&quot; directly but replace any <a
+href="https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html">alias suffix</a> with
+the resolved function version, as the same runtime instance may be invokable with multiple different
+aliases.</li> <li><strong>GCP:</strong> The <a
 href="https://cloud.google.com/iam/docs/full-resource-names">URI of the resource</a></li>
 <li><strong>Azure:</strong> The <a
 href="https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id">Fully Qualified
-Resource ID</a>.</li> <li>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 {@code faas.id} as a span
-attribute instead.</li> </ul>
+Resource ID</a> of the invoked function, <em>not</em> the function app, having the form
+{@code
+/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>}.
+This means that a span attribute MUST be used, as an Azure function app can host multiple functions
+that would usually share a TracerProvider.</li>
+ </ul>
  */
 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";