From cdbc90abf3b7170f898439fd34126469c42686c6 Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Tue, 5 Sep 2023 10:51:58 +0200
Subject: [PATCH] [DEPRECATION] Deprecate ZPAGES (#2291)

---
 CHANGELOG.md   |  3 ++
 CMakeLists.txt | 11 ++++++-
 DEPRECATED.md  | 84 +++++++++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 96 insertions(+), 2 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 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]