Skip to content

Commit

Permalink
[SEMANTIC CONVENTIONS] Migration to weaver (open-telemetry#3105)
Browse files Browse the repository at this point in the history
  • Loading branch information
marcalff authored Nov 13, 2024
1 parent a713947 commit f7a9aea
Show file tree
Hide file tree
Showing 108 changed files with 13,511 additions and 252 deletions.
21 changes: 16 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
78 changes: 78 additions & 0 deletions DEPRECATED.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
41 changes: 41 additions & 0 deletions api/include/opentelemetry/semconv/client_attributes.h
Original file line number Diff line number Diff line change
@@ -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
57 changes: 57 additions & 0 deletions api/include/opentelemetry/semconv/error_attributes.h
Original file line number Diff line number Diff line change
@@ -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
59 changes: 59 additions & 0 deletions api/include/opentelemetry/semconv/exception_attributes.h
Original file line number Diff line number Diff line change
@@ -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
Loading

1 comment on commit f7a9aea

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'OpenTelemetry-cpp api Benchmark'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 2.

Benchmark suite Current: f7a9aea Previous: 1863fe7 Ratio
BM_CreateBaggageFromTenEntries 12940.050873279895 ns/iter 6281.387666758719 ns/iter 2.06
BM_ExtractBaggageHavingTenEntries 2.9737296655799423 ns/iter 1.392473333068365 ns/iter 2.14
BM_CreateBaggageFrom180Entries 244105.74485105026 ns/iter 113640.21501341066 ns/iter 2.15
BM_ExtractBaggageWith180Entries 1.332994506905238 ns/iter 0.6292016078010623 ns/iter 2.12

This comment was automatically generated by workflow using github-action-benchmark.

Please sign in to comment.