[SEMANTIC CONVENTIONS] Migration to weaver (open-telemetry#3105)

Author: marcalff

CHANGELOG.md

@@ -15,12 +15,18 @@ Increment the:
 
 ## [Unreleased]
 
-* [API] Comply with W3C Trace Context [#3115](https://github.com/open-telemetry/opentelemetry-cpp/pull/3115)
-  * Also adds CI check to ensure continued compliance
+* [API] Comply with W3C Trace Context
+  [#3115](https://github.com/open-telemetry/opentelemetry-cpp/pull/3115)
 
 * [API] Jaeger Propagator should not be deprecated
   [#3086](https://github.com/open-telemetry/opentelemetry-cpp/pull/3086)
 
+* Upgrade to prometheus 1.3.0
+  [#3122](https://github.com/open-telemetry/opentelemetry-cpp/pull/3122)
+
+* [SEMANTIC CONVENTIONS] Migration to weaver
+  [#3105](https://github.com/open-telemetry/opentelemetry-cpp/pull/3105)
+
 Important changes:
 
 * [API] Jaeger Propagator should not be deprecated
@@ -32,14 +38,19 @@ Important changes:
     as the Jaeger propagator can be used without the (now removed)
     Jaeger exporter.
 
-* Upgrade to prometheus 1.3.0
-  [#3122](https://github.com/open-telemetry/opentelemetry-cpp/pull/3122)
-
 * [EXPORTER] Change log resources location for ElasticsearchLogRecordExporter
   [#3119](https://github.com/open-telemetry/opentelemetry-cpp/pull/3131)
 
   * Moved from `root/resources` to `root`
 
+* [SEMANTIC CONVENTIONS] Migration to weaver
+  [#3105](https://github.com/open-telemetry/opentelemetry-cpp/pull/3105)
+
+  * `semantic_convention.h` header files are deprecated,
+    replaced by `semconv/xxx_attributes.h` header files,
+    for each `xxx` semantic attribute group.
+  * See file DEPRECATED.md for details.
+
 ## [1.17 2024-10-07]
 
 * [CI] Add a clang-tidy build

DEPRECATED.md

@@ -59,3 +59,81 @@ N/A
 ## [Documentation]
 
 N/A
+
+## Semantic conventions
+
+### Header files "semantic_conventions.h"
+
+#### Announcement (semantic_conventions.h)
+
+Deprecation is announced as part of the migration to weaver:
+
+* `Version:` release following opentelemetry-cpp 1.17.0
+* `Date:` Nov 9, 2024
+* `PR:` [PR 3105](https://github.com/open-telemetry/opentelemetry-cpp/pull/3105)
+
+#### Motivation (semantic_conventions.h)
+
+The header files for semantic conventions are generated automatically.
+The tooling to generate these files is changing:
+
+* before, the build-tool repository was used
+* now, the weaver repository is used
+
+Changes in tooling allows to generate code that is better organized,
+with dedicated header files per group of semantic conventions,
+instead of a single header file for everything.
+
+#### Scope (semantic_conventions.h)
+
+The following files:
+
+* `api/include/opentelemetry/trace/semantic_conventions.h`
+* `sdk/include/opentelemetry/sdk/resource/semantic_conventions.h`
+
+are now deprecated.
+
+They correspond to semantic conventions v1.27.0,
+and will no longer be maintained up to date.
+
+These files will be removed in the future.
+
+#### Mitigation (semantic_conventions.h)
+
+Two things have changed:
+
+* the header file to use
+* the symbol name to use.
+
+Before, the semantic convention for `url.full` was:
+
+* declared in file `semantic_conventions.h`
+* declared as symbol `SemanticConventions::kUrlFull`
+
+Now, the `url.full` convention, which is part or the `url` group, is:
+
+* declared in file `semconv/url_attributes.h`
+* declared as symbol `semconv::url::kUrlFull`
+
+Application code that uses semantic conventions must be adjusted
+accordingly.
+
+In addition, semantic conventions that are not marked as stable
+are generated in a different header file, placed under directory
+`incubating`, to better separate stable and non stable code.
+
+For example, file `semconv/incubating/url_attributes.h`
+defines `semconv::url::kUrlDomain`,
+which is not marked as stable in semconv v1.27.0
+
+#### Planned removal (semantic_conventions.h)
+
+The following files:
+
+* `api/include/opentelemetry/trace/semantic_conventions.h`
+* `sdk/include/opentelemetry/sdk/resource/semantic_conventions.h`
+
+will be removed.
+
+The removal date is planned for July 1, 2025.
+This allows more than six months for applications to adjust.

api/include/opentelemetry/semconv/client_attributes.h

@@ -0,0 +1,41 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * DO NOT EDIT, this is an Auto-generated file from:
+ * buildscripts/semantic-convention/templates/registry/semantic_attributes-h.j2
+ */
+
+#pragma once
+
+#include "opentelemetry/common/macros.h"
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace semconv
+{
+namespace client
+{
+
+/**
+ * Client address - domain name if available without reverse DNS lookup; otherwise, IP address or
+ * Unix domain socket name. <p> When observed from the server side, and when communicating through
+ * an intermediary, @code client.address @endcode SHOULD represent the client address behind any
+ * intermediaries,  for example proxies, if it's available.
+ */
+static constexpr const char *kClientAddress = "client.address";
+
+/**
+ * Client port number.
+ * <p>
+ * When observed from the server side, and when communicating through an intermediary, @code
+ * client.port @endcode SHOULD represent the client port behind any intermediaries,  for example
+ * proxies, if it's available.
+ */
+static constexpr const char *kClientPort = "client.port";
+
+}  // namespace client
+}  // namespace semconv
+OPENTELEMETRY_END_NAMESPACE

api/include/opentelemetry/semconv/error_attributes.h

@@ -0,0 +1,57 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * DO NOT EDIT, this is an Auto-generated file from:
+ * buildscripts/semantic-convention/templates/registry/semantic_attributes-h.j2
+ */
+
+#pragma once
+
+#include "opentelemetry/common/macros.h"
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace semconv
+{
+namespace error
+{
+
+/**
+ * Describes a class of error the operation ended with.
+ * <p>
+ * The @code error.type @endcode SHOULD be predictable, and SHOULD have low cardinality.
+ * <p>
+ * When @code error.type @endcode is set to a type (e.g., an exception type), its
+ * canonical class name identifying the type within the artifact SHOULD be used.
+ * <p>
+ * Instrumentations SHOULD document the list of errors they report.
+ * <p>
+ * The cardinality of @code error.type @endcode within one instrumentation library SHOULD be low.
+ * Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+ * should be prepared for @code error.type @endcode to have high cardinality at query time when no
+ * additional filters are applied.
+ * <p>
+ * If the operation has completed successfully, instrumentations SHOULD NOT set @code error.type
+ * @endcode. <p> If a specific domain defines its own set of error identifiers (such as HTTP or gRPC
+ * status codes), it's RECOMMENDED to: <p> <ul> <li>Use a domain-specific attribute</li> <li>Set
+ * @code error.type @endcode to capture all errors, regardless of whether they are defined within
+ * the domain-specific set or not.</li>
+ * </ul>
+ */
+static constexpr const char *kErrorType = "error.type";
+
+namespace ErrorTypeValues
+{
+/**
+ * A fallback error value to be used when the instrumentation doesn't define a custom value.
+ */
+static constexpr const char *kOther = "_OTHER";
+
+}  // namespace ErrorTypeValues
+
+}  // namespace error
+}  // namespace semconv
+OPENTELEMETRY_END_NAMESPACE

api/include/opentelemetry/semconv/exception_attributes.h

@@ -0,0 +1,59 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * DO NOT EDIT, this is an Auto-generated file from:
+ * buildscripts/semantic-convention/templates/registry/semantic_attributes-h.j2
+ */
+
+#pragma once
+
+#include "opentelemetry/common/macros.h"
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace semconv
+{
+namespace exception
+{
+
+/**
+ * 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. <p> 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 @code __exit__ @endcode method in Python) but will usually be caught at the
+ * point of recording the exception in most languages. <p> 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="https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception">example
+ * for recording span exceptions</a>. <p> It follows that an exception may still escape the scope of
+ * the span even if the @code exception.escaped @endcode 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.
+ */
+static constexpr const char *kExceptionEscaped = "exception.escaped";
+
+/**
+ * The exception message.
+ */
+static constexpr const char *kExceptionMessage = "exception.message";
+
+/**
+ * A stacktrace as a string in the natural representation for the language runtime. The
+ * representation is to be determined and documented by each language SIG.
+ */
+static constexpr const char *kExceptionStacktrace = "exception.stacktrace";
+
+/**
+ * The type of the exception (its fully-qualified class name, if applicable). The dynamic type of
+ * the exception should be preferred over the static type in languages that support it.
+ */
+static constexpr const char *kExceptionType = "exception.type";
+
+}  // namespace exception
+}  // namespace semconv
+OPENTELEMETRY_END_NAMESPACE