From b317d7adbe44f73dba500cc6845ae9a68c775157 Mon Sep 17 00:00:00 2001 From: Tom Tan Date: Tue, 15 Mar 2022 11:23:58 -0700 Subject: [PATCH 1/3] Enable line-length lint for markdown docs --- .markdownlint.json | 6 +- docs/building-with-stdlib.md | 4 +- docs/building-with-vs2019.md | 3 +- docs/cpp-metrics-api-design.md | 4 +- docs/cpp-metrics-sdk-design.md | 4 - docs/cpp-ostream-exporter-design.md | 2 - docs/dependencies.md | 90 ++++++++++++----- docs/google-test.md | 151 ++++++++++++++++++++++------ 8 files changed, 193 insertions(+), 71 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index 5eb727082c..48c2ae2a3f 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,4 +1,8 @@ { "default": true, - "line-length": false + "MD013": + { + "code_blocks": false, + "tables": false + } } diff --git a/docs/building-with-stdlib.md b/docs/building-with-stdlib.md index 26e09f9d39..a90a14a6ed 100644 --- a/docs/building-with-stdlib.md +++ b/docs/building-with-stdlib.md @@ -162,7 +162,9 @@ gcc-7 | C++17 | requires `gsl::span` for `std::span` im gcc-9+ | C++20 | If SDK is compiled without standard library classes, then `nostd::variant` -implementation internally uses a private snapshot of [Abseil Variant](https://github.com/abseil/abseil-cpp/blob/master/absl/types/variant.h) . +implementation internally uses a private snapshot of [Abseil +Variant](https://github.com/abseil/abseil-cpp/blob/master/absl/types/variant.h) +. Other modern C++ language features used by OpenTelemetry, e.g. `std::string_view` and `std::variant` are available in C++17 standard library. diff --git a/docs/building-with-vs2019.md b/docs/building-with-vs2019.md index c2783e60ca..fa41c4a1ba 100644 --- a/docs/building-with-vs2019.md +++ b/docs/building-with-vs2019.md @@ -136,7 +136,8 @@ instructions that detail how to [run build build tools in a docker container](ht build tooling. This script installs all build tools and builds all 3rd party dependencies from source using [vcpkg package manager](https://vcpkg.io/en/index.html). - Launch Visual Studio 2019 IDE. -- Use `Open a local folder` option to open the folder where you cloned the source code. +- Use `Open a local folder` option to open the folder where you cloned the + source code. - Right-click on `CMakeLists.txt` and choose `Generate Cache for opentelemetry-cpp`. - In the top bar menu - select `Build -> Build All` to build SDK, Exporters and Tests. - You can use [Google Test Adapter](https://marketplace.visualstudio.com/items?itemName=ChristianSoltenborn.GoogleTestAdapter) diff --git a/docs/cpp-metrics-api-design.md b/docs/cpp-metrics-api-design.md index 8e6e81ce65..8123789ec5 100644 --- a/docs/cpp-metrics-api-design.md +++ b/docs/cpp-metrics-api-design.md @@ -139,7 +139,6 @@ private: }; ``` - ```cpp # meter_provider.h class MeterProvider @@ -170,7 +169,7 @@ function. This interface consists of a set of **instrument constructors**, and a **facility for capturing batches of measurements.** -```cpp +``` cpp # meter.h class Meter { public: @@ -258,7 +257,6 @@ private: InstrumentationInfo instrumentationInfo_; } ``` - ### Meter API Class Design Considerations diff --git a/docs/cpp-metrics-sdk-design.md b/docs/cpp-metrics-sdk-design.md index 6a3e517e74..7ae3c16c0f 100644 --- a/docs/cpp-metrics-sdk-design.md +++ b/docs/cpp-metrics-sdk-design.md @@ -133,7 +133,6 @@ error.** **Implementation:** - ```cpp # meter.h / meter.cc class Meter : public API::Meter { @@ -271,9 +270,7 @@ private: InstrumentationInfo instrumentationInfo_; }; ``` - - ```cpp # record.h /* @@ -316,7 +313,6 @@ private: nostd::variant, Aggregator, Aggregator, Aggregator> aggregator_; }; ``` - Metric instruments created from this Meter class will be stored in a map (or another, similar container [needs to be nostd]) called “metrics.” This is diff --git a/docs/cpp-ostream-exporter-design.md b/docs/cpp-ostream-exporter-design.md index 64a36570d4..7deb369ab3 100644 --- a/docs/cpp-ostream-exporter-design.md +++ b/docs/cpp-ostream-exporter-design.md @@ -101,7 +101,6 @@ want to make the shutdown timeout configurable. In the OStreamExporter there is no cleanup to be done, so there is no need to use the timeout within the `Shutdown` function as it will never be blocking. - ```cpp class StreamSpanExporter final : public sdktrace::SpanExporter { @@ -162,7 +161,6 @@ public: } }; ``` - ## MetricsExporter diff --git a/docs/dependencies.md b/docs/dependencies.md index 14d32a8459..1a5d1d0f28 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -3,59 +3,97 @@ There are - External dependencies as linkable libraries or externally installed headers, and -- Internal dependencies as the part of code from external libraries backported/copied in main repo. +- Internal dependencies as the part of code from external libraries + backported/copied in main repo. Both these dependencies are listed here: ## Internal dependencies -- [nostd::variant](https://github.com/open-telemetry/opentelemetry-cpp/blob/v1.0.0-rc1/api/include/opentelemetry/nostd/absl/types/variant.h): This is backported from [Abseil C++ libraries](https://github.com/abseil/abseil-cpp) and used as default variant implementation. License: `Apache License 2.0` -- [TraceLoggingDynamic](https://github.com/open-telemetry/opentelemetry-cpp/blob/v1.0.0-rc1/exporters/etw/include/opentelemetry/exporters/etw/TraceLoggingDynamic.h): Dynamic TraceLogging Provider API for C++ used by ETW exporter. License: `MIT License` +- [nostd::variant](https://github.com/open-telemetry/opentelemetry-cpp/blob/v1.0.0-rc1/api/include/opentelemetry/nostd/absl/types/variant.h): + This is backported from [Abseil C++ + libraries](https://github.com/abseil/abseil-cpp) and used as default variant + implementation. License: `Apache License 2.0` +- [TraceLoggingDynamic](https://github.com/open-telemetry/opentelemetry-cpp/blob/v1.0.0-rc1/exporters/etw/include/opentelemetry/exporters/etw/TraceLoggingDynamic.h): + Dynamic TraceLogging Provider API for C++ used by ETW exporter. License: `MIT + License` ## External dependencies -- [API](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/api) & [SDK](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/sdk): - - Uses Standard C++ library for latest features (std::string_view, std::variant, std::span, std::shared_ptr, std::unique_ptr) with C++14/17/20 compiler if `WITH_STL` cmake option is enabled or `HAVE_CPP_STDLIB` macro is defined. License: `GNU General Public License` - - For C++11/14/17 compilers, fallback to gsl::span if [GSL C++ library](https://github.com/microsoft/GSL) is installed. License: `MIT License` - - Uses Abseil C++ Library for `absl::variant` as default `nostd::variant` if `WITH_ABSEIL` cmake option or `--@io_opentelemetry_cpp/api:with_abseil=true` (aka `--//api:with_abseil=true`) bazel option is enabled. License: `Apache License 2.0` +- [API](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/api) + & + [SDK](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/sdk): + - Uses Standard C++ library for latest features (std::string_view, + std::variant, std::span, std::shared_ptr, std::unique_ptr) with C++14/17/20 + compiler if `WITH_STL` cmake option is enabled or `HAVE_CPP_STDLIB` macro is + defined. License: `GNU General Public License` + - For C++11/14/17 compilers, fallback to gsl::span if [GSL C++ + library](https://github.com/microsoft/GSL) is installed. License: `MIT + License` + - Uses Abseil C++ Library for `absl::variant` as default `nostd::variant` if + `WITH_ABSEIL` cmake option or + `--@io_opentelemetry_cpp/api:with_abseil=true` (aka + `--//api:with_abseil=true`) bazel option is enabled. License: `Apache + License 2.0` -- [OTLP/HTTP+JSON](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/otlp) exporter: - - [protobuf](https://github.com/protocolbuffers/protobuf): Library to serialize structured data. +- [OTLP/HTTP+JSON](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/otlp) + exporter: + - [protobuf](https://github.com/protocolbuffers/protobuf): Library to + serialize structured data. - OTLP messages are constructed as protobuf payloads. - - `protoc` compiler is used to generate C++ stubs for proto files provided by `opentelemetry-proto`. - - `libprotobuf` library is used for generating serialised trace/metrics/log data to be sent to opentelemetry collector. - - License: The library is licensed [here](https://github.com/protocolbuffers/protobuf/blob/master/LICENSE). The code generated by protoc compiler is owned by the owner of `.proto` file. - - [libcurl](https://curl.se/libcurl/) : the multiprotocol file transfer library. - - Export connects with opentelemetry collector over HTTP protocol using libcurl library - - License: Inspired by `MIT/X` but not same. + - `protoc` compiler is used to generate C++ stubs for proto files provided + by `opentelemetry-proto`. + - `libprotobuf` library is used for generating serialised trace/metrics/log + data to be sent to opentelemetry collector. + - License: The library is licensed + [here](https://github.com/protocolbuffers/protobuf/blob/master/LICENSE). + The code generated by protoc compiler is owned by the owner of `.proto` + file. + - [libcurl](https://curl.se/libcurl/) : the multiprotocol file transfer + library. + - Export connects with opentelemetry collector over HTTP protocol using + libcurl library + - License: Inspired by `MIT/X` but not same. + - [nlohmann/json](https://github.com/nlohmann/json): JSON for Modern C++. - - protobuf serialized otlp messages are encoded in JSON format using this library. + - protobuf serialized otlp messages are encoded in JSON format using this + library. - License: `MIT License` -- [OTLP/gRPC](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/otlp) exporter: +- [OTLP/gRPC](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/otlp) + exporter: - `protobuf` OTLP messages are constructed as protobuf payloads. - [gRPC](https://github.com/grpc/grpc): An RPC library and framework - Exporter communicates with OTLP collector using gRPC transport mechanism. - License: `Apache License 2.0` -- [Zipkin](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/zipkin) exporter: +- [Zipkin](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/zipkin) + exporter: - `libcurl` for connecting with Zipkin server over HTTP protocol. - `nlohmann/json` for encoding Zipkin messages. -- [Jaeger](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/jaeger) exporter: - - [Thrift](https://github.com/apache/thrift) - Serialization and RPC framework. +- [Jaeger](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/jaeger) + exporter: + - [Thrift](https://github.com/apache/thrift) - Serialization and RPC + framework. - `thrift` compiler to generate C++ stubs for IDL data model for Jaeger. - - `libthrift` library to generate serialised trace/metrics/log data to be sent to remote Jaeger service. + - `libthrift` library to generate serialised trace/metrics/log data to be + sent to remote Jaeger service. - License: `Apache License 2.0` -- [ETW](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/etw) exporter: - - `nlohmann/json` for generating MessagePack serialization for message to be transmitted to ETW. +- [ETW](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/etw) + exporter: + - `nlohmann/json` for generating MessagePack serialization for message to be + transmitted to ETW. -- [Prometheus](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/prometheus) exporter: - - [`prometheus-cpp`](https://github.com/jupp0r/prometheus-cpp) Prometheus Client Library for Modern C++ +- [Prometheus](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/prometheus) + exporter: + - [`prometheus-cpp`](https://github.com/jupp0r/prometheus-cpp) Prometheus + Client Library for Modern C++ - License: `MIT License` -- [ElasticSearch](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/elasticsearch) exporter: +- [ElasticSearch](https://github.com/open-telemetry/opentelemetry-cpp/tree/v1.0.0-rc1/exporters/elasticsearch) + exporter: - `libcurl` for connecting with Elasticsearch server over HTTP protocol. - `nlohmann/json` for encoding Elastic Search messages. diff --git a/docs/google-test.md b/docs/google-test.md index d824019958..fc9aa3f675 100644 --- a/docs/google-test.md +++ b/docs/google-test.md @@ -2,19 +2,34 @@ ## Introduction -[Google Test](https://github.com/google/googletest) is a unit testing framework for C++ programming developed by Google. It is currently being used for unit testing in the [OpenTelemetry C++](https://github.com/open-telemetry/opentelemetry-cpp) repo, along with tools like [codecov.io](http://codecov.io/) to thoroughly test the code in the repository. A primer for using Google Test can be found [here](https://github.com/google/googletest/blob/master/googletest/docs/primer.md). +[Google Test](https://github.com/google/googletest) is a unit testing framework +for C++ programming developed by Google. It is currently being used for unit +testing in the [OpenTelemetry +C++](https://github.com/open-telemetry/opentelemetry-cpp) repo, along with tools +like [codecov.io](http://codecov.io/) to thoroughly test the code in the +repository. A primer for using Google Test can be found +[here](https://github.com/google/googletest/blob/master/googletest/docs/primer.md). ## Features -Google Test provides a vast set of tools to be used for unit testing. The two most important are assertions and tests. +Google Test provides a vast set of tools to be used for unit testing. The two +most important are assertions and tests. ### Assertions -Google Test allows a developer to write test cases that use assertions to verify code behavior. Refer to the [assertions](https://github.com/google/googletest/blob/master/googletest/docs/primer.md#assertions) section in the primer for more details. +Google Test allows a developer to write test cases that use assertions to verify +code behavior. Refer to the +[assertions](https://github.com/google/googletest/blob/master/googletest/docs/primer.md#assertions) +section in the primer for more details. ### Tests -To create a test, use the `TEST()` macro to define a test function. This is similar to a normal C++ function that returns no value. Google Test assertions are used inside the test function, and the result of the test is determined by the assertions used inside the test function. If any assertion fails (can be either fatal or nonfatal), then the test fails; if all assertions pass, the test succeeds. A sample test function is outlined below. +To create a test, use the `TEST()` macro to define a test function. This is +similar to a normal C++ function that returns no value. Google Test assertions +are used inside the test function, and the result of the test is determined by +the assertions used inside the test function. If any assertion fails (can be +either fatal or nonfatal), then the test fails; if all assertions pass, the test +succeeds. A sample test function is outlined below. ```cpp TEST(TestSuiteName, TestName) { @@ -24,7 +39,10 @@ TEST(TestSuiteName, TestName) { } ``` -A [sample unit test](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/sdk/test/trace/tracer_provider_test.cc) from the OTel C++ repo, testing the `GetTracer()` method in the `TracerProvider` class, is shown below. +A [sample unit +test](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/sdk/test/trace/tracer_provider_test.cc) +from the OTel C++ repo, testing the `GetTracer()` method in the `TracerProvider` +class, is shown below. ```cpp #include "opentelemetry/sdk/trace/tracer_provider.h" @@ -68,17 +86,32 @@ TEST(TracerProvider, GetTracer) ### Test Coverage Reports -Another feature that Google Test provides is test coverage reports; along with this, Google Test also allows us to easily integrate code coverage tools such as [codecov.io](http://codecov.io/) with the project. +Another feature that Google Test provides is test coverage reports; along with +this, Google Test also allows us to easily integrate code coverage tools such as +[codecov.io](http://codecov.io/) with the project. ## Integration and Usage -One of the base requirements to build and use Google Test from a source package are to use either Bazel or CMake; the other is a C++11-standard-compliant compiler like GCC or Clang. +One of the base requirements to build and use Google Test from a source package +are to use either Bazel or CMake; the other is a C++11-standard-compliant +compiler like GCC or Clang. ### Bazel -First, to install bazel, refer to the instructions [here](https://docs.bazel.build/versions/3.3.0/install.html), and for an example build using bazel, refer to the tutorial [here](https://docs.bazel.build/versions/3.3.0/tutorial/cpp.html). - -Bazel makes use of a `BUILD` file, which gives instructions to bazel on how to build the project. The file contains targets that point to a set of source files and dependencies. Along with a `BUILD` file, a `WORKSPACE` file exists that identifies the directory it resides in as a bazel workspace. In the OTel C++ repository, the SDK unit tests using the Google Test framework to ensure code functionality. In the [BUILD](https://github.com/open-telemetry/opentelemetry-cpp/tree/master/sdk/test/trace) file for trace tests, there are six different targets, each corresponding to a different unit test. An example target taken from this file is shown below. +First, to install bazel, refer to the instructions +[here](https://docs.bazel.build/versions/3.3.0/install.html), and for an example +build using bazel, refer to the tutorial +[here](https://docs.bazel.build/versions/3.3.0/tutorial/cpp.html). + +Bazel makes use of a `BUILD` file, which gives instructions to bazel on how to +build the project. The file contains targets that point to a set of source files +and dependencies. Along with a `BUILD` file, a `WORKSPACE` file exists that +identifies the directory it resides in as a bazel workspace. In the OTel C++ +repository, the SDK unit tests using the Google Test framework to ensure code +functionality. In the +[BUILD](https://github.com/open-telemetry/opentelemetry-cpp/tree/master/sdk/test/trace) +file for trace tests, there are six different targets, each corresponding to a +different unit test. An example target taken from this file is shown below. ```cmake cc_test( @@ -98,18 +131,24 @@ Integrating Google Tests with bazel is as simple as creating a target with: - name: The target name, aka the name of the binary to build - srcs: The source file containing the tests -- deps: The dependencies of the build; here, `//sdk/src/trace` refers to the directory of the source code being tested, and `@com_google_googletest//:gtest_main` is the Google Test dependency. +- deps: The dependencies of the build; here, `//sdk/src/trace` refers to the + directory of the source code being tested, and + `@com_google_googletest//:gtest_main` is the Google Test dependency. -Building and executing a unit test is also very simple. On terminal, navigate to the directory the WORKSPACE file resides in, and execute two commands: +Building and executing a unit test is also very simple. On terminal, navigate to +the directory the WORKSPACE file resides in, and execute two commands: ```console bazel build //path/to/package:target-name bazel-bin/path/to/package/target-name ``` -The first command builds the unit test with the given target name; the second runs the unit test. +The first command builds the unit test with the given target name; the second +runs the unit test. -This next command runs the above two commands at once, though you may get a message stating `There were tests whose specified size is too big` and they may not run without modifying some options. +This next command runs the above two commands at once, though you may get a +message stating `There were tests whose specified size is too big` and they may +not run without modifying some options. ```console bazel test //path/to/package:target-name @@ -128,7 +167,8 @@ or bazel test //sdk/test/trace:tracer_provider_test ``` -Additionally, all Bazel tests can be ran in a Docker container by navigating to the root of the directory and executing the command: +Additionally, all Bazel tests can be ran in a Docker container by navigating to +the root of the directory and executing the command: ```console ./ci/run_docker.sh ./ci/do_ci.sh bazel.test @@ -136,9 +176,13 @@ Additionally, all Bazel tests can be ran in a Docker container by navigating to ### CMake -CMake can be installed following instructions from [here](https://cmake.org/download/). You will also need to install Google Test, along with libbenchmark. +CMake can be installed following instructions from +[here](https://cmake.org/download/). You will also need to install Google Test, +along with libbenchmark. -Download a zip of the Google Test source code [here](https://github.com/google/googletest/releases/tag/release-1.10.0). Then, navigate into the source code directory and run the following commands: +Download a zip of the Google Test source code +[here](https://github.com/google/googletest/releases/tag/release-1.10.0). Then, +navigate into the source code directory and run the following commands: ```console mkdir build && cd build @@ -147,11 +191,26 @@ make make install ``` -This will install Google Test for you; you can delete the source code after running these commands. - -Next, follow the instructions [here](https://github.com/google/benchmark#installation) to download Google Benchmark. The section following this one will detail performance benchmarking using Google Benchmark. - -CMake makes use of a `CMakeLists.txt` file that provides instructions for a project’s source files and targets. There is a main `CMakeLists.txt` file in the root of the project directory, and a `CMakeLists.txt` for each subdirectory. In the main `CMakeLists.txt` file, the `cmake_minimum_required` and `CMAKE_CXX_STANDARD` are set, the project name is set with `project()`, directories are included and subdirectories added, and much more. However, more importantly, in the context of Google Test within the OTel C++ repo, the `CMakeLists.txt` to look at is the one located in the directory your tests are being written in; for this example, it’s `opentelemetry-cpp/sdk/test/trace`. This [CMakeLists.txt](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/sdk/test/trace/CMakeLists.txt) file, shown below, describes the names of the tests to be added as executables. +This will install Google Test for you; you can delete the source code after +running these commands. + +Next, follow the instructions +[here](https://github.com/google/benchmark#installation) to download Google +Benchmark. The section following this one will detail performance benchmarking +using Google Benchmark. + +CMake makes use of a `CMakeLists.txt` file that provides instructions for a +project’s source files and targets. There is a main `CMakeLists.txt` file in the +root of the project directory, and a `CMakeLists.txt` for each subdirectory. In +the main `CMakeLists.txt` file, the `cmake_minimum_required` and +`CMAKE_CXX_STANDARD` are set, the project name is set with `project()`, +directories are included and subdirectories added, and much more. However, more +importantly, in the context of Google Test within the OTel C++ repo, the +`CMakeLists.txt` to look at is the one located in the directory your tests are +being written in; for this example, it’s `opentelemetry-cpp/sdk/test/trace`. +This +[CMakeLists.txt](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/sdk/test/trace/CMakeLists.txt) +file, shown below, describes the names of the tests to be added as executables. ```cmake foreach( @@ -179,9 +238,13 @@ target_link_libraries(sampler_benchmark benchmark::benchmark ``` -This is how a `CMakeLists.txt` file will be written with the purpose of unit testing. After writing a unit test, navigate to the `CMakeLists.txt` file for that subdirectory and add the test name to the list of test names in `foreach()`. +This is how a `CMakeLists.txt` file will be written with the purpose of unit +testing. After writing a unit test, navigate to the `CMakeLists.txt` file for +that subdirectory and add the test name to the list of test names in +`foreach()`. -To build and execute using CMake, navigate into the root directory (`opentelemetry-cpp` here), and run the following commands from terminal: +To build and execute using CMake, navigate into the root directory +(`opentelemetry-cpp` here), and run the following commands from terminal: ```console mkdir build && cd build @@ -192,25 +255,30 @@ make test This will run all tests in the repo. -To run tests individually, in terminal, navigate to the `build` directory and execute the following command: +To run tests individually, in terminal, navigate to the `build` directory and +execute the following command: ```console ctest -R ``` -For example, this command will build and execute the test named TEST(Meter, CollectSyncInstruments) in the metrics library: +For example, this command will build and execute the test named TEST(Meter, +CollectSyncInstruments) in the metrics library: ```console ctest -R metrics.Meter.CollectSyncInstruments ``` -The second cmake option creates test coverage reports; these are able to be viewed using a tool like lcov (instructions to download [here](http://ltp.sourceforge.net/coverage/lcov.php)), and running the command +The second cmake option creates test coverage reports; these are able to be +viewed using a tool like lcov (instructions to download +[here](http://ltp.sourceforge.net/coverage/lcov.php)), and running the command ```console lcov --directory $PWD --capture --output-file coverage.info ``` -Additionally, all CMake tests can be ran in a Docker container by navigating to the root of the directory and executing the command: +Additionally, all CMake tests can be ran in a Docker container by navigating to +the root of the directory and executing the command: ```console ./ci/run_docker.sh ./ci/do_ci.sh cmake.test @@ -218,9 +286,21 @@ Additionally, all CMake tests can be ran in a Docker container by navigating to ### Performance Benchmarking -While Google Test itself does not provide performance benchmarking, Google Benchmark, a closely related tool, does. Follow the instructions [here](https://github.com/google/benchmark#installation) to download Google Benchmark using CMake. A basic usage example can be viewed [here](https://github.com/google/benchmark#usage), while a more in depth usage guide can be found [here](https://github.com/google/benchmark#user-guide). Generally, it is very similar to the Googletest unit testing structure and we can easily convert unit tests into benchmarked routines. - -A benchmark consists of a “benchmarked function” which takes a benchmark state as a parameter. The library automatically decides how many iterations to run based on the duration of the first few run iterations. This function is called directly underneath using the benchmark macro. Finally, a call to BENCHMARK_MAIN() runs all benchmarks. As a proof of concept, below is a unit test for the PrometheusCollector class into a benchmark: +While Google Test itself does not provide performance benchmarking, Google +Benchmark, a closely related tool, does. Follow the instructions +[here](https://github.com/google/benchmark#installation) to download Google +Benchmark using CMake. A basic usage example can be viewed +[here](https://github.com/google/benchmark#usage), while a more in depth usage +guide can be found [here](https://github.com/google/benchmark#user-guide). +Generally, it is very similar to the Googletest unit testing structure and we +can easily convert unit tests into benchmarked routines. + +A benchmark consists of a “benchmarked function” which takes a benchmark state +as a parameter. The library automatically decides how many iterations to run +based on the duration of the first few run iterations. This function is called +directly underneath using the benchmark macro. Finally, a call to +BENCHMARK_MAIN() runs all benchmarks. As a proof of concept, below is a unit +test for the PrometheusCollector class into a benchmark: ```cpp #include "opentelemetry/exporters/prometheus/prometheus_collector.h" @@ -285,6 +365,11 @@ Benchmark Time CPU Iterations CreateRecordsAndCollect 51989 ns 51821 ns 12438 ``` -OTel also provides a bazel shortcut to build tests which can be seen [here](https://github.com/open-telemetry/opentelemetry-cpp/blob/573696f3fdc1fd85e24ac19860ae6f2345837a3e/bazel/otel_cc_benchmark.bzl). This not only creates a benchmark executable, but a “smoketest” which runs each benchmark for one iteration. +OTel also provides a bazel shortcut to build tests which can be seen +[here](https://github.com/open-telemetry/opentelemetry-cpp/blob/573696f3fdc1fd85e24ac19860ae6f2345837a3e/bazel/otel_cc_benchmark.bzl). +This not only creates a benchmark executable, but a “smoketest” which runs each +benchmark for one iteration. -We can use benchmarking to measure performance of exporting, data translation, and collecting. Additionally, creating benchmarks for each component will help us determine which areas of the pipeline can be optimized further. +We can use benchmarking to measure performance of exporting, data translation, +and collecting. Additionally, creating benchmarks for each component will help +us determine which areas of the pipeline can be optimized further. From ca151095b260cc0470ea393c5e58be95bd9700e4 Mon Sep 17 00:00:00 2001 From: Tom Tan Date: Tue, 15 Mar 2022 11:29:24 -0700 Subject: [PATCH 2/3] Remove more inline markdownlint rules --- docs/cpp-metrics-api-design.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/cpp-metrics-api-design.md b/docs/cpp-metrics-api-design.md index 8123789ec5..bb460f04c7 100644 --- a/docs/cpp-metrics-api-design.md +++ b/docs/cpp-metrics-api-design.md @@ -352,7 +352,6 @@ call: `instrument.Add(x, labels)`. MUST support `RecordBatch` calling (where a single set of labels is applied to several metric instruments). - ```cpp # metric.h @@ -514,7 +513,6 @@ private: void (*callback_)(ObserverResult); }; ``` - The Counter below is an example of one Metric instrument. It is important to note that in the Counter’s add function, it binds the labels to the instrument @@ -522,7 +520,6 @@ before calling add, then unbinds. Therefore all interactions with the aggregator take place through bound instruments and by extension, the BaseBoundInstrument Class. - ```cpp template class BoundCounter: public BoundSynchronousInstrument{ //override bind? @@ -597,7 +594,6 @@ class BoundUpDownSumObserver: public AsynchronousInstrument; class ValueObserver: public AsynchronousInstrument; class BoundValueObserver: public AsynchronousInstrument; ``` - ### Metric Class Design Considerations From a39a28cfef50405343efc114c2ea6d0fb9a9e783 Mon Sep 17 00:00:00 2001 From: Tom Tan Date: Tue, 15 Mar 2022 20:23:47 -0700 Subject: [PATCH 3/3] Format more doc --- CHANGELOG.md | 482 +++++++++++++++++++---------- INSTALL.md | 88 +++--- README.md | 22 +- Versioning.md | 39 +-- examples/grpc/README.md | 24 +- examples/http/README.md | 18 +- examples/multi_processor/README.md | 13 +- examples/zipkin/README.md | 7 +- exporters/etw/README.md | 145 +++++---- 9 files changed, 539 insertions(+), 299 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52c30cfea8..4f66ec617a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,221 +43,393 @@ previous logs, please update API package to this release if ## [1.1.1] 2021-12-20 -* [SDK] Rename OTEL_CPP_GET_ATTR macro, and define it using fully qualified attr function ([#1140](https://github.com/open-telemetry/opentelemetry-cpp/pull/1140)) -* [SDK] Default resource attributes and attributes in OTEL_RESOURCE_ATTRIBUTES are missing when using Otlp*LogExporter ([#1082](https://github.com/open-telemetry/opentelemetry-cpp/pull/1082)) -* [METRICS] Add Meter and MeterProvider in the SDK ([#1078](https://github.com/open-telemetry/opentelemetry-cpp/pull/1078)) -* [EXPORTER] ZipkinExporter shutdown ([#1153](https://github.com/open-telemetry/opentelemetry-cpp/pull/1153)) -* [EXPORTER] Jaeger exporter shutdown ([#1150](https://github.com/open-telemetry/opentelemetry-cpp/pull/1150)) -* [EXPORTER] Bugfix: `jaeger::TUDPTransport::write` crash when `getaddrinfo` returns error ([#1116](https://github.com/open-telemetry/opentelemetry-cpp/pull/1116)) -* [EXPORTER] Bugfix: Jaeger exporter: extend supported attributes types ([#1106](https://github.com/open-telemetry/opentelemetry-cpp/pull/1106)) -* [EXPORTER] Fix otlp generates null span ids ([#1113](https://github.com/open-telemetry/opentelemetry-cpp/pull/1113)) -* [EXPORTER] Jaeger bazel (Linux only) ([#1077](https://github.com/open-telemetry/opentelemetry-cpp/pull/1077)) -* [DOCS] Add note on DLL support ([#1137](https://github.com/open-telemetry/opentelemetry-cpp/pull/1137)) -* [DOCS] Improve the instructions for Bazel build ([#1136](https://github.com/open-telemetry/opentelemetry-cpp/pull/1136)) -* [DOCS] Document dependencies ([#1119](https://github.com/open-telemetry/opentelemetry-cpp/pull/1119)) -* [DOCS] Dockerfile for quick demo/troubleshooting purpose ([#905](https://github.com/open-telemetry/opentelemetry-cpp/pull/905)) -* [TESTS] Fix data race in BM_ThreadYieldSpinLockThrashing ([#1099](https://github.com/open-telemetry/opentelemetry-cpp/pull/1099)) -* [EXAMPLE] Otlp gRPC log example ([#1083](https://github.com/open-telemetry/opentelemetry-cpp/pull/1083)) -* [BUILD] C++20 not Building with VS2019 ([#1144](https://github.com/open-telemetry/opentelemetry-cpp/pull/1144)) -* [BUILD] Mark tags to bazel targets([#1075](https://github.com/open-telemetry/opentelemetry-cpp/pull/1075)) +* [SDK] Rename OTEL_CPP_GET_ATTR macro, and define it using fully qualified attr + function + ([#1140](https://github.com/open-telemetry/opentelemetry-cpp/pull/1140)) +* [SDK] Default resource attributes and attributes in OTEL_RESOURCE_ATTRIBUTES + are missing when using Otlp*LogExporter + ([#1082](https://github.com/open-telemetry/opentelemetry-cpp/pull/1082)) +* [METRICS] Add Meter and MeterProvider in the SDK + ([#1078](https://github.com/open-telemetry/opentelemetry-cpp/pull/1078)) +* [EXPORTER] ZipkinExporter shutdown + ([#1153](https://github.com/open-telemetry/opentelemetry-cpp/pull/1153)) +* [EXPORTER] Jaeger exporter shutdown + ([#1150](https://github.com/open-telemetry/opentelemetry-cpp/pull/1150)) +* [EXPORTER] Bugfix: `jaeger::TUDPTransport::write` crash when `getaddrinfo` + returns error + ([#1116](https://github.com/open-telemetry/opentelemetry-cpp/pull/1116)) +* [EXPORTER] Bugfix: Jaeger exporter: extend supported attributes types + ([#1106](https://github.com/open-telemetry/opentelemetry-cpp/pull/1106)) +* [EXPORTER] Fix otlp generates null span ids + ([#1113](https://github.com/open-telemetry/opentelemetry-cpp/pull/1113)) +* [EXPORTER] Jaeger bazel (Linux only) + ([#1077](https://github.com/open-telemetry/opentelemetry-cpp/pull/1077)) +* [DOCS] Add note on DLL support + ([#1137](https://github.com/open-telemetry/opentelemetry-cpp/pull/1137)) +* [DOCS] Improve the instructions for Bazel build + ([#1136](https://github.com/open-telemetry/opentelemetry-cpp/pull/1136)) +* [DOCS] Document dependencies + ([#1119](https://github.com/open-telemetry/opentelemetry-cpp/pull/1119)) +* [DOCS] Dockerfile for quick demo/troubleshooting purpose + ([#905](https://github.com/open-telemetry/opentelemetry-cpp/pull/905)) +* [TESTS] Fix data race in BM_ThreadYieldSpinLockThrashing + ([#1099](https://github.com/open-telemetry/opentelemetry-cpp/pull/1099)) +* [EXAMPLE] Otlp gRPC log example + ([#1083](https://github.com/open-telemetry/opentelemetry-cpp/pull/1083)) +* [BUILD] C++20 not Building with VS2019 + ([#1144](https://github.com/open-telemetry/opentelemetry-cpp/pull/1144)) +* [BUILD] Mark tags to bazel + targets([#1075](https://github.com/open-telemetry/opentelemetry-cpp/pull/1075)) ## [1.1.0] 2021-11-19 -* [BUILD] build release tarball when nlohmann-json not installed ([#1074](https://github.com/open-telemetry/opentelemetry-cpp/pull/1074)) -* [SDK] Bugfix: regex is neither working on GCC 4.9.x ([#1069](https://github.com/open-telemetry/opentelemetry-cpp/pull/1069)) -* [SDK] Improvement: span_id should not break strict aliasing. ([#1068](https://github.com/open-telemetry/opentelemetry-cpp/pull/1068)) -* [EXAMPLE] OTLP HTTP log example ([#1062](https://github.com/open-telemetry/opentelemetry-cpp/pull/1062)) -* [SDK] OTLP gRPC log export should fail after shutdown ([#1064](https://github.com/open-telemetry/opentelemetry-cpp/pull/1064)) -* [BUILD] Building otlp exporter from the release tarball ([#1056](https://github.com/open-telemetry/opentelemetry-cpp/pull/1056)) -* [METRICS] Move old metrics implementation to different directory, and rename targets to \_deprecated ([#1053](https://github.com/open-telemetry/opentelemetry-cpp/pull/1053)) -* [EXPORTER] Add OTLP/gRPC Log Exporter ([#1048](https://github.com/open-telemetry/opentelemetry-cpp/pull/1048)) -* [EXPORTER] Prometheus Exporter ([#1031](https://github.com/open-telemetry/opentelemetry-cpp/pull/1031)) -* [EXPORTER] Add OTLP/HTTP Log Exporter ([#1030](https://github.com/open-telemetry/opentelemetry-cpp/pull/1030)) -* [SDK] fix: issue 368- consistent namespace scope resolution ([#1008](https://github.com/open-telemetry/opentelemetry-cpp/pull/1008)) +* [BUILD] build release tarball when nlohmann-json not installed + ([#1074](https://github.com/open-telemetry/opentelemetry-cpp/pull/1074)) +* [SDK] Bugfix: regex is neither working on GCC 4.9.x + ([#1069](https://github.com/open-telemetry/opentelemetry-cpp/pull/1069)) +* [SDK] Improvement: span_id should not break strict aliasing. + ([#1068](https://github.com/open-telemetry/opentelemetry-cpp/pull/1068)) +* [EXAMPLE] OTLP HTTP log example + ([#1062](https://github.com/open-telemetry/opentelemetry-cpp/pull/1062)) +* [SDK] OTLP gRPC log export should fail after shutdown + ([#1064](https://github.com/open-telemetry/opentelemetry-cpp/pull/1064)) +* [BUILD] Building otlp exporter from the release tarball + ([#1056](https://github.com/open-telemetry/opentelemetry-cpp/pull/1056)) +* [METRICS] Move old metrics implementation to different directory, and rename + targets to \_deprecated + ([#1053](https://github.com/open-telemetry/opentelemetry-cpp/pull/1053)) +* [EXPORTER] Add OTLP/gRPC Log Exporter + ([#1048](https://github.com/open-telemetry/opentelemetry-cpp/pull/1048)) +* [EXPORTER] Prometheus Exporter + ([#1031](https://github.com/open-telemetry/opentelemetry-cpp/pull/1031)) +* [EXPORTER] Add OTLP/HTTP Log Exporter + ([#1030](https://github.com/open-telemetry/opentelemetry-cpp/pull/1030)) +* [SDK] fix: issue 368- consistent namespace scope resolution + ([#1008](https://github.com/open-telemetry/opentelemetry-cpp/pull/1008)) ## [1.0.1] 2021-10-21 -* [EXPORTER] Exports span attributes to ETW ([#1021](https://github.com/open-telemetry/opentelemetry-cpp/pull/1021)) -* [BUILD] cmake: add FindThrift.cmake find module method for thrift ([#1020](https://github.com/open-telemetry/opentelemetry-cpp/pull/1020)) -* [BUILD] Fix nlohmann_json package dependency ([#1017](https://github.com/open-telemetry/opentelemetry-cpp/pull/1017)) -* [EXPORTER] Change OTLP/HTTP default port from 4317 to 4318 ([#1018](https://github.com/open-telemetry/opentelemetry-cpp/pull/1018)) -* [EXPORTER] ETW Log Exporter ([#1006](https://github.com/open-telemetry/opentelemetry-cpp/pull/1006)) -* [API] Adding new Logger:log() method ([#1005](https://github.com/open-telemetry/opentelemetry-cpp/pull/1005)) -* [EXPORTER] Remove scheme from OTLP endpoint before passing to gRPC ([#988](https://github.com/open-telemetry/opentelemetry-cpp/pull/988)) -* [BUILD] Update opentelemetry-proto for bazel build to 0.9.0 ([#984](https://github.com/open-telemetry/opentelemetry-cpp/pull/984)) -* [BUILD] Cross compling grpc_cpp_plugin not found bug ([#982](https://github.com/open-telemetry/opentelemetry-cpp/pull/982)) -* [EXPORTER] Support environment variables for both `OtlpGrpcExporter` and `OtlpHttpExporter` ([#983](https://github.com/open-telemetry/opentelemetry-cpp/pull/983)) -* [API/SDK] Add schema_url support to both Resource and InstrumentationLibrary ([#979](https://github.com/open-telemetry/opentelemetry-cpp/pull/979)) -* [BUILD] Fix build issue where _memcpy_ was not declared in scope ([#985](https://github.com/open-telemetry/opentelemetry-cpp/issues/985)) +* [EXPORTER] Exports span attributes to ETW + ([#1021](https://github.com/open-telemetry/opentelemetry-cpp/pull/1021)) +* [BUILD] cmake: add FindThrift.cmake find module method for thrift + ([#1020](https://github.com/open-telemetry/opentelemetry-cpp/pull/1020)) +* [BUILD] Fix nlohmann_json package dependency + ([#1017](https://github.com/open-telemetry/opentelemetry-cpp/pull/1017)) +* [EXPORTER] Change OTLP/HTTP default port from 4317 to 4318 + ([#1018](https://github.com/open-telemetry/opentelemetry-cpp/pull/1018)) +* [EXPORTER] ETW Log Exporter + ([#1006](https://github.com/open-telemetry/opentelemetry-cpp/pull/1006)) +* [API] Adding new Logger:log() method + ([#1005](https://github.com/open-telemetry/opentelemetry-cpp/pull/1005)) +* [EXPORTER] Remove scheme from OTLP endpoint before passing to gRPC + ([#988](https://github.com/open-telemetry/opentelemetry-cpp/pull/988)) +* [BUILD] Update opentelemetry-proto for bazel build to 0.9.0 + ([#984](https://github.com/open-telemetry/opentelemetry-cpp/pull/984)) +* [BUILD] Cross compling grpc_cpp_plugin not found bug + ([#982](https://github.com/open-telemetry/opentelemetry-cpp/pull/982)) +* [EXPORTER] Support environment variables for both `OtlpGrpcExporter` and + `OtlpHttpExporter` + ([#983](https://github.com/open-telemetry/opentelemetry-cpp/pull/983)) +* [API/SDK] Add schema_url support to both Resource and InstrumentationLibrary + ([#979](https://github.com/open-telemetry/opentelemetry-cpp/pull/979)) +* [BUILD] Fix build issue where _memcpy_ was not declared in scope + ([#985](https://github.com/open-telemetry/opentelemetry-cpp/issues/985)) ## [1.0.0] 2021-09-16 ### API -* Document DefaultSpan, remove DefaultTracer ([#959](https://github.com/open-telemetry/opentelemetry-cpp/pull/959)) -* Separate baggage<->Context api from Baggage Propagator ([#963](https://github.com/open-telemetry/opentelemetry-cpp/pull/963)) -* Remove unused public API to_span_ptr ([#964](https://github.com/open-telemetry/opentelemetry-cpp/pull/964)) -* :collision: Make span context management public ([#967](https://github.com/open-telemetry/opentelemetry-cpp/pull/967)) -* Support determining parent span from Context while creating new Span ([#969](https://github.com/open-telemetry/opentelemetry-cpp/pull/969)) -* :collision: Traces: Add note on experimental semantic convention implementation, prefix semantics headers with experimental tag ([#970](https://github.com/open-telemetry/opentelemetry-cpp/pull/970)) -* Increment OPENTELEMETRY_ABI_VERSION_NO to 1 ([#980](https://github.com/open-telemetry/opentelemetry-cpp/pull/980)) +* Document DefaultSpan, remove DefaultTracer + ([#959](https://github.com/open-telemetry/opentelemetry-cpp/pull/959)) +* Separate baggage<->Context api from Baggage Propagator + ([#963](https://github.com/open-telemetry/opentelemetry-cpp/pull/963)) +* Remove unused public API to_span_ptr + ([#964](https://github.com/open-telemetry/opentelemetry-cpp/pull/964)) +* :collision: Make span context management public + ([#967](https://github.com/open-telemetry/opentelemetry-cpp/pull/967)) +* Support determining parent span from Context while creating new Span + ([#969](https://github.com/open-telemetry/opentelemetry-cpp/pull/969)) +* :collision: Traces: Add note on experimental semantic convention + implementation, prefix semantics headers with experimental tag + ([#970](https://github.com/open-telemetry/opentelemetry-cpp/pull/970)) +* Increment OPENTELEMETRY_ABI_VERSION_NO to 1 + ([#980](https://github.com/open-telemetry/opentelemetry-cpp/pull/980)) ### SDK -* Clean up `GetEnvironmentVariable` and remove unused variable under `NO_GETENV` ([#976](https://github.com/open-telemetry/opentelemetry-cpp/pull/976)) -* :collision: Resources: Add note on experimental semantic convention implementation, prefix semantics headers with experimental tag ([#970](https://github.com/open-telemetry/opentelemetry-cpp/pull/970)) +* Clean up `GetEnvironmentVariable` and remove unused variable under `NO_GETENV` + ([#976](https://github.com/open-telemetry/opentelemetry-cpp/pull/976)) +* :collision: Resources: Add note on experimental semantic convention + implementation, prefix semantics headers with experimental tag + ([#970](https://github.com/open-telemetry/opentelemetry-cpp/pull/970)) ### OTLP Exporter -* :bug: Ignore status description if status code is not Error ([#962](https://github.com/open-telemetry/opentelemetry-cpp/pull/962)) -* :collision: Make Otlp exporter configuration environment variables specs-compliant ([#974](https://github.com/open-telemetry/opentelemetry-cpp/pull/974)) +* :bug: Ignore status description if status code is not Error + ([#962](https://github.com/open-telemetry/opentelemetry-cpp/pull/962)) +* :collision: Make Otlp exporter configuration environment variables + specs-compliant + ([#974](https://github.com/open-telemetry/opentelemetry-cpp/pull/974)) ### Zipkin Exporter -* :bug: Don't set parentId in case parentId is empty ([#943](https://github.com/open-telemetry/opentelemetry-cpp/pull/943)) -* :rocket: Extend zipkin exporter with ability to provide headers ([#951](https://github.com/open-telemetry/opentelemetry-cpp/pull/951)) +* :bug: Don't set parentId in case parentId is empty + ([#943](https://github.com/open-telemetry/opentelemetry-cpp/pull/943)) +* :rocket: Extend zipkin exporter with ability to provide headers + ([#951](https://github.com/open-telemetry/opentelemetry-cpp/pull/951)) ### DOCS -* :book: Add getting-started documentation for SDK: ([#942](https://github.com/open-telemetry/opentelemetry-cpp/pull/942)) -* :book: Remove unnecessary spaces and spelling of gRPC in README ([#965](https://github.com/open-telemetry/opentelemetry-cpp/pull/965)) +* :book: Add getting-started documentation for SDK: + ([#942](https://github.com/open-telemetry/opentelemetry-cpp/pull/942)) +* :book: Remove unnecessary spaces and spelling of gRPC in README + ([#965](https://github.com/open-telemetry/opentelemetry-cpp/pull/965)) ### BUILD -* Disable bazel build for gcc 4.8, upgrade versions for grpc(v1.39.1) and bazel(4.2.0), document bazel support ([#953](https://github.com/open-telemetry/opentelemetry-cpp/pull/953)) -* Move CMake config template to cmake folder ([#958](https://github.com/open-telemetry/opentelemetry-cpp/pull/958)) -* Enable CMake to search the new package variable `_ROOT` ([#975](https://github.com/open-telemetry/opentelemetry-cpp/pull/975)) -* :bug: Do not override CMAKE_CXX_STANDARD ([#977](https://github.com/open-telemetry/opentelemetry-cpp/pull/977)) +* Disable bazel build for gcc 4.8, upgrade versions for grpc(v1.39.1) and + bazel(4.2.0), document bazel support + ([#953](https://github.com/open-telemetry/opentelemetry-cpp/pull/953)) +* Move CMake config template to cmake folder + ([#958](https://github.com/open-telemetry/opentelemetry-cpp/pull/958)) +* Enable CMake to search the new package variable `_ROOT` + ([#975](https://github.com/open-telemetry/opentelemetry-cpp/pull/975)) +* :bug: Do not override CMAKE_CXX_STANDARD + ([#977](https://github.com/open-telemetry/opentelemetry-cpp/pull/977)) ### :construction: Experiemental Features (Will change in future) -* Semantic Conventions for traces - As the specs is still experimental, the implementation will change in future. -* Semantic Convention for resource - As the specs is still experimental, the implementation will change in future. -* Logs and Metrics API & SDK - These are not compliant, and are behind feature flag. Not recommended to use for now. +* Semantic Conventions for traces - As the specs is still experimental, the + implementation will change in future. +* Semantic Convention for resource - As the specs is still experimental, the + implementation will change in future. +* Logs and Metrics API & SDK - These are not compliant, and are behind feature + flag. Not recommended to use for now. ## [1.0.0-rc4] 2021-08-04 -* [EXPORTER] `BREAKING CHANGE` Fix default HTTP port for OTLP HTTP Exporter ([#939](https://github.com/open-telemetry/opentelemetry-cpp/pull/939)) -* [API] Fix timeout calculation for Tracer::Flush() and Tracer::Close() ([#937](https://github.com/open-telemetry/opentelemetry-cpp/pull/937)) -* [API] Fix for Stack::Resize that new_capacity is not assigned to capacity_ ([#934](https://github.com/open-telemetry/opentelemetry-cpp/pull/934)) -* [SDK] Fix race condition in circular buffer simulation test ([#931](https://github.com/open-telemetry/opentelemetry-cpp/pull/931)) -* [EXPORTER] Fix error logging in Jaeger Exporter ([#930](https://github.com/open-telemetry/opentelemetry-cpp/pull/930)) -* [BUILD] Use latest grpc version (v1.39.0) for cmake build of otlp exporter ([#927](https://github.com/open-telemetry/opentelemetry-cpp/pull/927)) -* [EXPORTER] Add Jaeger Thrift HTTP exporter ([#926](https://github.com/open-telemetry/opentelemetry-cpp/pull/926)) -* [SDK] Move env-var read logic to common dir, and optional reading of env-var ([#924](https://github.com/open-telemetry/opentelemetry-cpp/pull/924)) -* [EXPORTER] Remove recordable header from CMake install rules for exporters ([#923](https://github.com/open-telemetry/opentelemetry-cpp/pull/923)) -* [EXPORTER] `BREAKING CHANGE` Rename Recordable to JaegerRecordable in Jaeger exporter ([#919](https://github.com/open-telemetry/opentelemetry-cpp/pull/919)) -* [EXPORTER] `BREAKING CHANGE` Rename Jaeger exporter target ([#918](https://github.com/open-telemetry/opentelemetry-cpp/pull/918)) -* [EXPORTER] Add Zipkin exporter example ([#917](https://github.com/open-telemetry/opentelemetry-cpp/pull/917)) -* [EXPORTER] Bazel build for Zipkin exorter ([#916](https://github.com/open-telemetry/opentelemetry-cpp/pull/916)) -* [BUILD] Allow to use local GSL ([#915](https://github.com/open-telemetry/opentelemetry-cpp/pull/915)) -* [DOCS] Document vcpkg toolchain configuration ([#913](https://github.com/open-telemetry/opentelemetry-cpp/pull/913)) -* [SDK] Fix for resource deletion after tracer provider shutdown ([#911](https://github.com/open-telemetry/opentelemetry-cpp/pull/911)) -* [BUILD] Add bazel build for grpc example ([#910](https://github.com/open-telemetry/opentelemetry-cpp/pull/910)) -* [EXPORTER] Add resource and instrumentation library support for OStreamSpanExporter ([#906](https://github.com/open-telemetry/opentelemetry-cpp/pull/906)) -* [API] Adding semantic-convention attributes for trace ([#868](https://github.com/open-telemetry/opentelemetry-cpp/pull/868)) +* [EXPORTER] `BREAKING CHANGE` Fix default HTTP port for OTLP HTTP Exporter + ([#939](https://github.com/open-telemetry/opentelemetry-cpp/pull/939)) +* [API] Fix timeout calculation for Tracer::Flush() and Tracer::Close() + ([#937](https://github.com/open-telemetry/opentelemetry-cpp/pull/937)) +* [API] Fix for Stack::Resize that new_capacity is not assigned to capacity_ + ([#934](https://github.com/open-telemetry/opentelemetry-cpp/pull/934)) +* [SDK] Fix race condition in circular buffer simulation test + ([#931](https://github.com/open-telemetry/opentelemetry-cpp/pull/931)) +* [EXPORTER] Fix error logging in Jaeger Exporter + ([#930](https://github.com/open-telemetry/opentelemetry-cpp/pull/930)) +* [BUILD] Use latest grpc version (v1.39.0) for cmake build of otlp exporter + ([#927](https://github.com/open-telemetry/opentelemetry-cpp/pull/927)) +* [EXPORTER] Add Jaeger Thrift HTTP exporter + ([#926](https://github.com/open-telemetry/opentelemetry-cpp/pull/926)) +* [SDK] Move env-var read logic to common dir, and optional reading of env-var + ([#924](https://github.com/open-telemetry/opentelemetry-cpp/pull/924)) +* [EXPORTER] Remove recordable header from CMake install rules for exporters + ([#923](https://github.com/open-telemetry/opentelemetry-cpp/pull/923)) +* [EXPORTER] `BREAKING CHANGE` Rename Recordable to JaegerRecordable in Jaeger + exporter + ([#919](https://github.com/open-telemetry/opentelemetry-cpp/pull/919)) +* [EXPORTER] `BREAKING CHANGE` Rename Jaeger exporter target + ([#918](https://github.com/open-telemetry/opentelemetry-cpp/pull/918)) +* [EXPORTER] Add Zipkin exporter example + ([#917](https://github.com/open-telemetry/opentelemetry-cpp/pull/917)) +* [EXPORTER] Bazel build for Zipkin exorter + ([#916](https://github.com/open-telemetry/opentelemetry-cpp/pull/916)) +* [BUILD] Allow to use local GSL + ([#915](https://github.com/open-telemetry/opentelemetry-cpp/pull/915)) +* [DOCS] Document vcpkg toolchain configuration + ([#913](https://github.com/open-telemetry/opentelemetry-cpp/pull/913)) +* [SDK] Fix for resource deletion after tracer provider shutdown + ([#911](https://github.com/open-telemetry/opentelemetry-cpp/pull/911)) +* [BUILD] Add bazel build for grpc example + ([#910](https://github.com/open-telemetry/opentelemetry-cpp/pull/910)) +* [EXPORTER] Add resource and instrumentation library support for + OStreamSpanExporter + ([#906](https://github.com/open-telemetry/opentelemetry-cpp/pull/906)) +* [API] Adding semantic-convention attributes for trace + ([#868](https://github.com/open-telemetry/opentelemetry-cpp/pull/868)) ## [1.0.0-rc3] 2021-07-12 -* [DOCS] Add doxygen reference docs for SDK ([#902](https://github.com/open-telemetry/opentelemetry-cpp/pull/902)) -* [EXPORTER] Jaeger Exporter - Populate resource attributes into process tags in Jaeger ([#897](https://github.com/open-telemetry/opentelemetry-cpp/pull/897)) -* [EXPORTER] Zipkin Exporter - Report Event timestamp into microseconds ([#896](https://github.com/open-telemetry/opentelemetry-cpp/pull/896)) -* [EXPORTER] Jaeger Exporter - Handle span events ([#895](https://github.com/open-telemetry/opentelemetry-cpp/pull/895)) -* [DOCS] Fix API docs for Scope object ([#894](https://github.com/open-telemetry/opentelemetry-cpp/pull/894)) -* [BUILD] Fix Linking error for libcurl on some macOS environments ([#893](https://github.com/open-telemetry/opentelemetry-cpp/pull/893)) -* [API] Context cleanup from Runtime Storage ([#885](https://github.com/open-telemetry/opentelemetry-cpp/pull/885)) -* [DOCS] Document strategy to avoid conflict between two different versions of Abseil ([#883](https://github.com/open-telemetry/opentelemetry-cpp/pull/883/)) -* [EXPORTER] ETW Exporter - Document example for ETW Exporter ([#882](https://github.com/open-telemetry/opentelemetry-cpp/pull/882)) -* [SDK] Create Span with Valid spanId and traceId irrespective of Sampling decision ([#879](https://github.com/open-telemetry/opentelemetry-cpp/pull/879)) -* [EXPORTER] Jaeger Exporter - Rename bswap macros to avoid clash on some systems ([#876](https://github.com/open-telemetry/opentelemetry-cpp/pull/876)) -* [API] Add Semantics Conventions attributes for Resources ([#872](https://github.com/open-telemetry/opentelemetry-cpp/pull/872)) -* [BUILD] Use nlohmann-json from submodules if not already installed ([#870](https://github.com/open-telemetry/opentelemetry-cpp/pull/870)) +* [DOCS] Add doxygen reference docs for SDK + ([#902](https://github.com/open-telemetry/opentelemetry-cpp/pull/902)) +* [EXPORTER] Jaeger Exporter - Populate resource attributes into process tags in + Jaeger ([#897](https://github.com/open-telemetry/opentelemetry-cpp/pull/897)) +* [EXPORTER] Zipkin Exporter - Report Event timestamp into microseconds + ([#896](https://github.com/open-telemetry/opentelemetry-cpp/pull/896)) +* [EXPORTER] Jaeger Exporter - Handle span events + ([#895](https://github.com/open-telemetry/opentelemetry-cpp/pull/895)) +* [DOCS] Fix API docs for Scope object + ([#894](https://github.com/open-telemetry/opentelemetry-cpp/pull/894)) +* [BUILD] Fix Linking error for libcurl on some macOS environments + ([#893](https://github.com/open-telemetry/opentelemetry-cpp/pull/893)) +* [API] Context cleanup from Runtime Storage + ([#885](https://github.com/open-telemetry/opentelemetry-cpp/pull/885)) +* [DOCS] Document strategy to avoid conflict between two different versions of + Abseil ([#883](https://github.com/open-telemetry/opentelemetry-cpp/pull/883/)) +* [EXPORTER] ETW Exporter - Document example for ETW Exporter + ([#882](https://github.com/open-telemetry/opentelemetry-cpp/pull/882)) +* [SDK] Create Span with Valid spanId and traceId irrespective of Sampling + decision + ([#879](https://github.com/open-telemetry/opentelemetry-cpp/pull/879)) +* [EXPORTER] Jaeger Exporter - Rename bswap macros to avoid clash on some + systems ([#876](https://github.com/open-telemetry/opentelemetry-cpp/pull/876)) +* [API] Add Semantics Conventions attributes for Resources + ([#872](https://github.com/open-telemetry/opentelemetry-cpp/pull/872)) +* [BUILD] Use nlohmann-json from submodules if not already installed + ([#870](https://github.com/open-telemetry/opentelemetry-cpp/pull/870)) ## [1.0.0-rc2] 2021-06-18 -* [EXPORTER] Jaeger Exporter - Support for Instrumentation Library ([#864](https://github.com/open-telemetry/opentelemetry-cpp/pull/864)) -* [TESTS] Adding benchmark tests for baggage api ([#861](https://github.com/open-telemetry/opentelemetry-cpp/pull/861)) -* [BUILD] Fix for GCC9/C++20 Support for using STL for modern C++ features ([#860](https://github.com/open-telemetry/opentelemetry-cpp/pull/860)) -* [TESTS] Adding benchmark tests for span create api ([#856](https://github.com/open-telemetry/opentelemetry-cpp/pull/856)) -* [BUILD] Fix for using Abseil library for modern C++ features ([#850](https://github.com/open-telemetry/opentelemetry-cpp/pull/850)) -* [BUILD] Fix issues with win32/x86 compilation ([#847](https://github.com/open-telemetry/opentelemetry-cpp/pull/847)) -* [DOCS] Document OSS dependencies and their licenses ([#844](https://github.com/open-telemetry/opentelemetry-cpp/pull/844)) -* [BUILD] Various fixes to build with Visual Studio 2015 ([#840](https://github.com/open-telemetry/opentelemetry-cpp/pull/840)) -* [INSTRUMENTATION] HTTPClient: Change support for full URL argument ([#833](https://github.com/open-telemetry/opentelemetry-cpp/pull/833)) -* [EXPORTER] Jaeger Exporter - fix endianness of Jaeger IDs for transmission ([#832](https://github.com/open-telemetry/opentelemetry-cpp/pull/832)) -* [INSTRUMENTATION] fix protobuf compilation warning in gRPC example ([#830](https://github.com/open-telemetry/opentelemetry-cpp/pull/830)) -* [EXPORTER] `BREAKING CHANGE` - Add OTLP/HTTP+JSON Protocol exporter; Rename `OtlpExporter` to `OtlpGrpcExporter` ([#810](https://github.com/open-telemetry/opentelemetry-cpp/pull/810)) +* [EXPORTER] Jaeger Exporter - Support for Instrumentation Library + ([#864](https://github.com/open-telemetry/opentelemetry-cpp/pull/864)) +* [TESTS] Adding benchmark tests for baggage api + ([#861](https://github.com/open-telemetry/opentelemetry-cpp/pull/861)) +* [BUILD] Fix for GCC9/C++20 Support for using STL for modern C++ features + ([#860](https://github.com/open-telemetry/opentelemetry-cpp/pull/860)) +* [TESTS] Adding benchmark tests for span create api + ([#856](https://github.com/open-telemetry/opentelemetry-cpp/pull/856)) +* [BUILD] Fix for using Abseil library for modern C++ features + ([#850](https://github.com/open-telemetry/opentelemetry-cpp/pull/850)) +* [BUILD] Fix issues with win32/x86 compilation + ([#847](https://github.com/open-telemetry/opentelemetry-cpp/pull/847)) +* [DOCS] Document OSS dependencies and their licenses + ([#844](https://github.com/open-telemetry/opentelemetry-cpp/pull/844)) +* [BUILD] Various fixes to build with Visual Studio 2015 + ([#840](https://github.com/open-telemetry/opentelemetry-cpp/pull/840)) +* [INSTRUMENTATION] HTTPClient: Change support for full URL argument + ([#833](https://github.com/open-telemetry/opentelemetry-cpp/pull/833)) +* [EXPORTER] Jaeger Exporter - fix endianness of Jaeger IDs for transmission + ([#832](https://github.com/open-telemetry/opentelemetry-cpp/pull/832)) +* [INSTRUMENTATION] fix protobuf compilation warning in gRPC example + ([#830](https://github.com/open-telemetry/opentelemetry-cpp/pull/830)) +* [EXPORTER] `BREAKING CHANGE` - Add OTLP/HTTP+JSON Protocol exporter; Rename + `OtlpExporter` to `OtlpGrpcExporter` + ([#810](https://github.com/open-telemetry/opentelemetry-cpp/pull/810)) ## [1.0.0-rc1] 2021-06-04 -* [BUILD] Enable Jaeger exporter build in Windows ([#815](https://github.com/open-telemetry/opentelemetry-cpp/pull/815)) -* [DOCS] Versioning doc update to clarify release and versioning policy ([#811](https://github.com/open-telemetry/opentelemetry-cpp/pull/811)) -* [LOGS] Move Logging implementation under feature-flag ([#807](https://github.com/open-telemetry/opentelemetry-cpp/pull/807)) -* [BUILD] Filter metric headers files from `opentelemetry-api` and `opentelemetry-sdk` targets if metrics feature-flag is disabled ([#806](https://github.com/open-telemetry/opentelemetry-cpp/pull/806)) -* [BUILD] Fix install rule for ostream exporter, Jaeger, ETW, ElasticSearch ([#805](Fix install rule for header files of ostream exporter)) -* [API/SDK] Switch from mpark::variant to absl::variant as default ([#771](https://github.com/open-telemetry/opentelemetry-cpp/pull/771)) -* [API/SDK] Support `const char *` as acceptable data type for attributes and resources ([#771](https://github.com/open-telemetry/opentelemetry-cpp/pull/771)) -* [EXAMPLE] gRPC instrumentation example with context propagation ([#729](https://github.com/open-telemetry/opentelemetry-cpp/pull/729)) +* [BUILD] Enable Jaeger exporter build in Windows + ([#815](https://github.com/open-telemetry/opentelemetry-cpp/pull/815)) +* [DOCS] Versioning doc update to clarify release and versioning policy + ([#811](https://github.com/open-telemetry/opentelemetry-cpp/pull/811)) +* [LOGS] Move Logging implementation under feature-flag + ([#807](https://github.com/open-telemetry/opentelemetry-cpp/pull/807)) +* [BUILD] Filter metric headers files from `opentelemetry-api` and + `opentelemetry-sdk` targets if metrics feature-flag is disabled + ([#806](https://github.com/open-telemetry/opentelemetry-cpp/pull/806)) +* [BUILD] Fix install rule for ostream exporter, Jaeger, ETW, ElasticSearch + ([#805](Fix install rule for header files of ostream exporter)) +* [API/SDK] Switch from mpark::variant to absl::variant as default + ([#771](https://github.com/open-telemetry/opentelemetry-cpp/pull/771)) +* [API/SDK] Support `const char *` as acceptable data type for attributes and + resources + ([#771](https://github.com/open-telemetry/opentelemetry-cpp/pull/771)) +* [EXAMPLE] gRPC instrumentation example with context propagation + ([#729](https://github.com/open-telemetry/opentelemetry-cpp/pull/729)) ## [0.7.0] 2021-05-26 -* [METRICS] Move metrics api/sdk under preview feature flag ([#745](https://github.com/open-telemetry/opentelemetry-cpp/pull/745)) -* [DOCS] Add instructions to build using Bazel ([#747](https://github.com/open-telemetry/opentelemetry-cpp/pull/747)) -* [DOCS] Update copyright headers ([#754](https://github.com/open-telemetry/opentelemetry-cpp/pull/754)) -* [EXPORTER] Populate resource to OTLP proto data ([#758](https://github.com/open-telemetry/opentelemetry-cpp/pull/758)) -* [CI] Add CodeQL security scan CI workflow ([#770](https://github.com/open-telemetry/opentelemetry-cpp/pull/770)) -* [BUILD] Enable building API only CMake Project ([#778](https://github.com/open-telemetry/opentelemetry-cpp/pull/778)) -* [SDK] Fix for sampling of root span ([#784](https://github.com/open-telemetry/opentelemetry-cpp/pull/784)) -* [CI] Add Jaeger exporter to CMake CI build ([#786](https://github.com/open-telemetry/opentelemetry-cpp/pull/786)) -* [API] `BREAKING CHANGE` - Tracer::WithActiveSpan() to return Scope object intead of unique_ptr ([#788](https://github.com/open-telemetry/opentelemetry-cpp/pull/788)) -* [DOCS] Add docs for nested spans and context propagation in readthedocs ([#792](https://github.com/open-telemetry/opentelemetry-cpp/pull/792)) -* [CI] Output verbose error for failed unit-test in CI ([#796](https://github.com/open-telemetry/opentelemetry-cpp/pull/796)) +* [METRICS] Move metrics api/sdk under preview feature flag + ([#745](https://github.com/open-telemetry/opentelemetry-cpp/pull/745)) +* [DOCS] Add instructions to build using Bazel + ([#747](https://github.com/open-telemetry/opentelemetry-cpp/pull/747)) +* [DOCS] Update copyright headers + ([#754](https://github.com/open-telemetry/opentelemetry-cpp/pull/754)) +* [EXPORTER] Populate resource to OTLP proto data + ([#758](https://github.com/open-telemetry/opentelemetry-cpp/pull/758)) +* [CI] Add CodeQL security scan CI workflow + ([#770](https://github.com/open-telemetry/opentelemetry-cpp/pull/770)) +* [BUILD] Enable building API only CMake Project + ([#778](https://github.com/open-telemetry/opentelemetry-cpp/pull/778)) +* [SDK] Fix for sampling of root span + ([#784](https://github.com/open-telemetry/opentelemetry-cpp/pull/784)) +* [CI] Add Jaeger exporter to CMake CI build + ([#786](https://github.com/open-telemetry/opentelemetry-cpp/pull/786)) +* [API] `BREAKING CHANGE` - Tracer::WithActiveSpan() to return Scope object + intead of unique_ptr + ([#788](https://github.com/open-telemetry/opentelemetry-cpp/pull/788)) +* [DOCS] Add docs for nested spans and context propagation in readthedocs + ([#792](https://github.com/open-telemetry/opentelemetry-cpp/pull/792)) +* [CI] Output verbose error for failed unit-test in CI + ([#796](https://github.com/open-telemetry/opentelemetry-cpp/pull/796)) ## [0.6.0] 2021-05-11 -* [EXPORTER] Add Jaeger exporter ([#534](https://github.com/open-telemetry/opentelemetry-cpp/pull/534)) -* [SDK] Support multiple processors ([#692](https://github.com/open-telemetry/opentelemetry-cpp/pull/692)) -* [SDK] Add instrumentation library and multiple tracer support ([#693](https://github.com/open-telemetry/opentelemetry-cpp/pull/693)) -* [SDK] Resource integration with Exporters ([#706](https://github.com/open-telemetry/opentelemetry-cpp/pull/706)) -* [EXAMPLE] Enhance existing http example with propagation ([#727](https://github.com/open-telemetry/opentelemetry-cpp/pull/727)) +* [EXPORTER] Add Jaeger exporter + ([#534](https://github.com/open-telemetry/opentelemetry-cpp/pull/534)) +* [SDK] Support multiple processors + ([#692](https://github.com/open-telemetry/opentelemetry-cpp/pull/692)) +* [SDK] Add instrumentation library and multiple tracer support + ([#693](https://github.com/open-telemetry/opentelemetry-cpp/pull/693)) +* [SDK] Resource integration with Exporters + ([#706](https://github.com/open-telemetry/opentelemetry-cpp/pull/706)) +* [EXAMPLE] Enhance existing http example with propagation + ([#727](https://github.com/open-telemetry/opentelemetry-cpp/pull/727)) ## [0.5.0] 2021-04-26 -* [SDK] Support custom span-id and trace-id generator ([#681](https://github.com/open-telemetry/opentelemetry-cpp/pull/681)) -* [SDK] Add SpanContext (and TraceState) to Recordable ([#667](https://github.com/open-telemetry/opentelemetry-cpp/pull/667)) -* [SDK] Global Propagator ([#668](https://github.com/open-telemetry/opentelemetry-cpp/pull/668)) -* [SDK] Create SharedContext for updating span pipeline ([#650](https://github.com/open-telemetry/opentelemetry-cpp/pull/650)) -* [API] Baggage implementation ([#676](https://github.com/open-telemetry/opentelemetry-cpp/pull/676)) -* [API] Move class from opentelemetry::core namespace to opentelemetry::common namespace ([#686](https://github.com/open-telemetry/opentelemetry-cpp/pull/686)) +* [SDK] Support custom span-id and trace-id generator + ([#681](https://github.com/open-telemetry/opentelemetry-cpp/pull/681)) +* [SDK] Add SpanContext (and TraceState) to Recordable + ([#667](https://github.com/open-telemetry/opentelemetry-cpp/pull/667)) +* [SDK] Global Propagator + ([#668](https://github.com/open-telemetry/opentelemetry-cpp/pull/668)) +* [SDK] Create SharedContext for updating span pipeline + ([#650](https://github.com/open-telemetry/opentelemetry-cpp/pull/650)) +* [API] Baggage implementation + ([#676](https://github.com/open-telemetry/opentelemetry-cpp/pull/676)) +* [API] Move class from opentelemetry::core namespace to opentelemetry::common + namespace + ([#686](https://github.com/open-telemetry/opentelemetry-cpp/pull/686)) ## [0.4.0] 2021-04-12 -* [EXPORTER] ETW Exporter enhancements ([#519](https://github.com/open-telemetry/opentelemetry-cpp/pull/519)) -* [EXPORTER] Read Zipkin endpoint from environment variable. ([#624](https://github.com/open-telemetry/opentelemetry-cpp/pull/624)) -* [EXPORTER] Split Zpages webserver hosting from Exporter ([#626](https://github.com/open-telemetry/opentelemetry-cpp/pull/626)) -* [EXPORTER] ETW Exporter Usage Instructions ([#628](https://github.com/open-telemetry/opentelemetry-cpp/pull/628)) -* [INSTRUMENTATION] HTTP Client/Server Instrumentation example ([#632](https://github.com/open-telemetry/opentelemetry-cpp/pull/632)) -* [EXPORTER] Enable tls authentication for otlp grpc exporter ([#635](Enable tls authentication for otlp grpc exporter)) -* [API] Refactoring trace_state to reuse common functionality in baggage ([#638](https://github.com/open-telemetry/opentelemetry-cpp/pull/638/files)) +* [EXPORTER] ETW Exporter enhancements + ([#519](https://github.com/open-telemetry/opentelemetry-cpp/pull/519)) +* [EXPORTER] Read Zipkin endpoint from environment variable. + ([#624](https://github.com/open-telemetry/opentelemetry-cpp/pull/624)) +* [EXPORTER] Split Zpages webserver hosting from Exporter + ([#626](https://github.com/open-telemetry/opentelemetry-cpp/pull/626)) +* [EXPORTER] ETW Exporter Usage Instructions + ([#628](https://github.com/open-telemetry/opentelemetry-cpp/pull/628)) +* [INSTRUMENTATION] HTTP Client/Server Instrumentation example + ([#632](https://github.com/open-telemetry/opentelemetry-cpp/pull/632)) +* [EXPORTER] Enable tls authentication for otlp grpc exporter ([#635](Enable tls + authentication for otlp grpc exporter)) +* [API] Refactoring trace_state to reuse common functionality in baggage + ([#638](https://github.com/open-telemetry/opentelemetry-cpp/pull/638/files)) ## [0.3.0] 2021-03-19 -* [EXPORTER] Added Zipkin Exporter. ([#471](https://github.com/open-telemetry/opentelemetry-cpp/pull/471)) -* [API] Added Jaeger propagator. ([#599](https://github.com/open-telemetry/opentelemetry-cpp/pull/599)) -* [PROPAGATOR] Added Composite Propagator ([#597](https://github.com/open-telemetry/opentelemetry-cpp/pull/597)) -* [API] Propagate traceflag from parent ([#603](https://github.com/open-telemetry/opentelemetry-cpp/pull/603)) -* [DOCS] Add sphinx support for api doc generation ([595](https://github.com/open-telemetry/opentelemetry-cpp/pull/595)) -* [SDK] Add service.name if missing in Resource ([#616](https://github.com/open-telemetry/opentelemetry-cpp/pull/616)) +* [EXPORTER] Added Zipkin Exporter. + ([#471](https://github.com/open-telemetry/opentelemetry-cpp/pull/471)) +* [API] Added Jaeger propagator. + ([#599](https://github.com/open-telemetry/opentelemetry-cpp/pull/599)) +* [PROPAGATOR] Added Composite Propagator + ([#597](https://github.com/open-telemetry/opentelemetry-cpp/pull/597)) +* [API] Propagate traceflag from parent + ([#603](https://github.com/open-telemetry/opentelemetry-cpp/pull/603)) +* [DOCS] Add sphinx support for api doc generation + ([595](https://github.com/open-telemetry/opentelemetry-cpp/pull/595)) +* [SDK] Add service.name if missing in Resource + ([#616](https://github.com/open-telemetry/opentelemetry-cpp/pull/616)) ## [0.2.0] 2021-03-02 -* [SDK] Added `ForceFlush` to `TracerProvider`. ([#588](https://github.com/open-telemetry/opentelemetry-cpp/pull/588)). -* [SDK] Added Resource API. ([#502](https://github.com/open-telemetry/opentelemetry-cpp/pull/502)) +* [SDK] Added `ForceFlush` to `TracerProvider`. + ([#588](https://github.com/open-telemetry/opentelemetry-cpp/pull/588)). +* [SDK] Added Resource API. + ([#502](https://github.com/open-telemetry/opentelemetry-cpp/pull/502)) * [API] Modified TraceState support for w3c trace context as per specs. -* [SDK] TraceState implementation as per spec ([#551](https://github.com/open-telemetry/opentelemetry-cpp/pull/551)) -* [API] Added B3 Propagator. ([#523](https://github.com/open-telemetry/opentelemetry-cpp/pull/523)) -* [Exporter] Added ETW Exporter. ([#376](https://github.com/open-telemetry/opentelemetry-cpp/pull/376)) -* [CI] Enable cache for Bazel for faster builds. ([#505](https://github.com/open-telemetry/opentelemetry-cpp/pull/505)) +* [SDK] TraceState implementation as per spec + ([#551](https://github.com/open-telemetry/opentelemetry-cpp/pull/551)) +* [API] Added B3 Propagator. + ([#523](https://github.com/open-telemetry/opentelemetry-cpp/pull/523)) +* [Exporter] Added ETW Exporter. + ([#376](https://github.com/open-telemetry/opentelemetry-cpp/pull/376)) +* [CI] Enable cache for Bazel for faster builds. + ([#505](https://github.com/open-telemetry/opentelemetry-cpp/pull/505)) ## [0.0.1] 2020-12-16 diff --git a/INSTALL.md b/INSTALL.md index 5520112b3f..69934fde46 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -5,7 +5,10 @@ build systems for opentelemetry-cpp. ## Dependencies -You can link OpenTelemetry C++ SDK with libraries provided in [dependencies.md](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/docs/dependencies.md) (complete list of libraries with versions used in our CI can be found [here](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release)). +You can link OpenTelemetry C++ SDK with libraries provided in +[dependencies.md](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/docs/dependencies.md) +(complete list of libraries with versions used in our CI can be found +[here](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release)). ## Build instructions using CMake @@ -23,14 +26,17 @@ You can link OpenTelemetry C++ SDK with libraries provided in [dependencies.md]( unittests. We use CMake version 3.15.2 in our build system. To install CMake, consult the [Installing CMake](https://cmake.org/install/) guide. - [GoogleTest](https://github.com/google/googletest) framework to build and run - the unittests. Refer to [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L5) - for version of GoogleTest used in CI. To - install GoogleTest, consult the [GoogleTest Build + the unittests. Refer to + [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L5) + for version of GoogleTest used in CI. To install GoogleTest, consult the + [GoogleTest Build Instructions](https://github.com/google/googletest/blob/master/googletest/README.md#generic-build-instructions). -- [Google Benchmark](https://github.com/google/benchmark) framework to build and run - benchmark tests. Refer to [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L4) - for version of Benchmark used in CI. To install Benchmark, - consult the [GoogleBenchmark Build Instructions](https://github.com/google/benchmark#installation). +- [Google Benchmark](https://github.com/google/benchmark) framework to build and + run benchmark tests. Refer to + [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L4) + for version of Benchmark used in CI. To install Benchmark, consult the + [GoogleBenchmark Build + Instructions](https://github.com/google/benchmark#installation). - Apart from above core requirements, the Exporters and Propagators have their build dependencies which are not covered here. E.g, Otlp Exporter needs grpc/protobuf library, Zipkin exporter needs nlohmann-json and libcurl, ETW @@ -75,9 +81,9 @@ You can link OpenTelemetry C++ SDK with libraries provided in [dependencies.md]( configuration, the code is compiled without `-fpic` option, so it is not suitable for inclusion in shared libraries. To enable the code for inclusion in shared libraries, this variable is used. - - `-DBUILD_SHARED_LIBS=ON` : To build shared libraries for the targets. Please - refer to note [below](#building-shared-libs-for-windows) for Windows DLL - support + - `-DBUILD_SHARED_LIBS=ON` : To build shared libraries for the targets. + Please refer to note [below](#building-shared-libs-for-windows) for + Windows DLL support - `-DWITH_OTLP=ON` : To enable building Otlp exporter. - `-DWITH_PROMETHEUS=ON` : To enable building prometheus exporter. @@ -145,23 +151,25 @@ target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES}) ## Build instructions using Bazel NOTE: Experimental, and not supported for all the components. Make sure the -[GoogleTest](https://github.com/google/googletest) installation may fail if there is a different version of googletest already installed in system-defined path. +[GoogleTest](https://github.com/google/googletest) installation may fail if +there is a different version of googletest already installed in system-defined +path. ### Prerequisites for Bazel -- A supported platform (e.g. Windows, macOS or Linux). -Refer to [Platforms Supported](./README.md#supported-development-platforms) -for more information. -- A compatible C++ compiler supporting at least C++11. -Major compilers are supported. -Refer to [Supported Compilers](./README.md#supported-c-versions) for more information. -- [Git](https://git-scm.com/) for fetching opentelemetry-cpp source code from repository. -To install Git, consult the [Set up Git](https://help.github.com/articles/set-up-git/) -guide on GitHub. -- [Bazel](https://www.bazel.build/) for building opentelemetry-cpp API, -SDK with their unittests. We use 3.7.2 in our build system. +- A supported platform (e.g. Windows, macOS or Linux). Refer to [Platforms +Supported](./README.md#supported-development-platforms) for more information. +- A compatible C++ compiler supporting at least C++11. Major compilers are +supported. Refer to [Supported Compilers](./README.md#supported-c-versions) for +more information. +- [Git](https://git-scm.com/) for fetching opentelemetry-cpp source code from +repository. To install Git, consult the [Set up +Git](https://help.github.com/articles/set-up-git/) guide on GitHub. +- [Bazel](https://www.bazel.build/) for building opentelemetry-cpp API, SDK with +their unittests. We use 3.7.2 in our build system. -To install Bazel, consult the [Installing Bazel](https://docs.bazel.build/versions/3.7.0/install.html) guide. +To install Bazel, consult the [Installing +Bazel](https://docs.bazel.build/versions/3.7.0/install.html) guide. ### Building as standalone Bazel Project @@ -178,7 +186,8 @@ To install Bazel, consult the [Installing Bazel](https://docs.bazel.build/versio $ ``` -2. Navigate to the repository cloned above, download the dependencies and build the source code: +2. Navigate to the repository cloned above, download the dependencies and build + the source code: ```console $ cd opentelemtry-cpp @@ -252,23 +261,26 @@ cc_library( ## Building shared libs for Windows -Windows DLL build is not supported. There are some constraints on how C++ DLLs work on -Windows, specifically we can't safely allocate memory in one DLL and free it in another. -For now, OpenTelemetry C++ targets need to be statically linked into the Windows applications. +Windows DLL build is not supported. There are some constraints on how C++ DLLs +work on Windows, specifically we can't safely allocate memory in one DLL and +free it in another. For now, OpenTelemetry C++ targets need to be statically +linked into the Windows applications. ## Using Package Managers -If you are using [Conan](https://www.conan.io/) to manage your dependencies, -add [`opentelemetry-cpp/x.y.z`](https://conan.io/center/opentelemetry-cpp) to -your `conanfile`'s requires, where `x.y.z` is the release version you want to use. +If you are using [Conan](https://www.conan.io/) to manage your dependencies, add +[`opentelemetry-cpp/x.y.z`](https://conan.io/center/opentelemetry-cpp) to your +`conanfile`'s requires, where `x.y.z` is the release version you want to use. Please file issues [here](https://github.com/conan-io/conan-center-index/issues) if you experience problems with the packages. If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project -for external dependencies, then you can install the -[opentelemetry-cpp package](https://github.com/microsoft/vcpkg/tree/master/ports/opentelemetry-cpp) -with `vcpkg install opentelemetry-cpp` and follow the then displayed descriptions. -Please see the vcpkg project for any issues regarding the packaging. - -Please note, these packages are not officially provided and maintained by OpenTelemetry C++ project, -and are just listed here to consolidate all such efforts for ease of developers. +for external dependencies, then you can install the [opentelemetry-cpp +package](https://github.com/microsoft/vcpkg/tree/master/ports/opentelemetry-cpp) +with `vcpkg install opentelemetry-cpp` and follow the then displayed +descriptions. Please see the vcpkg project for any issues regarding the +packaging. + +Please note, these packages are not officially provided and maintained by +OpenTelemetry C++ project, and are just listed here to consolidate all such +efforts for ease of developers. diff --git a/README.md b/README.md index e891fca116..18b9aafd14 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,16 @@ The C++ [OpenTelemetry](https://opentelemetry.io/) client. | Metrics | Development [1] | N/A | | Logs | Experimental [2] | N/A | -* [1]: The development of the metrics API and SDK based on new stable specification is ongoing. The timelines would be available in release milestone. The earlier implementation (based on old specification) can be included in build by setting `ENABLE_METRICS_PREVIEW` preprocessor macro, and is included under `*/_metrics/*` directory. This would be eventually removed once the ongoing implemetation is stable. -* [2]: The current Log Signal Implementation is Experimental, and will change as the current OpenTelemetry Log specification matures. The current implementation can be included in build by setting `ENABLE_LOGS_PREVIEW` preprocessor macro. +* [1]: The development of the metrics API and SDK based on new stable + specification is ongoing. The timelines would be available in release + milestone. The earlier implementation (based on old specification) can be + included in build by setting `ENABLE_METRICS_PREVIEW` preprocessor macro, + and is included under `*/_metrics/*` directory. This would be eventually + removed once the ongoing implemetation is stable. +* [2]: The current Log Signal Implementation is Experimental, and will change as + the current OpenTelemetry Log specification matures. The current + implementation can be included in build by setting `ENABLE_LOGS_PREVIEW` + preprocessor macro. ## OpenTelemetry Specification Compatibility Matrix @@ -26,7 +34,8 @@ The C++ [OpenTelemetry](https://opentelemetry.io/) client. | 1.0.0 | 1.0.0-rc4 | N/A [1] | | 1.0.0 | 1.0.0 | N/A | -* [1]: We don't have releases for opentelemetry-cpp contrib repo. This may change in future. +* [1]: We don't have releases for opentelemetry-cpp contrib repo. This may + change in future. ## Supported C++ Versions @@ -66,7 +75,8 @@ having C++ compiler with [supported C++ standards](#supported-c-versions). ## Dependencies -Please refer to [Dependencies.md](docs/dependencies.md) for OSS Dependencies and license requirements. +Please refer to [Dependencies.md](docs/dependencies.md) for OSS Dependencies and +license requirements. ## Installation @@ -74,7 +84,9 @@ Please refer to [INSTALL.md](./INSTALL.md). ## Getting Started -As an application owner or the library author, you can find the getting started guide and reference documentation on [opentelemetry-cpp.readthedocs.io](https://opentelemetry-cpp.readthedocs.io/en/latest/) +As an application owner or the library author, you can find the getting started +guide and reference documentation on +[opentelemetry-cpp.readthedocs.io](https://opentelemetry-cpp.readthedocs.io/en/latest/) The `examples/simple` directory contains a minimal program demonstrating how to instrument a small library using a simple `processor` and console `exporter`, diff --git a/Versioning.md b/Versioning.md index 9327285163..b6cbe490e2 100644 --- a/Versioning.md +++ b/Versioning.md @@ -19,20 +19,20 @@ buy may not work in applications using `opentelemetry 2.0.0`. Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise: -* The API is header only, and uses ABI compliant interfaces. However, ABI stability - is not guaranteed for SDK. -* In case of ABI breaking changes, a new `inline namespace` version will - be introduced, and the existing linked applications can continue using the older version - unless they relink with newer version. +* The API is header only, and uses ABI compliant interfaces. However, ABI + stability is not guaranteed for SDK. +* In case of ABI breaking changes, a new `inline namespace` version will be + introduced, and the existing linked applications can continue using the older + version unless they relink with newer version. ## Release Policy * Release versions will follow [SemVer 2.0](https://semver.org/). * Only a single source package containing the API, SDK, and exporters which are required by the specification would be released. All these components are - always versioned and released together. For example, any changes in one of the exporter - would result in version update of the entire source package even though there is - no changes in API, SDK and other exporters. + always versioned and released together. For example, any changes in one of the + exporter would result in version update of the entire source package even + though there is no changes in API, SDK and other exporters. * Experimental releases: New (unstable) telemetry signals and features will be introduced behind feature flag protected by a preprocessor macro. @@ -65,16 +65,19 @@ Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise: allowed to break existing stable interfaces. Feature flags will be removed once we have a stable implementation for the signal. -* As an exception, small experimental features in otherwise stable signals/components - mayn't necessarily be released under feature flag. These would be flagged as experimental - by adding a `NOTE` in it's header file - either at the beginning of file, or as the comment for - the experimental API methods. Also, if the complete header is experimental, it would be prefixed - as `experimental_`. As an example, the semantic conventions for - trace signal is experimental at the time of the writing and is within `experimental_semantic_conventions.h` - -* Code under the "*::detail" namespace implements internal details, - and is NOT part of public interface. Also, any API not documented in the [public - documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT part of the public interface. +* As an exception, small experimental features in otherwise stable + signals/components mayn't necessarily be released under feature flag. These + would be flagged as experimental by adding a `NOTE` in it's header file - + either at the beginning of file, or as the comment for the experimental API + methods. Also, if the complete header is experimental, it would be prefixed as + `experimental_`. As an example, the semantic conventions for trace signal is + experimental at the time of the writing and is within + `experimental_semantic_conventions.h` + +* Code under the "*::detail" namespace implements internal details, and is NOT + part of public interface. Also, any API not documented in the [public + documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT + part of the public interface. * GitHub releases will be made for all released versions. diff --git a/examples/grpc/README.md b/examples/grpc/README.md index d964501aea..96d1dc2797 100644 --- a/examples/grpc/README.md +++ b/examples/grpc/README.md @@ -2,7 +2,10 @@ ## gRPC -This is a simple example that demonstrates tracing a gRPC request from client to server. There is an experimental directory in this example - the code within has been commented out to prevent any conflicts. The example shows several aspects of tracing such as: +This is a simple example that demonstrates tracing a gRPC request from client to +server. There is an experimental directory in this example - the code within has +been commented out to prevent any conflicts. The example shows several aspects +of tracing such as: * Using the `TracerProvider` * Implementing the TextMapCarrier @@ -15,16 +18,20 @@ This is a simple example that demonstrates tracing a gRPC request from client to ### Running the example -1. The example uses gRPC C++ as well as Google's protocol buffers. Make sure you have installed both - of these packages on your system, in such a way that CMake would know how to find them with this command: +1. The example uses gRPC C++ as well as Google's protocol buffers. Make sure you + have installed both of these packages on your system, in such a way that + CMake would know how to find them with this command: ``find_package(gRPC)`` -2. Build and Deploy the opentelementry-cpp as described in [INSTALL.md](../../INSTALL.md). Building the project will build all of the examples - and create new folders containing their executables within the 'build' directory NOT the 'examples' directory. +2. Build and Deploy the opentelementry-cpp as described in + [INSTALL.md](../../INSTALL.md). Building the project will build all of the + examples and create new folders containing their executables within the + 'build' directory NOT the 'examples' directory. -3. Start the server from your `build/examples/grpc` directory. Both the server and client are configured to use 8800 as the default port, - but if you would like to use another port, you can specify that as an argument. +3. Start the server from your `build/examples/grpc` directory. Both the server + and client are configured to use 8800 as the default port, but if you would + like to use another port, you can specify that as an argument. ```console $ ./server [port_num] @@ -38,7 +45,8 @@ This is a simple example that demonstrates tracing a gRPC request from client to ... ``` -5. You should see console exporter output for both the client and server sessions. +5. You should see console exporter output for both the client and server + sessions. * Client console ```console diff --git a/examples/http/README.md b/examples/http/README.md index 58ca97ca02..70285170fc 100644 --- a/examples/http/README.md +++ b/examples/http/README.md @@ -2,7 +2,8 @@ ## HTTP -This is a simple example that demonstrates tracing an HTTP request from client to server. The example shows several aspects of tracing such as: +This is a simple example that demonstrates tracing an HTTP request from client +to server. The example shows several aspects of tracing such as: * Using the `TracerProvider` * Using the `GlobalPropagator` @@ -15,10 +16,13 @@ This is a simple example that demonstrates tracing an HTTP request from client t ### Running the example 1. The example uses HTTP server and client provided as part of this repo: - * [HTTP Client](https://github.com/open-telemetry/opentelemetry-cpp/tree/main/ext/include/opentelemetry/ext/http/client) - * [HTTP Server](https://github.com/open-telemetry/opentelemetry-cpp/tree/main/ext/include/opentelemetry/ext/http/server) + * [HTTP + Client](https://github.com/open-telemetry/opentelemetry-cpp/tree/main/ext/include/opentelemetry/ext/http/client) + * [HTTP + Server](https://github.com/open-telemetry/opentelemetry-cpp/tree/main/ext/include/opentelemetry/ext/http/server) -2. Build and Deploy the opentelementry-cpp as described in [INSTALL.md](../../INSTALL.md) +2. Build and Deploy the opentelementry-cpp as described in + [INSTALL.md](../../INSTALL.md) 3. Start the server from the `examples/http` directory @@ -35,7 +39,8 @@ This is a simple example that demonstrates tracing an HTTP request from client t ... ``` -5. You should see console exporter output for both the client and server sessions. +5. You should see console exporter output for both the client and server + sessions. * Client console ```console @@ -103,4 +108,5 @@ This is a simple example that demonstrates tracing an HTTP request from client t } ``` - As seen from example above, `trace_id` and `parent_span_id` is propagated from client to server. + As seen from example above, `trace_id` and `parent_span_id` is propagated + from client to server. diff --git a/examples/multi_processor/README.md b/examples/multi_processor/README.md index 3efbfa6ef1..c539397623 100644 --- a/examples/multi_processor/README.md +++ b/examples/multi_processor/README.md @@ -2,13 +2,14 @@ In this example, the application in `main.cc` initializes and registers a tracer provider from the [OpenTelemetry -SDK](https://github.com/open-telemetry/opentelemetry-cpp). The `TracerProvider` is connected -to two `processor-exporter` pipelines - for exporting simultaneously to `StdoutSpanExporter` -and `InMemorySpanExporter`. The application then -calls a `foo_library` which has been instrumented using the [OpenTelemetry +SDK](https://github.com/open-telemetry/opentelemetry-cpp). The `TracerProvider` +is connected to two `processor-exporter` pipelines - for exporting +simultaneously to `StdoutSpanExporter` and `InMemorySpanExporter`. The +application then calls a `foo_library` which has been instrumented using the +[OpenTelemetry API](https://github.com/open-telemetry/opentelemetry-cpp/tree/main/api). -Resulting telemetry is directed to stdout through the StdoutSpanExporter, and saved as a -variable (vector of spans) through `InMemorySpanExporter`. +Resulting telemetry is directed to stdout through the StdoutSpanExporter, and +saved as a variable (vector of spans) through `InMemorySpanExporter`. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for instructions on building and running the example. diff --git a/examples/zipkin/README.md b/examples/zipkin/README.md index a07480213d..17d325ecb9 100644 --- a/examples/zipkin/README.md +++ b/examples/zipkin/README.md @@ -2,9 +2,10 @@ This is an example of how to use the Zipkin exporter. -The application in `main.cc` initializes an `ZipkinExporter` instance and uses it to -register a tracer provider from the [OpenTelemetry SDK](https://github.com/open-telemetry/opentelemetry-cpp). -The application then calls a `foo_library` which has been instrumented using the [OpenTelemetry +The application in `main.cc` initializes an `ZipkinExporter` instance and uses +it to register a tracer provider from the [OpenTelemetry +SDK](https://github.com/open-telemetry/opentelemetry-cpp). The application then +calls a `foo_library` which has been instrumented using the [OpenTelemetry API](https://github.com/open-telemetry/opentelemetry-cpp/tree/main/api). Resulting spans are exported to the Zipkin server using the Zipkin exporter. diff --git a/exporters/etw/README.md b/exporters/etw/README.md index 675fa6bb47..29dc3de430 100644 --- a/exporters/etw/README.md +++ b/exporters/etw/README.md @@ -1,45 +1,57 @@ # Getting Started with OpenTelemetry C++ SDK and ETW exporter on Windows -Event Tracing for Windows (ETW) is an efficient kernel-level tracing facility that lets you log kernel or -application-defined events to a log file. You can consume the events in real time or from a log file and -use them to debug an application or to determine where performance issues are occurring in the application. - -OpenTelemetry C++ SDK ETW exporter allows the code instrumented using OpenTelemetry API to forward events -to out-of-process ETW listener, for subsequent data recording or forwarding to alternate pipelines and -flows. Windows Event Tracing infrastructure is available to any vendor or application being deployed on -Windows. +Event Tracing for Windows (ETW) is an efficient kernel-level tracing facility +that lets you log kernel or application-defined events to a log file. You can +consume the events in real time or from a log file and use them to debug an +application or to determine where performance issues are occurring in the +application. + +OpenTelemetry C++ SDK ETW exporter allows the code instrumented using +OpenTelemetry API to forward events to out-of-process ETW listener, for +subsequent data recording or forwarding to alternate pipelines and flows. +Windows Event Tracing infrastructure is available to any vendor or application +being deployed on Windows. ## API support These are the features planned to be supported by ETW exporter: -- [x] OpenTelemetry Tracing API and SDK headers are **stable** and moving towards GA. -- [ ] OpenTelemetry Logging API is work-in-progress, pending implementation of [Latest Logging API spec here](https://github.com/open-telemetry/oteps/pull/150) +- [x] OpenTelemetry Tracing API and SDK headers are **stable** and moving + towards GA. +- [ ] OpenTelemetry Logging API is work-in-progress, pending implementation of + [Latest Logging API spec + here](https://github.com/open-telemetry/oteps/pull/150) - [ ] OpenTelemetry Metrics API is not implemented yet. -Implementation of OpenTelemetry C++ SDK ETW exporter on Windows OS is `header only` : +Implementation of OpenTelemetry C++ SDK ETW exporter on Windows OS is `header +only` : -- full definitions of all macros, functions and classes comprising the library are visible to the compiler -in a header file form. -- implementation does not need to be separately compiled, packaged and installed in order to be used. +- full definitions of all macros, functions and classes comprising the library +are visible to the compiler in a header file form. +- implementation does not need to be separately compiled, packaged and installed + in order to be used. -All that is required is to point the compiler at the location of the headers, and then `#include` the header -files into the application source. Compiler's optimizer can do a much better job when all the library's -source code is available. Several options below may be turned on to optimize the code with the usage of -standard C++ library, Microsoft Guidelines Support library, Google Abseil Variant library. Or enabling -support for non-standard features, such as 8-bit byte arrays support that enables performance-efficient -representation of binary blobs on ETW wire. +All that is required is to point the compiler at the location of the headers, +and then `#include` the header files into the application source. Compiler's +optimizer can do a much better job when all the library's source code is +available. Several options below may be turned on to optimize the code with the +usage of standard C++ library, Microsoft Guidelines Support library, Google +Abseil Variant library. Or enabling support for non-standard features, such as +8-bit byte arrays support that enables performance-efficient representation of +binary blobs on ETW wire. ## Example project -The following include directories are required, relative to the top-level source tree of OpenTelemetry C++ repo: +The following include directories are required, relative to the top-level source +tree of OpenTelemetry C++ repo: - api/include/ - exporters/etw/include/ - sdk/include/ -Code that instantiates ETW TracerProvider, subsequently obtaining a Tracer bound to `OpenTelemetry-ETW-Provider`, -and emitting a span named `MySpan` with attributes on it, as well as `MyEvent` within that span. +Code that instantiates ETW TracerProvider, subsequently obtaining a Tracer bound +to `OpenTelemetry-ETW-Provider`, and emitting a span named `MySpan` with +attributes on it, as well as `MyEvent` within that span. ```cpp @@ -100,10 +112,12 @@ Note that different `Tracer` objects may be bound to different ETW destinations. ## Build options and Compiler Defines -While including OpenTelemetry C++ SDK with ETW exporter, the customers are in complete control of -what options they would like to enable for their project using `Preprocessor Definitions`. +While including OpenTelemetry C++ SDK with ETW exporter, the customers are in +complete control of what options they would like to enable for their project +using `Preprocessor Definitions`. -These options affect how "embedded in application" OpenTelemetry C++ SDK code is compiled: +These options affect how "embedded in application" OpenTelemetry C++ SDK code is +compiled: | Name | Description | |---------------------|------------------------------------------------------------------------------------------------------------------------| @@ -115,13 +129,16 @@ These options affect how "embedded in application" OpenTelemetry C++ SDK code is ### ETW TraceLogging Dynamic Events -ETW supports a mode that is called "Dynamic Manifest", where event may contain strongly-typed -key-value pairs, with primitive types such as `integer`, `double`, `string`, etc. This mode -requires `TraceLoggingDynamic.h` header. Please refer to upstream repository containining -[Microsoft TraceLogging Dynamic framework](https://github.com/microsoft/tracelogging-dynamic-windows) -licensed under [MIT License](https://github.com/microsoft/tracelogging-dynamic-windows/blob/main/LICENSE). +ETW supports a mode that is called "Dynamic Manifest", where event may contain +strongly-typed key-value pairs, with primitive types such as `integer`, +`double`, `string`, etc. This mode requires `TraceLoggingDynamic.h` header. +Please refer to upstream repository containining [Microsoft TraceLogging Dynamic +framework](https://github.com/microsoft/tracelogging-dynamic-windows) licensed +under [MIT +License](https://github.com/microsoft/tracelogging-dynamic-windows/blob/main/LICENSE). -Complete [list of ETW types](https://docs.microsoft.com/en-us/windows/win32/wes/eventmanifestschema-outputtype-complextype#remarks). +Complete [list of ETW +types](https://docs.microsoft.com/en-us/windows/win32/wes/eventmanifestschema-outputtype-complextype#remarks). OpenTelemetry C++ ETW exporter implements the following type mapping: @@ -137,33 +154,37 @@ OpenTelemetry C++ ETW exporter implements the following type mapping: Support for arrays of primitive types is not implemented yet. -Visual Studio 2019 allows to use `View -> Other Windows -> Diagnostic Events` to capture -events that are emitted by instrumented application and sent to ETW provider in a live view. -Instrumentation name passed to `GetTracer` API above corresponds to `ETW Provider Name`. -If Instrumentation name contains a GUID - starts with a curly brace, e.g. -`{deadbeef-fade-dead-c0de-cafebabefeed}` then the parameter is assumed to be -`ETW Provider GUID`. - -Click on `Settings` and add the provider to monitor either by its Name or by GUID. In above -example, the provider name is `OpenTelemetry-ETW-Provider`. Please refer to Diagnostic Events -usage instructions [here](https://docs.microsoft.com/en-us/azure/service-fabric/service-fabric-diagnostics-how-to-monitor-and-diagnose-services-locally#view-service-fabric-system-events-in-visual-studio) -to learn more. Note that running ETW Listener in Visual Studio requires Elevation, i.e. -Visual Studio would prompt you to confirm that you accept to run the ETW Listener process as -Administrator. This is a limitation of ETW Listeners, they must be run as privileged process. +Visual Studio 2019 allows to use `View -> Other Windows -> Diagnostic Events` to +capture events that are emitted by instrumented application and sent to ETW +provider in a live view. Instrumentation name passed to `GetTracer` API above +corresponds to `ETW Provider Name`. If Instrumentation name contains a GUID - +starts with a curly brace, e.g. `{deadbeef-fade-dead-c0de-cafebabefeed}` then +the parameter is assumed to be `ETW Provider GUID`. + +Click on `Settings` and add the provider to monitor either by its Name or by +GUID. In above example, the provider name is `OpenTelemetry-ETW-Provider`. +Please refer to Diagnostic Events usage instructions +[here](https://docs.microsoft.com/en-us/azure/service-fabric/service-fabric-diagnostics-how-to-monitor-and-diagnose-services-locally#view-service-fabric-system-events-in-visual-studio) +to learn more. Note that running ETW Listener in Visual Studio requires +Elevation, i.e. Visual Studio would prompt you to confirm that you accept to run +the ETW Listener process as Administrator. This is a limitation of ETW +Listeners, they must be run as privileged process. ### ETW events encoded in MessagePack -OpenTelemetry ETW exporter optionally allows to encode the incoming event payload using -[MessagePack](https://msgpack.org/index.html) compact binary protocol. ETW/MsgPack encoding -requires [nlohmann/json](https://github.com/nlohmann/json) library to be included in the build -of OpenTelemetry ETW exporter. Any recent version of `nlohmann/json` is compatible with ETW -exporter. For example, the version included in `third_party/nlohmann-json` directory may be -used. +OpenTelemetry ETW exporter optionally allows to encode the incoming event +payload using [MessagePack](https://msgpack.org/index.html) compact binary +protocol. ETW/MsgPack encoding requires +[nlohmann/json](https://github.com/nlohmann/json) library to be included in the +build of OpenTelemetry ETW exporter. Any recent version of `nlohmann/json` is +compatible with ETW exporter. For example, the version included in +`third_party/nlohmann-json` directory may be used. -There is currently **no built-in decoder available** for this format. However, there is ongoing -effort to include the ETW/MsgPack decoder in [Azure/diagnostics-eventflow](https://github.com/Azure/diagnostics-eventflow) -project, which may be used as a side-car listener to forward incoming ETW/MsgPack events to many -other destinations, such as: +There is currently **no built-in decoder available** for this format. However, +there is ongoing effort to include the ETW/MsgPack decoder in +[Azure/diagnostics-eventflow](https://github.com/Azure/diagnostics-eventflow) +project, which may be used as a side-car listener to forward incoming +ETW/MsgPack events to many other destinations, such as: - StdOutput (console output) - HTTP (json via http) @@ -179,8 +200,9 @@ And community-contributed exporters: - ReflectInsight output - Splunk output -[This PR](https://github.com/Azure/diagnostics-eventflow/pull/382) implements the `Input adapter` -for OpenTelemetry ETW/MsgPack protocol encoded events for Azure EventFlow. +[This PR](https://github.com/Azure/diagnostics-eventflow/pull/382) implements +the `Input adapter` for OpenTelemetry ETW/MsgPack protocol encoded events for +Azure EventFlow. Other standard tools for processing ETW events on Windows OS, such as: @@ -193,9 +215,12 @@ will be augmented in future with support for ETW/MsgPack encoding. This document needs to be supplemented with additional information: -- [ ] mapping between OpenTelemetry fields and concepts and their corresponding ETW counterparts +- [ ] mapping between OpenTelemetry fields and concepts and their corresponding + ETW counterparts - [ ] links to E2E instrumentation example and ETW listener - [ ] Logging API example - [ ] Metrics API example (once Metrics spec is finalized) -- [ ] example how ETW Listener may employ OpenTelemetry .NET SDK to 1-1 transform from ETW events back to OpenTelemetry flow -- [ ] links to NuGet package that contains the source code of SDK that includes OpenTelemetry SDK and ETW exporter +- [ ] example how ETW Listener may employ OpenTelemetry .NET SDK to 1-1 + transform from ETW events back to OpenTelemetry flow +- [ ] links to NuGet package that contains the source code of SDK that includes + OpenTelemetry SDK and ETW exporter