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

.env

@@ -193,3 +193,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

CHANGELOG.md

@@ -30,6 +30,9 @@ the release.
   ([#2737](https://github.com/open-telemetry/opentelemetry-demo/pull/2737))
 * [collector] [dockerstats/receiver] Set API version to 1.44
   ([#2767](https://github.com/open-telemetry/opentelemetry-demo/pull/2767))
+* [telemetry-docs] Add a new service to provide telemetry documentation based
+  on Weaver
+  ([#2794](https://github.com/open-telemetry/opentelemetry-demo/pull/2794))
 
 ## 2.1.3
 

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
@@ -920,6 +924,26 @@ 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
+    logging: *logging
+
   # OpenSearch
   opensearch:
     container_name: opensearch

kubernetes/opentelemetry-demo.yaml

@@ -20144,3 +20144,65 @@ spec:
         - name: config-emptydir
           mountPath: /usr/share/opensearch/config/opensearch.yml
           subPath: opensearch.yml
+---
+# Source: opentelemetry-demo/templates/telemetry-docs.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: telemetry-docs
+  namespace: otel-demo
+  labels:
+    opentelemetry.io/name: telemetry-docs
+    app.kubernetes.io/component: telemetry-docs
+    app.kubernetes.io/name: telemetry-docs
+    app.kubernetes.io/version: "2.1.3"
+    app.kubernetes.io/part-of: opentelemetry-demo
+spec:
+  type: ClusterIP
+  ports:
+    - port: 8000
+      name: http
+      targetPort: 8000
+  selector:
+    opentelemetry.io/name: telemetry-docs
+---
+# Source: opentelemetry-demo/templates/telemetry-docs.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: telemetry-docs
+  namespace: otel-demo
+  labels:
+    opentelemetry.io/name: telemetry-docs
+    app.kubernetes.io/component: telemetry-docs
+    app.kubernetes.io/name: telemetry-docs
+    app.kubernetes.io/version: "2.1.3"
+    app.kubernetes.io/part-of: opentelemetry-demo
+spec:
+  replicas: 1
+  revisionHistoryLimit: 10
+  selector:
+    matchLabels:
+      opentelemetry.io/name: telemetry-docs
+  template:
+    metadata:
+      labels:
+        opentelemetry.io/name: telemetry-docs
+        app.kubernetes.io/component: telemetry-docs
+        app.kubernetes.io/name: telemetry-docs
+    spec:
+      serviceAccountName: opentelemetry-demo
+      containers:
+        - name: telemetry-docs
+          image: 'ghcr.io/open-telemetry/demo:2.1.3-telemetry-docs'
+          imagePullPolicy: IfNotPresent
+          ports:
+            - containerPort: 8000
+              name: http
+          resources:
+            limits:
+              memory: 100Mi
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 1000
+            runAsGroup: 1000

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 }
                         - 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,51 @@
+# 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 otel/weaver:latest 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: Serve documentation with mkdocs
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install mkdocs and theme
+RUN pip install --no-cache-dir mkdocs mkdocs-material
+
+# Copy base mkdocs configuration (inherited by generated mkdocs.yml)
+COPY src/telemetry-docs/mkdocs.yml /app/mkdocs-base.yml
+
+# Copy generated documentation
+COPY --from=registry-builder /workspace/docs /app/docs
+
+# Put mkdocs.yml with dynamic navigation into the app root
+RUN mv /app/docs/mkdocs.yml /app/mkdocs.yml
+
+# Expose port for mkdocs
+EXPOSE ${TELEMETRY_DOCS_PORT}
+
+# Serve documentation
+CMD ["sh", "-c", "mkdocs serve --dev-addr 0.0.0.0:${TELEMETRY_DOCS_PORT}"]

src/telemetry-docs/README.md

@@ -0,0 +1,56 @@
+# 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) and
+[MkDocs](https://www.mkdocs.org/).
+
+## 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.
+
+## Architecture
+
+The service uses a two-stage Docker build:
+
+### Stage 1: Weaver Builder
+
+- Uses the official `otel/weaver:latest` image
+- Reads the telemetry schema from `/telemetry-schema` directory
+- Generates Markdown documentation files
+
+### Stage 2: MkDocs Server
+
+- Uses Python 3.11 slim image
+- Installs MkDocs and Material theme
+- Copies the generated documentation from Stage 1
+- Serves the documentation on port 8000 as a live server
+
+## 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 new telemetry-docs
+
+```bash
+# Build the telemetry-docs image
+docker compose build telemetry-docs
+```
+
+## References
+
+- [OpenTelemetry Weaver](https://github.com/open-telemetry/weaver)
+- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/)
+- [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

src/telemetry-docs/templates/markdown/attribute_macros.j2

@@ -0,0 +1,45 @@
+{#- Attribute macros for Weaver templates -#}
+
+{#- Renders the type of an attribute -#}
+{% macro type(attribute) -%}
+{%- if attribute.type is mapping -%}
+{%- if attribute.type.members[0].value is string %}string{%- endif -%}
+{%- if attribute.type.members[0].value is int %}int{%- endif -%}
+{%- if attribute.type.members[0].value is float %}double{%- endif -%}
+{%- elif attribute.type == "template[boolean]" %}boolean
+{%- elif attribute.type == "template[int]" %}int
+{%- elif attribute.type == "template[double]" %}double
+{%- elif attribute.type == "template[string]" %}string
+{%- elif attribute.type == "template[boolean[]]" %}boolean[]
+{%- elif attribute.type == "template[int[]]" %}int[]
+{%- elif attribute.type == "template[double[]]" %}double[]
+{%- elif attribute.type == "template[string[]]" %}string[]
+{%- else %}{{ attribute.type | default('string') | trim }}{%- endif -%}
+{%- endmacro %}
+
+{% macro find_lineage(attr_id, lineage) %}{% if attr_id in lineage %}{{lineage[attr_id].source_group}}{% endif %}{% endmacro %}
+{% macro name_with_link(attribute, attribute_registry_base_url, lineage_attributes) %}[`{{name(attribute)}}`]({{attribute_registry_base_url}}/{{ find_lineage(attribute.name, lineage_attributes) | split_id | list | reject("eq", "registry")| first | kebab_case }}.md){% endmacro %}
+
+{#- Renders the name of an attribute -#}
+{% macro name(attribute) -%}
+{%- if attribute.type is startingwith("template[") %}{{ attribute.name }}.<key>
+{%- else %}{{ attribute.name }}{%- endif -%}
+{%- endmacro %}
+
+{#- Converts id to display name -#}
+{% macro display_name(group) -%}
+{%- if 'display_name' in group %}{{ group.display_name }}
+{%- else %}{{ group.id | replace("registry.", "") | replace(".", " ") | replace("_", " ") | title }} Attributes
+{%- endif -%}
+{%- endmacro %}
+
+{#- Humanize text by replacing underscores with spaces -#}
+{% macro humanize(text) -%}
+{{- text | replace('_', ' ') -}}
+{%- endmacro %}
+
+{#- Convert text to sentence case -#}
+{% macro sentence_case(text) -%}
+{{- text[:1] | upper }}{{ text[1:] | lower -}}
+{%- endmacro %}
+