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 dcf1034804..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 "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 +259,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..05ba8e52d4 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -151,7 +151,89 @@ N/A ## [opentelemetry-cpp Exporter] -N/A +### ZPages exporter + +#### Announcement (ZPages) + +* Version: 1.11.0 +* Date: 2023-09-01 +* PR: [DEPRECATION] Deprecate ZPAGES + [#2291](https://github.com/open-telemetry/opentelemetry-cpp/pull/2291) + +#### 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`) + +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` + * the C++ class `HttpServer` + * 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, +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) + +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 ## [Documentation]