From 62c721c3fce54283a2933eace8d126b4711f8407 Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Fri, 1 Sep 2023 21:33:42 +0200 Subject: [PATCH 1/6] Fixes #2217 --- CMakeLists.txt | 10 +++++++++- DEPRECATED.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 62 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index dcf1034804..02d18a95bf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -185,7 +185,7 @@ option(WITH_PROMETHEUS "Whether to include the Prometheus Client in the SDK" option(WITH_ELASTICSEARCH "Whether to include the Elasticsearch Client in the SDK" OFF) -option(WITH_ZPAGES "Whether to include the Zpages Server in the SDK" OFF) +option(WITH_ZPAGES "DEPRECATED - Whether to include the Zpages Server in the SDK" OFF) option(WITH_NO_GETENV "Whether the platform supports environment variables" OFF) @@ -258,6 +258,14 @@ option(WITH_OTLP_HTTP_SSL_TLS_PREVIEW option(WITH_METRICS_EXEMPLAR_PREVIEW "Whether to enable exemplar within metrics" OFF) +if(WITH_ZPAGES) + if(WITH_NO_DEPRECATED_CODE) + message(FATAL_ERROR "WITH_ZPAGES is DEPRECATED.") + else() + message(WARNING "WITH_ZPAGES is DEPRECATED.") + endif() +endif() + # # Verify options dependencies # diff --git a/DEPRECATED.md b/DEPRECATED.md index d77c3f073e..a9309b017b 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -151,7 +151,59 @@ N/A ## [opentelemetry-cpp Exporter] -N/A +### ZPages exporter + +#### Announcement (ZPages) + +* Version: 1.11.0 +* Date: 2023-09-01 +* PR: [DEPRECATION] Deprecate the ZPages exporter + [#xxxx](https://github.com/open-telemetry/opentelemetry-cpp/pull/xxxx) + +#### Motivation (ZPages) + +The ZPages specification itself was introduced in 2020, +and has been experimental ever since, +not getting a lot of attention, and never reaching a stable status. + +Several other opentelemetry projects have implemented support for zpages, +only to later deprecate and then remove the zpages implementation (Java, +C#), abandoning the zpages feature. + +In this context, it does not make sense to continue to maintain the zpages +code in opentelemetry-cpp. + +#### Scope (ZPages) + +The following are deprecated and planned for removal: + +* all the API headers located under `ext/include/opentelemetry/ext/zpages/`, including: + * the C++ class `ThreadsafeSpanData` + * the C++ class `TracezDataAggregator` + * the C++ class `TracezHttpServer` + * the C++ class `TracezSpanProcessor` + * the C++ class `TracezSharedData` + * the C++ class `ZPages` + * the C++ class `zPagesHttpServer` +* all the code and doc located under `ext/src/zpages/` +* all the tests located under `ext/test/zpages/` +* the zpages exporter library(`opentelemetry_zpages`) +* the zpages build options in CMake (`WITH_ZPAGES`) + +#### Mitigation (ZPages) + +Consider using a different exporter, +for example the OTLP exporter (both OTLP HTTP and OTLP GRPC are supported), +to expose trace data to a separate trace backend. + +Note that this changes the access pattern: + +* with zpages, data is only available locally (in process) +* with other exporters, data is available externally (not in process) + +#### Planned removal (ZPages) + +* Date: December, 2023 ## [Documentation] From e41a2c40b455e3222900f3e6be6bf3c3cd188e0a Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Fri, 1 Sep 2023 21:39:43 +0200 Subject: [PATCH 2/6] cleanup --- CHANGELOG.md | 3 +++ CMakeLists.txt | 3 ++- DEPRECATED.md | 4 ++-- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c4ce6f45f..f09553ce70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ Increment the: ## [Unreleased] +* [DEPRECATION] Deprecate ZPAGES + [#2291](https://github.com/open-telemetry/opentelemetry-cpp/pull/2291) + ## [1.11.0] 2023-08-21 * [BUILD] Fix more cases for symbol name for 32-bit win32 DLL build diff --git a/CMakeLists.txt b/CMakeLists.txt index 02d18a95bf..d1b1a384a8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -185,7 +185,8 @@ option(WITH_PROMETHEUS "Whether to include the Prometheus Client in the SDK" option(WITH_ELASTICSEARCH "Whether to include the Elasticsearch Client in the SDK" OFF) -option(WITH_ZPAGES "DEPRECATED - Whether to include the Zpages Server in the SDK" OFF) +option(WITH_ZPAGES + "DEPRECATED - Whether to include the Zpages Server in the SDK" OFF) option(WITH_NO_GETENV "Whether the platform supports environment variables" OFF) diff --git a/DEPRECATED.md b/DEPRECATED.md index a9309b017b..7361b6899c 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -157,8 +157,8 @@ N/A * Version: 1.11.0 * Date: 2023-09-01 -* PR: [DEPRECATION] Deprecate the ZPages exporter - [#xxxx](https://github.com/open-telemetry/opentelemetry-cpp/pull/xxxx) +* PR: [DEPRECATION] Deprecate ZPAGES + [#2291](https://github.com/open-telemetry/opentelemetry-cpp/pull/2291) #### Motivation (ZPages) From 91a7cbd739fc11bca19723fa0e074b9b31c9cb9f Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Tue, 5 Sep 2023 09:42:11 +0200 Subject: [PATCH 3/6] Implemented review comments --- DEPRECATED.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/DEPRECATED.md b/DEPRECATED.md index 7361b6899c..49ab46bb52 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -189,6 +189,12 @@ The following are deprecated and planned for removal: * all the tests located under `ext/test/zpages/` * the zpages exporter library(`opentelemetry_zpages`) * the zpages build options in CMake (`WITH_ZPAGES`) +* all the API headers located under `ext/include/opentelemetry/ext/http/server`, including: + * the C++ class `FileHttpServer` + * the C++ class `HttpRequestCallback` + * the C++ class `HttpServer` + * the C++ class `HttpRequestHandler` + * the C++ class `SocketCallback` #### Mitigation (ZPages) @@ -201,6 +207,20 @@ Note that this changes the access pattern: * with zpages, data is only available locally (in process) * with other exporters, data is available externally (not in process) +Our assessment is that the zpages implementation, is no longer in use, +and can be removed. + +If that assessment is incorrect (i.e., if you own a project that depends +on the zpage exporter from opentelemetry-cpp), please comment on the +removal issue +[#2292](https://github.com/open-telemetry/opentelemetry-cpp/issues/2292). + +An alternative to zpage removal is to move the code to the +opentelemetry-cpp-contrib github +[repository](https://github.com/open-telemetry/opentelemetry-cpp-contrib). + +Contributions to migrate the code, and maintain zpages, are welcome. + #### Planned removal (ZPages) * Date: December, 2023 From 90ed1648f5a9353f2dccd80283cd5c404da5e864 Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Tue, 5 Sep 2023 09:50:25 +0200 Subject: [PATCH 4/6] Rewording: private, not removed --- DEPRECATED.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/DEPRECATED.md b/DEPRECATED.md index 49ab46bb52..054d471c4e 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -189,6 +189,10 @@ The following are deprecated and planned for removal: * all the tests located under `ext/test/zpages/` * the zpages exporter library(`opentelemetry_zpages`) * the zpages build options in CMake (`WITH_ZPAGES`) + +The following code is no longer considered public, will no longer be +installed, and will no longer be useable outside of the opentelemetry-cpp implementation: + * all the API headers located under `ext/include/opentelemetry/ext/http/server`, including: * the C++ class `FileHttpServer` * the C++ class `HttpRequestCallback` @@ -196,6 +200,9 @@ The following are deprecated and planned for removal: * the C++ class `HttpRequestHandler` * the C++ class `SocketCallback` +This implementation of an HTTP server is meant to be used for testing only, +it is not production ready. + #### Mitigation (ZPages) Consider using a different exporter, From 8929de66afce0d869d8f3df882dde4090a88f3c7 Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Tue, 5 Sep 2023 09:52:38 +0200 Subject: [PATCH 5/6] Cleanup --- DEPRECATED.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEPRECATED.md b/DEPRECATED.md index 054d471c4e..ac7e04c422 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -214,7 +214,7 @@ Note that this changes the access pattern: * with zpages, data is only available locally (in process) * with other exporters, data is available externally (not in process) -Our assessment is that the zpages implementation, is no longer in use, +Our assessment is that the zpages implementation is no longer in use, and can be removed. If that assessment is incorrect (i.e., if you own a project that depends From a21a6b18894b634cdef02aac3f0c78c49abb22bb Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Tue, 5 Sep 2023 09:57:56 +0200 Subject: [PATCH 6/6] markdown lint. --- DEPRECATED.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/DEPRECATED.md b/DEPRECATED.md index ac7e04c422..05ba8e52d4 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -177,7 +177,8 @@ code in opentelemetry-cpp. The following are deprecated and planned for removal: -* all the API headers located under `ext/include/opentelemetry/ext/zpages/`, including: +* all the API headers located under + `ext/include/opentelemetry/ext/zpages/`, including: * the C++ class `ThreadsafeSpanData` * the C++ class `TracezDataAggregator` * the C++ class `TracezHttpServer` @@ -191,9 +192,11 @@ The following are deprecated and planned for removal: * the zpages build options in CMake (`WITH_ZPAGES`) The following code is no longer considered public, will no longer be -installed, and will no longer be useable outside of the opentelemetry-cpp implementation: +installed, and will no longer be useable outside of +the opentelemetry-cpp implementation: -* all the API headers located under `ext/include/opentelemetry/ext/http/server`, including: +* all the API headers located under + `ext/include/opentelemetry/ext/http/server`, including: * the C++ class `FileHttpServer` * the C++ class `HttpRequestCallback` * the C++ class `HttpServer`