Reorganize demo feature documentation (#3714)

open-telemetry · Jan 3, 2024 · 735babe · 735babe
1 parent beffc8e
commit 735babe
Show file tree

Hide file tree

Showing 11 changed files with 56 additions and 37 deletions.
diff --git a/.cspell.yml b/.cspell.yml
@@ -33,6 +33,7 @@ words:
   - currencyservice
   - daemonset
   - datadog
+  - dataprepper
   - declarators
   - discoverability
   - dotnet
@@ -102,6 +103,7 @@ words:
   - postgresql
   - Pranay
   - Prateek
+  - Prepper
   - Println
   - productcatalogservice
   - prometheus

diff --git a/content/en/blog/2022/announcing-opentelemetry-demo-release/index.md b/content/en/blog/2022/announcing-opentelemetry-demo-release/index.md
@@ -20,8 +20,8 @@ One of our primary goals of this project has been to create a robust sample
 application for developers to use in learning OpenTelemetry, and we’re proud to
 say that we’ve done just that. Every OpenTelemetry language SDK except Swift is
 [represented](/docs/demo/service-table/) in this release -- yes, even PHP! We’ve
-built complete [tracing flows](/docs/demo/trace-features/) that demonstrate a
-breadth of common instrumentation tasks such as:
+built complete [tracing flows](/docs/demo/telemetry-features/trace-features/)
+that demonstrate a breadth of common instrumentation tasks such as:
 
 - Enriching spans from automatic instrumentation.
 - Creating custom spans for richer, more useful traces.
@@ -30,8 +30,8 @@ breadth of common instrumentation tasks such as:
 - Creating attributes, events, and other telemetry metadata.
 
 We’ve also integrated OpenTelemetry Metrics across
-[several services](/docs/demo/metric-features/) to capture runtime and business
-metric use cases.
+[several services](/docs/demo/telemetry-features/metric-features/) to capture
+runtime and business metric use cases.
 
 Now, it’d be enough to just provide a great demonstration of OpenTelemetry, but
 one thing we wanted to focus on for our 1.0 release was showing not just the

diff --git a/content/en/blog/2023/logs-collection/index.md b/content/en/blog/2023/logs-collection/index.md
@@ -4,7 +4,7 @@ linkTitle: Python Logs Collection
 date: 2023-11-21
 author: '[Michael Hausenblas](https://github.com/mhausenblas) (AWS)'
 # prettier-ignore
-cSpell:ignore: asctime Chehab dataprepper exgru fileconsumer filelog Grogu grogu hossko Houssam levelname logfile otelbin Padawan Prepper svrnm WORKDIR yoda
+cSpell:ignore: asctime Chehab exgru fileconsumer filelog Grogu grogu hossko Houssam levelname logfile otelbin Padawan svrnm WORKDIR yoda
 ---
 
 In the following, we will walk through how to do

diff --git a/content/en/docs/demo/_index.md b/content/en/docs/demo/_index.md
@@ -75,10 +75,10 @@ Project reference documentation, like requirements and feature matrices.
 - [Architecture](architecture/)
 - [Development](development/)
 - [Feature Flags Reference](feature-flags/)
-- [Metric Feature Matrix](metric-features/)
+- [Metric Feature Matrix](telemetry-features/metric-features/)
 - [Requirements](./requirements/)
 - [Screenshots](screenshots/)
 - [Service Roles Table](service-table/)
-- [Span Attributes Reference](manual-span-attributes/)
+- [Span Attributes Reference](telemetry-features/manual-span-attributes/)
 - [Tests](tests/)
-- [Trace Feature Matrix](trace-features/)
+- [Trace Feature Matrix](telemetry-features/trace-features/)
diff --git a/content/en/docs/demo/architecture.md b/content/en/docs/demo/architecture.md
@@ -119,8 +119,9 @@ classDef typescript fill:#e98516,color:black;
 ```
 
 Follow these links for the current state of
-[metric](/docs/demo/metric-features/) and [trace](/docs/demo/trace-features/)
-instrumentation of the demo applications.
+[metric](/docs/demo/telemetry-features/metric-features/) and
+[trace](/docs/demo/telemetry-features/trace-features/) instrumentation of the
+demo applications.
 
 The collector is configured in
 [otelcol-config.yml](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/otelcollector/otelcol-config.yml),

diff --git a/content/en/docs/demo/feature-flags.md b/content/en/docs/demo/feature-flags.md
@@ -1,6 +1,6 @@
 ---
 title: Feature Flags
-aliases: [feature_flags]
+aliases: [feature_flags, ../feature_flags/]
 cSpell:ignore: OLJCESPC7Z
 ---
 

diff --git a/content/en/docs/demo/features.md → ...en/docs/demo/telemetry-features/_index.md b/content/en/docs/demo/features.md → ...en/docs/demo/telemetry-features/_index.md
@@ -1,37 +1,53 @@
 ---
-title: Demo Features
-linkTitle: Features
+title: Telemetry Features
+linkTitle: Telemetry Features
 aliases: [demo_features]
 ---
 
-- **[Kubernetes](https://kubernetes.io/)**: the app is designed to run on
-  Kubernetes (both locally, as well as on the cloud) using a Helm chart.
-- **[Docker](https://docs.docker.com)**: this forked sample can also be executed
-  only with Docker.
-- **[gRPC](https://grpc.io/)**: microservices use a high volume of gRPC calls to
-  communicate to each other.
-- **[HTTP](https://www.rfc-editor.org/rfc/rfc9110.html)**: microservices use
-  HTTP where gRPC is unavailable or not well supported.
+## OpenTelemetry
+
 - **[OpenTelemetry Traces](/docs/concepts/signals/traces/)**: all services are
   instrumented using OpenTelemetry available instrumentation libraries.
-- **[OpenTelemetry Metrics](/docs/concepts/signals/metrics/)**: Select services
+- **[OpenTelemetry Metrics](/docs/concepts/signals/metrics/)**: select services
   are instrumented using OpenTelemetry available instrumentation libraries. More
   will be added as the relevant SDKs are released.
+- **[OpenTelemetry Logs](/docs/concepts/signals/logs/)**: select services are
+  instrumented using OpenTelemetry available instrumentation libraries. More
+  will be added as the relevant SDKs are released.
 - **[OpenTelemetry Collector](/docs/collector/)**: all services are instrumented
   and sending the generated traces and metrics to the OpenTelemetry Collector
   via gRPC. The received traces are then exported to the logs and to Jaeger;
   received metrics and exemplars are exported to logs and Prometheus.
+
+## Observability Solutions
+
+- **[Grafana](https://grafana.com/)**: all metric dashboards are stored in
+  Grafana.
 - **[Jaeger](https://www.jaegertracing.io/)**: all generated traces are being
   sent to Jaeger.
-- **Synthetic Load Generation**: the application demo comes with a background
-  job that creates realistic usage patterns on the website using
-  [Locust](https://locust.io/) load generator.
+- **[OpenSearch](https://opensearch.org/)**: all generated logs are sent to
+  DataPrepper. OpenSearch will be used to centralize logging data from services.
 - **[Prometheus](https://prometheus.io/)**: all generated metrics and exemplars
   are scraped by Prometheus.
-- **[Grafana](https://grafana.com/)**: all metric dashboards are stored in
-  Grafana.
+
+## Environments
+
+- **[Docker](https://docs.docker.com)**: this forked sample can be executed with
+  Docker.
+- **[Kubernetes](https://kubernetes.io/)**: the app is designed to run on
+  Kubernetes (both locally, as well as on the cloud) using a Helm chart.
+
+## Protocols
+
+- **[gRPC](https://grpc.io/)**: microservices use a high volume of gRPC calls to
+  communicate to each other.
+- **[HTTP](https://www.rfc-editor.org/rfc/rfc9110.html)**: microservices use
+  HTTP where gRPC is unavailable or not well supported.
+
+## Other Components
+
 - **[Envoy](https://www.envoyproxy.io/)**: Envoy is used as a reverse proxy for
   user-facing web interfaces such as the frontend, load generator, and feature
   flag service.
-- **[OpenSearch](https://opensearch.org/)**: OpenSearch is used to centralize
-  logging data from services.
+- **[Locust](https://locust.io)**: a background job that creates realistic usage
+  patterns on the website using a synthetic load generator.
diff --git a/content/en/docs/demo/logging-features.md → ...mo/telemetry-features/logging-features.md b/content/en/docs/demo/logging-features.md → ...mo/telemetry-features/logging-features.md
@@ -1,7 +1,7 @@
 ---
 title: Log Coverage by Service
-linkTitle: Log Feature Coverage
-aliases: [log_service_features]
+linkTitle: Log Coverage
+aliases: [log_service_features, ../log_features]
 ---
 
 | Service         | Language        | OTLP Logs |

diff --git a/...nt/en/docs/demo/manual-span-attributes.md → ...emetry-features/manual-span-attributes.md b/...nt/en/docs/demo/manual-span-attributes.md → ...emetry-features/manual-span-attributes.md
diff --git a/content/en/docs/demo/metric-features.md → ...emo/telemetry-features/metric-features.md b/content/en/docs/demo/metric-features.md → ...emo/telemetry-features/metric-features.md
@@ -1,7 +1,7 @@
 ---
-title: Metric Feature Coverage by Service
-linkTitle: Metric Feature Coverage
-aliases: [metric_service_features]
+title: Metric Coverage by Service
+linkTitle: Metric Coverage
+aliases: [metric_service_features, ../metric_features]
 ---
 
 | Service         | Language        | Auto-instrumentation | Manual Instrumentation | Multiple Instruments | Views | Custom Attributes | Resource Detection | Trace Exemplars |

diff --git a/content/en/docs/demo/trace-features.md → ...demo/telemetry-features/trace-features.md b/content/en/docs/demo/trace-features.md → ...demo/telemetry-features/trace-features.md
@@ -1,7 +1,7 @@
 ---
-title: Trace Feature Coverage by Service
-linkTitle: Trace Feature Coverage
-aliases: [trace_service_features]
+title: Trace Coverage by Service
+linkTitle: Trace Coverage
+aliases: [trace_service_features, ../trace_features]
 ---
 
 | Service            | Language        | Instrumentation Libraries | Manual Span Creation | Span Data Enrichment | RPC Context Propagation | Span Links | Baggage | Resource Detection |