Added Weaver configuration for all telemetry, and a generated mkdocs site

.env

@@ -192,3 +192,8 @@ JAEGER_GRPC_PORT=4317
 PROMETHEUS_PORT=9090
 PROMETHEUS_HOST=prometheus
 PROMETHEUS_ADDR=${PROMETHEUS_HOST}:${PROMETHEUS_PORT}
+
+# Telemetry Documentation
+TELEMETRY_DOCS_HOST=telemetry-docs
+TELEMETRY_DOCS_PORT=8000
+TELEMETRY_DOCS_DOCKERFILE=./src/telemetry-docs/Dockerfile

.github/workflows/component-build-images.yml

@@ -142,6 +142,10 @@ jobs:
             tag_suffix: shipping
             context: ./
             setup-qemu: true
+          - file: ./src/telemetry-docs/Dockerfile
+            tag_suffix: telemetry-docs
+            context: ./
+            setup-qemu: true
           - file: ./test/tracetesting/Dockerfile
             tag_suffix: traceBasedTests
             context: ./

CHANGELOG.md

@@ -7,6 +7,9 @@ the release.
 
 ## Unreleased
 
+* [telemetry-docs] Add a new service to provide telemetry documentation based
+  on Weaver
+  ([#2794](https://github.com/open-telemetry/opentelemetry-demo/pull/2794))
 * [accounting] fix memory leak with dbcontext
   ([#2876](https://github.com/open-telemetry/opentelemetry-demo/pull/2876))
 * [chore] Upgrade OTel Collector to v0.145.0 with :warning: breaking change:

Makefile

@@ -191,6 +191,7 @@ start:
 	@echo "Go to http://localhost:8080/grafana/ for the Grafana UI."
 	@echo "Go to http://localhost:8080/loadgen/ for the Load Generator UI."
 	@echo "Go to http://localhost:8080/feature/ to change feature flags."
+	@echo "Go to http://localhost:8080/telemetry/ for the Weaver generated telemetry documentation."
 
 .PHONY: start-minimal
 start-minimal:

docker-compose.yml

@@ -366,6 +366,8 @@ services:
       - FLAGD_PORT
       - FLAGD_UI_HOST
       - FLAGD_UI_PORT
+      - TELEMETRY_DOCS_HOST
+      - TELEMETRY_DOCS_PORT
     depends_on:
       frontend:
         condition: service_started
@@ -377,6 +379,8 @@ services:
         condition: service_started
       flagd-ui:
         condition: service_started
+      telemetry-docs:
+        condition: service_started
     dns_search: ""
 
   # image-provider
@@ -918,6 +922,29 @@ services:
       - "${PROMETHEUS_PORT}:${PROMETHEUS_PORT}"
     logging: *logging
 
+  # Telemetry Documentation
+  telemetry-docs:
+    image: ${IMAGE_NAME}:${DEMO_VERSION}-telemetry-docs
+    container_name: telemetry-docs
+    build:
+      context: ./
+      dockerfile: ${TELEMETRY_DOCS_DOCKERFILE}
+      cache_from:
+        - ${IMAGE_NAME}:${IMAGE_VERSION}-telemetry-docs
+    deploy:
+      resources:
+        limits:
+          memory: 100M
+    restart: unless-stopped
+    ports:
+      - "${TELEMETRY_DOCS_PORT}"
+    environment:
+      - TELEMETRY_DOCS_PORT
+      - OTEL_COLLECTOR_HOST
+      - OTEL_COLLECTOR_PORT_GRPC
+      - OTEL_SERVICE_NAME=telemetry-docs
+    logging: *logging
+
   # OpenSearch
   opensearch:
     container_name: opensearch

src/frontend-proxy/envoy.tmpl.yaml

@@ -51,6 +51,10 @@ static_resources:
                           redirect: { path_redirect: "/grafana/" }
                         - match: { prefix: "/grafana/" }
                           route: { cluster: grafana }
+                        - match: { path: "/telemetry" }
+                          redirect: { path_redirect: "/telemetry/" }
+                        - match: { prefix: "/telemetry/" }
+                          route: { cluster: telemetry-docs, prefix_rewrite: "/" }
                         - match: { prefix: "/images/" }
                           route: { cluster: image-provider, prefix_rewrite: "/" }
                         - match: { prefix: "/flagservice/" }
@@ -242,6 +246,18 @@ static_resources:
                     socket_address:
                       address: ${JAEGER_HOST}
                       port_value: ${JAEGER_UI_PORT}
+    - name: telemetry-docs
+      type: STRICT_DNS
+      lb_policy: ROUND_ROBIN
+      load_assignment:
+        cluster_name: telemetry-docs
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: ${TELEMETRY_DOCS_HOST}
+                      port_value: ${TELEMETRY_DOCS_PORT}
 admin:
   address:
     socket_address:

src/telemetry-docs/.dockerignore

@@ -0,0 +1,17 @@
+node_modules
+npm-debug.log
+.git
+.gitignore
+.DS_Store
+*.md
+!mkdocs.yml
+.env
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.coverage
+htmlcov
+dist
+build
+*.egg-info

src/telemetry-docs/Dockerfile

@@ -0,0 +1,56 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+# Two-stage build: Generate service-centric Markdown with Weaver, then serve with mkdocs
+
+# Stage 1: Generate Markdown files from telemetry schema using Weaver
+FROM docker.io/otel/weaver:v0.21.2 AS registry-builder
+
+WORKDIR /workspace
+
+# Copy the telemetry schema
+COPY telemetry-schema /workspace/telemetry-schema
+
+# Copy the Weaver templates
+COPY src/telemetry-docs/templates /workspace/templates
+
+# Generate service-centric pages and mkdocs.yml using Weaver
+RUN /weaver/weaver registry generate \
+    --registry=/workspace/telemetry-schema \
+    --templates=/workspace/templates \
+    markdown \
+    /workspace/docs
+
+# Generate fully resolved schema as JSON
+RUN /weaver/weaver registry resolve \
+    --registry=/workspace/telemetry-schema \
+    --format=json \
+    --output=/workspace/docs/schema.json
+
+# Stage 2: Build static site
+FROM python:3.14-slim-bookworm AS site-builder
+
+WORKDIR /app
+
+RUN pip install --no-cache-dir mkdocs mkdocs-material
+
+COPY src/telemetry-docs/mkdocs.yml /app/mkdocs-base.yml
+COPY --from=registry-builder /workspace/docs /app/docs
+
+RUN mv /app/docs/mkdocs.yml /app/mkdocs.yml && \
+    mkdocs build --clean
+
+# Stage 3: Serve with nginx (tiny!)
+FROM docker.io/nginxinc/nginx-unprivileged:1.29-alpine3.23-otel
+
+USER 101
+
+COPY --from=site-builder /app/site /static
+COPY src/telemetry-docs/nginx.conf.template /nginx.conf.template
+
+EXPOSE ${TELEMETRY_DOCS_PORT}
+
+STOPSIGNAL SIGQUIT
+
+# Start nginx
+CMD ["/bin/sh" , "-c" , "envsubst '$OTEL_COLLECTOR_HOST $OTEL_COLLECTOR_PORT_GRPC $OTEL_SERVICE_NAME $TELEMETRY_DOCS_PORT' < /nginx.conf.template > /etc/nginx/nginx.conf && exec nginx -g 'daemon off;'"]

src/telemetry-docs/README.md

@@ -0,0 +1,119 @@
+# Telemetry Documentation Service
+
+This service generates and hosts comprehensive documentation for the
+OpenTelemetry Demo's telemetry schema using
+[OpenTelemetry Weaver](https://github.com/open-telemetry/weaver),
+[MkDocs](https://www.mkdocs.org/), and
+[nginx with OpenTelemetry instrumentation](https://github.com/nginxinc/nginx-otel).
+
+## Overview
+
+The telemetry-docs service provides a web-based documentation interface that
+documents all custom attributes and metrics used across the OpenTelemetry Demo
+application. The documentation is automatically generated from the YAML schema
+definitions in the `telemetry-schema/` directory and served as a static site
+with full OpenTelemetry tracing.
+
+## Architecture
+
+The service uses a **3-stage Docker build** for optimal performance and observability:
+
+### Stage 1: Schema Generation (Weaver)
+
+- Uses the official `otel/weaver:v0.21.2` image
+- Reads the telemetry schema from `/telemetry-schema` directory
+- Generates service-centric Markdown documentation files
+- Generates fully resolved schema as JSON
+
+### Stage 2: Static Site Build (MkDocs)
+
+- Uses Python 3.14 slim-bookworm image
+- Installs MkDocs and Material theme
+- Builds static HTML site from generated Markdown
+- Optimizes assets for production delivery
+
+### Stage 3: Production Server (nginx + OpenTelemetry)
+
+- Uses `nginxinc/nginx-unprivileged:<version>-otel`
+- Serves pre-built static site
+- **Full OpenTelemetry instrumentation** with optimized configuration
+
+## OpenTelemetry Instrumentation
+
+The service includes production-ready OpenTelemetry tracing with:
+
+### Batch Configuration
+
+- **Interval**: 5s export frequency
+- **Batch size**: 256 spans per batch (optimized for static content)
+- **Batch count**: 2 pending batches per worker (reduced memory footprint)
+
+### Low-Cardinality Span Names
+
+Implements route parameterization to avoid high cardinality:
+
+- `/attributes/*.html` -> `GET /attributes/{business_domain}`
+- `/services/*.html` -> `GET /services/{service_name}`
+- `/index.html` -> `GET /index`
+- `/` -> `GET /`
+
+### Tracing Exclusions
+
+Static assets and health checks are excluded from tracing for **80-90%
+span volume reduction**:
+
+- Static files (CSS, JS, images, fonts)
+- Search indexes
+- Health check endpoint (`/status`)
+
+This follows
+[OpenTelemetry HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/)
+for optimal observability.
+
+## Usage
+
+### Running the telemetry-docs service
+
+The application can be run with the rest of the demo using the documented
+[docker compose or make commands](https://opentelemetry.io/docs/demo/#running-the-demo).
+
+### Accessing the Documentation
+
+Once the service is running, access the documentation at:
+<http://localhost:8080/telemetry>
+
+### Building the telemetry-docs service
+
+```bash
+docker compose build telemetry-docs
+```
+
+## Configuration
+
+### Environment Variables
+
+The service requires the following environment variables:
+
+- `TELEMETRY_DOCS_PORT` - Port for the nginx server (default: 8000)
+- `OTEL_COLLECTOR_HOST` - OpenTelemetry Collector hostname
+- `OTEL_COLLECTOR_PORT_GRPC` - OTel Collector gRPC port (default: 4317)
+- `OTEL_SERVICE_NAME` - Service name for telemetry (default: `telemetry-docs`)
+
+### nginx Configuration
+
+The service uses a templated nginx configuration (`nginx.conf.template`) with
+environment variable substitution. Key features:
+
+- **Static file serving** from `/static` directory
+- **OpenTelemetry module** for distributed tracing
+- **Cache headers** for static assets (1 year expiry)
+- **Health check endpoint** at `/status` (excluded from tracing)
+- **gzip compression** for efficient content delivery
+
+## References
+
+- [OpenTelemetry Weaver](https://github.com/open-telemetry/weaver)
+- [nginx OpenTelemetry Module](https://github.com/nginxinc/nginx-otel)
+- [OpenTelemetry HTTP Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/)
+- [MkDocs Documentation](https://www.mkdocs.org/)
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)

src/telemetry-docs/mkdocs.yml

@@ -0,0 +1,56 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+site_name: OpenTelemetry Demo Telemetry Schema
+site_description: Semantic conventions and telemetry schema for the OpenTelemetry Demo application
+site_author: OpenTelemetry Demo Contributors
+site_url: https://opentelemetry-demo.example.com/telemetry/
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - toc.follow
+    - content.code.copy
+
+plugins:
+  - search
+  - offline
+
+markdown_extensions:
+  - pymdownx.highlight:
+      use_pygments: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.details
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - tables
+  - toc:
+      permalink: true
+  - admonition
+  - attr_list
+
+extra:
+  version: 1.0.0
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/open-telemetry/opentelemetry-demo