Add a shared gateway tracing demo with Mongoose

README.md

@@ -62,12 +62,32 @@ cd playgrounds/pymongo
 ./scripts/run-app.sh    # or run the demo REST API
 ```
 
+## Shared telemetry demo
+
+[`shared/telemetry/`](shared/telemetry/) provides a reusable local stack with a
+tracing-enabled DocumentDB image, an OpenTelemetry Collector, and Jaeger. Start
+it once, then use any playground against the shared `documentdb-local`
+container.
+
+The Mongoose playground also includes optional application instrumentation and
+client-to-gateway trace-context propagation:
+
+```bash
+cd playgrounds/mongoose
+./scripts/run-telemetry-demo.sh
+```
+
+See the [shared telemetry guide](shared/telemetry/README.md) for image,
+configuration, and verification details.
+
 ## Repository Layout
 
 ```
 documentdb-playground/
 ├── README.md
 ├── LICENSE
+├── shared/
+│   └── telemetry/    # Collector + Jaeger + tracing-enabled DocumentDB stack
 └── playgrounds/
     ├── mongoose/     # Node.js + Mongoose ODM
     ├── mongodb-node/ # Node.js + MongoDB native driver

playgrounds/beanie/scripts/lib.sh

@@ -10,6 +10,7 @@ DOCUMENTDB_CONTAINER="${DOCUMENTDB_CONTAINER:-documentdb-local}"
 DOCUMENTDB_IMAGE="${DOCUMENTDB_IMAGE:-ghcr.io/documentdb/documentdb/documentdb-local:latest}"
 DOCUMENTDB_HOST="${DOCUMENTDB_HOST:-localhost}"
 DOCUMENTDB_PORT="${DOCUMENTDB_PORT:-10260}"
+DOCUMENTDB_CONTAINER_PORT=10260
 # Note: the emulator rejects some reserved names (e.g. "documentdb"); use a
 # distinct admin username.
 DOCUMENTDB_USERNAME="${DOCUMENTDB_USERNAME:-docdbadmin}"
@@ -22,6 +23,10 @@ build_uri() {
     echo "mongodb://${DOCUMENTDB_USERNAME}:${DOCUMENTDB_PASSWORD}@${DOCUMENTDB_HOST}:${DOCUMENTDB_PORT}/?tls=true&tlsAllowInvalidCertificates=true&directConnection=true"
 }
 
+build_container_uri() {
+    echo "mongodb://${DOCUMENTDB_USERNAME}:${DOCUMENTDB_PASSWORD}@localhost:${DOCUMENTDB_CONTAINER_PORT}/?tls=true&tlsAllowInvalidCertificates=true&directConnection=true"
+}
+
 # Wait until a TCP port accepts connections.
 # Args: <host> <port> [tries]
 wait_for_port() {
@@ -95,7 +100,7 @@ ensure_documentdb() {
 
 wait_for_documentdb() {
     local uri
-    uri="$(build_uri)"
+    uri="$(build_container_uri)"
     echo "Waiting for DocumentDB to accept connections ..."
 
     local i

playgrounds/mongodb-node/scripts/lib.sh

@@ -5,13 +5,18 @@ set -euo pipefail
 DOCUMENTDB_IMAGE="${DOCUMENTDB_IMAGE:-ghcr.io/documentdb/documentdb/documentdb-local:latest}"
 DOCUMENTDB_CONTAINER="${DOCUMENTDB_CONTAINER:-documentdb-local}"
 DOCUMENTDB_PORT="${DOCUMENTDB_PORT:-10260}"
+DOCUMENTDB_CONTAINER_PORT=10260
 DOCUMENTDB_USERNAME="${DOCUMENTDB_USERNAME:-docdbadmin}"
 DOCUMENTDB_PASSWORD="${DOCUMENTDB_PASSWORD:-Documentdb!Local1}"
 
 build_uri() {
     echo "mongodb://${DOCUMENTDB_USERNAME}:${DOCUMENTDB_PASSWORD}@localhost:${DOCUMENTDB_PORT}/?tls=true&tlsAllowInvalidCertificates=true&directConnection=true"
 }
 
+build_container_uri() {
+    echo "mongodb://${DOCUMENTDB_USERNAME}:${DOCUMENTDB_PASSWORD}@localhost:${DOCUMENTDB_CONTAINER_PORT}/?tls=true&tlsAllowInvalidCertificates=true&directConnection=true"
+}
+
 require_docker() {
     command -v docker >/dev/null || {
         echo "docker is required (start Docker Desktop / the Docker daemon first)" >&2
@@ -55,7 +60,7 @@ ensure_documentdb() {
 
 wait_for_documentdb() {
     local uri
-    uri="$(build_uri)"
+    uri="$(build_container_uri)"
     echo "Waiting for DocumentDB to accept connections ..."
 
     local attempt

playgrounds/mongoose/README.md

@@ -9,8 +9,10 @@ instance running in Docker. It includes:
   (`app/mongoose-crud-test.js`) that exercises connect, schema/index creation,
   insert, query, update, aggregation, unique-index enforcement, and delete.
 
-Everything runs on your machine: DocumentDB in a Docker container, the app and
-tests as local Node.js processes. No Kubernetes, no cloud, no image builds.
+The normal app and test paths run entirely on your machine: DocumentDB in a
+Docker container, with the app and tests as local Node.js processes. The
+optional tracing demo uses a published image containing the gateway tracing
+changes.
 
 > **What is Mongoose?** Mongoose is a **Node.js library** (an ODM, Object Data
 > Modeling layer), not a CLI tool or a server. Your application imports it to
@@ -21,7 +23,7 @@ tests as local Node.js processes. No Kubernetes, no cloud, no image builds.
 ## Prerequisites
 
 - **Docker** (Docker Desktop or a Docker daemon) — runs DocumentDB locally
-- **Node.js 18+** and **npm** — runs the app and test suite
+- **Node.js 18.19.x or 20.6+** and **npm** — runs the app and test suite
 
 That's it. The scripts pull the official `documentdb-local` image and start it
 for you.
@@ -79,6 +81,47 @@ Stop the database when you're done:
 ./scripts/stop-documentdb.sh
 ```
 
+## Trace the application and gateway
+
+The shared telemetry stack runs a tracing-enabled DocumentDB image, an
+OpenTelemetry Collector, and Jaeger. The Mongoose app emits HTTP and client
+spans, then puts the active W3C trace context in each supported database
+command's `comment` field. The gateway uses that context as the parent of
+`gateway.request`.
+
+```text
+HTTP request
+  -> Express server span
+       -> Mongoose client span
+            -> gateway.request
+                 -> gateway.process_request
+                      -> postgres.execute
+```
+
+Start the telemetry stack and Mongoose API. The stack pulls
+`ghcr.io/documentdb/documentdb/documentdb-local:trace-4fbbfcb8`
+automatically:
+
+```bash
+cd ../../playgrounds/mongoose
+./scripts/run-telemetry-demo.sh
+```
+
+In another terminal, generate API traffic and verify that Jaeger received one
+trace containing both the application and gateway services:
+
+```bash
+./scripts/verify-telemetry.sh
+```
+
+The verification helper also requires Python 3.
+
+The verification script prints a direct trace URL. The Jaeger UI is also
+available at <http://localhost:16686>.
+
+The normal `run-app.sh` and `run-test.sh` paths remain unchanged. Application
+tracing is enabled only when `OTEL_TRACES_ENABLED=true`.
+
 ## Trying the API
 
 With `./scripts/run-app.sh` running, the API is on `http://localhost:3000`:
@@ -106,6 +149,8 @@ curl -s http://localhost:3000/stats/genres | jq .
 | ----------------------------- | ------------------------------------------------------------------------------ |
 | `scripts/run-test.sh`         | Start DocumentDB (if needed) and run the Mongoose CRUD/compatibility suite.     |
 | `scripts/run-app.sh`          | Start DocumentDB (if needed) and run the Express + Mongoose API locally.        |
+| `scripts/run-telemetry-demo.sh` | Start the shared Collector, Jaeger, and DocumentDB stack, then run the traced API. |
+| `scripts/verify-telemetry.sh` | Generate API traffic and verify a connected application and gateway trace.      |
 | `scripts/start-documentdb.sh` | Start the local DocumentDB container and wait until it is ready.                |
 | `scripts/stop-documentdb.sh`  | Stop and remove the local DocumentDB container.                                |
 | `scripts/lib.sh`              | Shared helpers: container lifecycle, readiness wait, connection-string builder. |
@@ -184,6 +229,9 @@ Read by [`app/db.js`](app/db.js), [`app/server.js`](app/server.js), and
 | `TLS_INSECURE`                | `true`                                        | app + test | When `true`, accepts the gateway's self-signed cert. Set `false` for CA-verified TLS.|
 | `SERVER_SELECTION_TIMEOUT_MS` | `10000`                                       | app        | How long Mongoose waits to select a server before erroring.                         |
 | `PORT`                        | `3000`                                        | app        | Port the Express API listens on.                                                    |
+| `OTEL_TRACES_ENABLED`         | `false`                                       | app        | Enable HTTP, Mongoose client, and trace-context propagation instrumentation.        |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry default                         | app        | Collector endpoint used by the traced app.                                          |
+| `OTEL_SERVICE_NAME`           | SDK default                                   | app        | Application service name shown in Jaeger.                                           |
 
 ## Running the Test Suite Manually
 
@@ -254,12 +302,15 @@ mongoose/
 │   ├── package.json
 │   ├── db.js                    # Mongoose connection (DocumentDB options)
 │   ├── server.js                # Express REST API (/books, /health, /stats)
+│   ├── telemetry.js             # Optional OpenTelemetry setup + context propagation
 │   ├── models/book.js           # Example Mongoose schema/model
 │   └── mongoose-crud-test.js    # Standalone CRUD/compatibility test suite
 └── scripts/
     ├── lib.sh                   # Shared container lifecycle + connection-string builder
     ├── start-documentdb.sh      # Start the local DocumentDB container
     ├── stop-documentdb.sh       # Stop/remove the local DocumentDB container
     ├── run-app.sh               # Start DocumentDB + run the API locally
+    ├── run-telemetry-demo.sh    # Start shared telemetry + run the traced API
+    ├── verify-telemetry.sh      # Verify the joined app and gateway trace
     └── run-test.sh              # Start DocumentDB + run the test suite
 ```