From 7b6f195a2b4bf5d1d6e8c6f2d727e3ee307aeae4 Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Thu, 20 Aug 2020 16:24:18 +0000 Subject: [PATCH 1/8] Add usage instructions, remove unneeded details --- ext/src/zpages/README.md | 58 +++++++++++++--------------------------- 1 file changed, 19 insertions(+), 39 deletions(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index 8e8fed394a..72c29fbd3c 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -1,45 +1,25 @@ # zPages - -## Table of Contents -- [Summary](#summary) - - [TraceZ](#tracez) - - [RPCz](#rpcz) -- [Usage](#usage) -- [Links of Interest](#links-of-interest) - -## Summary -zPages allow easy viewing of tracing information. When included for a process, zPages will display basic information about that process on a webpage. Two types of zPages include TraceZ and RPCz. - -Including a zPage within a page is useful for developers because it's quicker to get running than adding extra code and installing external exporters like Jaeger and Zipkin. zPages tend to be more lightweight than these external exporters, but are also helpful for debugging latency issues (slow parts of applications) and deadlocks (running spans that don't end). - -The idea of "zPages" originates from one of OpenTelemetry's predecessors, [OpenCensus](https://opencensus.io/). You can read more about it [here](https://opencensus.io/zpages). OpenCensus has different zPage implementations in [Java](https://opencensus.io/zpages/java/), [Go](https://opencensus.io/zpages/go/), and [Node](https://opencensus.io/zpages/node/) and there has been similar internal solutions developed at companies like Uber, but *this is the first major open-source implementation of zPages in C++*. Within OpenTelemetry, zPages are also being developed in [Java](https://github.com/open-telemetry/opentelemetry-java). - -#### How It Works -On a high level, an application creates spans using a Tracer Provider/Tracer who passes them to a Span Processor, which exports spans to the appropriate Data Aggregator that a Http Server displays information for. - -> TODO: Add picture examples for span overview and individual span view - -### TraceZ -TraceZ is a type of zPage that shows information on tracing spans, and allows users to look closer at specific and individual spans. Details a user would view include span id, name, status, and timestamps. The individual components of TraceZ are as follows: - -- TracezSpanProcessor (TSP) - - A tracer/tracer provider (which the user chooses) creates spans, which connects to TSP so that TraceZ to detect spans. The TSP then stores tracing information in running and completed containers and provides an interface for TDA to access their information. -- TracezDataAggregator (TDA) - - Intermediary between the TSP and THS, which also performs various functions and calculations (mainly grouping spans by their names and latency times) to send the correct tracing information to the THS. -- TracezHttpServer (THS) - - User-facing web page generator, which creates HTML pages using TDA that display 1) overall information and trends on all of the process's spans and 2) more detailed information on specific spans when clicked. - -### RPCz -RPCz is a type of zPage that provides details on instrumented sent and received RPC messages. Although there is currently no ongoing development of RPCz for OpenTelemetry, OpenCensus zPages have implementations of RPCz (linked above). +## Overview +zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies. See more information in the OTel spec. # Usage -> TODO: Add instructions to add zPages +1. Add the following 2 lines of code + - `#include opentelemetry/ext/zpages/zpages.h // include zPages` + - `zpages::Initialize; // start up zPages in your app, before any tracing/span code` +2. Build and run your application normally + - For example, you can do this for the zPages example while at the root `opentelemetry-cpp` directory with: + ``` + bazel build //examples/zpages:zpages_example + bazel-bin/examples/zpages/zpages_example + ``` + If you look at the zPages example's source [code](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/examples/zpages/zpages_example.cc), it demonstrates adding zPages, manual application instrumentation (which sends data to zPages for viewing), and simulated use cases for zPages. +3. View zPages ib http://localhost:3000/tracez + -## Links of Interest -- [TracezSpanProcessor Design Doc](https://docs.google.com/document/d/1kO4iZARYyr-EGBlY2VNM3ELU3iw6ZrC58Omup_YT-fU/edit#) (pending review) -- [TracezDataAggregator Design Doc](https://docs.google.com/document/d/1ziKFgvhXFfRXZjOlAHQRR-TzcNcTXzg1p2I9oPCEIoU/edit?ts=5ef0d177#heading=h.5irk4csrpu0y) (pending review) -- [TracezHttpServer Design Doc](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) (draft) +## More Information - [zPages General Direction Spec](https://github.com/open-telemetry/oteps/blob/master/text/0110-z-pages.md) -- [Prospective Fields Displayed by - TraceZ](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/sdk/include/opentelemetry/sdk/trace/span_data.h) +- OTel C++ Design Docs + - [Tracez Span Processor](https://docs.google.com/document/d/1kO4iZARYyr-EGBlY2VNM3ELU3iw6ZrC58Omup_YT-fU/edit#) + - [Tracez Data Aggregator](https://docs.google.com/document/d/1ziKFgvhXFfRXZjOlAHQRR-TzcNcTXzg1p2I9oPCEIoU/edit?ts=5ef0d177#heading=h.5irk4csrpu0y) + - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - includes pictures of Tracez From 85e3e3306298d0bfafdcd343f93c490b68394cd8 Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Thu, 20 Aug 2020 16:29:17 +0000 Subject: [PATCH 2/8] Fix typo, adjust wording --- ext/src/zpages/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index 72c29fbd3c..e6b9e0470b 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -14,7 +14,7 @@ zPages are a quick and light way to view tracing and metrics information on stan bazel-bin/examples/zpages/zpages_example ``` If you look at the zPages example's source [code](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/examples/zpages/zpages_example.cc), it demonstrates adding zPages, manual application instrumentation (which sends data to zPages for viewing), and simulated use cases for zPages. -3. View zPages ib http://localhost:3000/tracez +3. View zPages in http://localhost:3000/tracez ## More Information @@ -22,4 +22,4 @@ zPages are a quick and light way to view tracing and metrics information on stan - OTel C++ Design Docs - [Tracez Span Processor](https://docs.google.com/document/d/1kO4iZARYyr-EGBlY2VNM3ELU3iw6ZrC58Omup_YT-fU/edit#) - [Tracez Data Aggregator](https://docs.google.com/document/d/1ziKFgvhXFfRXZjOlAHQRR-TzcNcTXzg1p2I9oPCEIoU/edit?ts=5ef0d177#heading=h.5irk4csrpu0y) - - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - includes pictures of Tracez + - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - includes pictures of zPages/Tracez UI From d9005024baf740783212ffc9bfc1c0959a203cc4 Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Sat, 22 Aug 2020 13:09:35 -0400 Subject: [PATCH 3/8] Add experimental spec links --- ext/src/zpages/README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index e6b9e0470b..cd7f21f18c 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -1,6 +1,6 @@ # zPages ## Overview -zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies. See more information in the OTel spec. +zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). # Usage @@ -14,12 +14,13 @@ zPages are a quick and light way to view tracing and metrics information on stan bazel-bin/examples/zpages/zpages_example ``` If you look at the zPages example's source [code](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/examples/zpages/zpages_example.cc), it demonstrates adding zPages, manual application instrumentation (which sends data to zPages for viewing), and simulated use cases for zPages. -3. View zPages in http://localhost:3000/tracez +3. View zPages ib http://localhost:3000/tracez ## More Information -- [zPages General Direction Spec](https://github.com/open-telemetry/oteps/blob/master/text/0110-z-pages.md) +- OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md) +- [zPages General Direction Spec (OTEP)](https://github.com/open-telemetry/oteps/blob/master/text/0110-z-pages.md) - OTel C++ Design Docs - [Tracez Span Processor](https://docs.google.com/document/d/1kO4iZARYyr-EGBlY2VNM3ELU3iw6ZrC58Omup_YT-fU/edit#) - [Tracez Data Aggregator](https://docs.google.com/document/d/1ziKFgvhXFfRXZjOlAHQRR-TzcNcTXzg1p2I9oPCEIoU/edit?ts=5ef0d177#heading=h.5irk4csrpu0y) - - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - includes pictures of zPages/Tracez UI + - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - also includes pictures From b361050a2231f80e763c4168695f0b53fb242f17 Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Sat, 22 Aug 2020 19:07:46 +0000 Subject: [PATCH 4/8] Add CMake todo --- ext/src/zpages/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index e6b9e0470b..aafe4bd226 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -1,8 +1,9 @@ # zPages ## Overview -zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies. See more information in the OTel spec. +zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). # Usage +> TODO: Add CMake instructions 1. Add the following 2 lines of code - `#include opentelemetry/ext/zpages/zpages.h // include zPages` @@ -14,12 +15,14 @@ zPages are a quick and light way to view tracing and metrics information on stan bazel-bin/examples/zpages/zpages_example ``` If you look at the zPages example's source [code](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/examples/zpages/zpages_example.cc), it demonstrates adding zPages, manual application instrumentation (which sends data to zPages for viewing), and simulated use cases for zPages. -3. View zPages in http://localhost:3000/tracez +3. View zPages ib http://localhost:3000/tracez ## More Information -- [zPages General Direction Spec](https://github.com/open-telemetry/oteps/blob/master/text/0110-z-pages.md) +- OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md) +- [zPages General Direction Spec (OTEP)](https://github.com/open-telemetry/oteps/blob/master/text/0110-z-pages.md) - OTel C++ Design Docs - [Tracez Span Processor](https://docs.google.com/document/d/1kO4iZARYyr-EGBlY2VNM3ELU3iw6ZrC58Omup_YT-fU/edit#) - [Tracez Data Aggregator](https://docs.google.com/document/d/1ziKFgvhXFfRXZjOlAHQRR-TzcNcTXzg1p2I9oPCEIoU/edit?ts=5ef0d177#heading=h.5irk4csrpu0y) - - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - includes pictures of zPages/Tracez UI + - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - also includes reference pictures of the zPages/Tracez UI + From 8a7c396f01a6e775438274269014a2aa8decbfb0 Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Mon, 24 Aug 2020 16:45:27 +0000 Subject: [PATCH 5/8] Add more TODOs --- ext/src/zpages/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index 1bcc44aebd..4e7ac601b3 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -1,6 +1,6 @@ # zPages ## Overview -zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). +zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies or backend setup. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). OTel C++ currently omly offers Tracez; future zPages to potentially add include TraceConfigz, RPCz, and Statsz. # Usage > TODO: Add CMake instructions From e84363013e3bce9ec8fe8e4ec6c3ad224bbee9ab Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Mon, 24 Aug 2020 16:49:03 +0000 Subject: [PATCH 6/8] Fix typo --- ext/src/zpages/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index 4e7ac601b3..93a56ddce0 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -1,6 +1,6 @@ # zPages ## Overview -zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies or backend setup. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). OTel C++ currently omly offers Tracez; future zPages to potentially add include TraceConfigz, RPCz, and Statsz. +zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies or backend setup. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). OTel C++ currently only offers Tracez; future zPages to potentially add include TraceConfigz, RPCz, and Statsz. # Usage > TODO: Add CMake instructions @@ -15,7 +15,7 @@ zPages are a quick and light way to view tracing and metrics information on stan bazel-bin/examples/zpages/zpages_example ``` If you look at the zPages example's source [code](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/examples/zpages/zpages_example.cc), it demonstrates adding zPages, manual application instrumentation (which sends data to zPages for viewing), and simulated use cases for zPages. -3. View zPages ib http://localhost:3000/tracez +3. View zPages at http://localhost:3000/tracez ## More Information From f43ecde9a00864fa427f448c90de6a6c96bd8456 Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Mon, 24 Aug 2020 22:04:16 +0000 Subject: [PATCH 7/8] Update tracez todo in readme --- ext/src/zpages/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index 93a56ddce0..a9d818b270 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -1,6 +1,6 @@ # zPages ## Overview -zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies or backend setup. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). OTel C++ currently only offers Tracez; future zPages to potentially add include TraceConfigz, RPCz, and Statsz. +zPages are a quick and light way to view tracing and metrics information on standard OpenTelemetry C++ instrumented applications. It requires no external dependencies or backend setup. See more information in the OTel zPages experimental [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/5b86d4b6c42e6d1e47d9155ac1e2e27f0f0b7769/experimental/trace/zpages.md). OTel C++ currently only offers Tracez; future zPages to potentially add include TraceConfigz, RPCz, and Statsz. Events and links need to be added to Tracez. # Usage > TODO: Add CMake instructions From 7a433cbf96a55ed3f473e8a598b525ad18f25d64 Mon Sep 17 00:00:00 2001 From: Janet Vu Date: Mon, 24 Aug 2020 18:31:38 -0400 Subject: [PATCH 8/8] Update ext/src/zpages/README.md Co-authored-by: Reiley Yang --- ext/src/zpages/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ext/src/zpages/README.md b/ext/src/zpages/README.md index a9d818b270..e9e3eff7c3 100644 --- a/ext/src/zpages/README.md +++ b/ext/src/zpages/README.md @@ -14,7 +14,7 @@ zPages are a quick and light way to view tracing and metrics information on stan bazel build //examples/zpages:zpages_example bazel-bin/examples/zpages/zpages_example ``` - If you look at the zPages example's source [code](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/examples/zpages/zpages_example.cc), it demonstrates adding zPages, manual application instrumentation (which sends data to zPages for viewing), and simulated use cases for zPages. + If you look at the [zPages example's source code](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/examples/zpages/zpages_example.cc), it demonstrates adding zPages, manual application instrumentation (which sends data to zPages for viewing), and simulated use cases for zPages. 3. View zPages at http://localhost:3000/tracez @@ -25,4 +25,3 @@ zPages are a quick and light way to view tracing and metrics information on stan - [Tracez Span Processor](https://docs.google.com/document/d/1kO4iZARYyr-EGBlY2VNM3ELU3iw6ZrC58Omup_YT-fU/edit#) - [Tracez Data Aggregator](https://docs.google.com/document/d/1ziKFgvhXFfRXZjOlAHQRR-TzcNcTXzg1p2I9oPCEIoU/edit?ts=5ef0d177#heading=h.5irk4csrpu0y) - [Tracez Http Server](https://docs.google.com/document/d/1U1V8QZ5LtGl4Mich-aJ6KZGLHrMIE8pWyspmzvnIefI/edit#) - includes reference pictures of the zPages/Tracez UI -