Add opt-in OpenTelemetry tracing hooks

.env.example

@@ -2,6 +2,11 @@ NODE_ENV=development
 PORT=3000
 APP_URL=http://localhost:3001
 
+# Optional distributed tracing (OTLP/HTTP). See docs/TRACING.md.
+OTEL_TRACING_ENABLED=false
+# OTEL_SERVICE_NAME=stellar-tickets-backend
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+
 # postgresql://user:password@host:5432/db
 DATABASE_URL=
 

README.md

@@ -350,6 +350,8 @@ and [`docs/CACHING.md`](docs/CACHING.md).
 
 ## Environment
 
+Optional OpenTelemetry tracing is documented in [`docs/TRACING.md`](docs/TRACING.md).
+
 See [`.env.example`](.env.example) and the generated
 [environment variable table](docs/CONFIGURATION.md#environment-variables).
 The Stellar-specific ones are worth calling out:

docs/CONFIGURATION.md

@@ -15,6 +15,9 @@ run with a missing or malformed value. See
 | Variable | Type | Required | Default | Validated at boot | Description |
 | --- | --- | --- | --- | --- | --- |
 | `NODE_ENV` | `development \| test \| production` | **required** | `development` | yes | Which NestJS environment the app runs in. Drives logging verbosity and whether development-only behaviour is enabled.
+| `OTEL_TRACING_ENABLED` | `true \| false` | optional | `false` | yes | Opt in to HTTP/NestJS OpenTelemetry spans. Off unless literally 'true'. See docs/TRACING.md.
+| `OTEL_SERVICE_NAME` | string | optional | `stellar-tickets-backend` \* | yes | Service name attached to exported spans; defaults to stellar-tickets-backend.
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | string | optional | `http://localhost:4318/v1/traces` \* | yes | OTLP HTTP trace collector URL. Defaults to http://localhost:4318/v1/traces.
 | `PORT` | integer | **required** | `3000` | yes | TCP port the HTTP server binds. Match it to the `port` in docker-compose.yml when running the API in a container.
 | `MAX_ACTIVE_RESALE_LISTINGS_PER_USER` | integer | optional | `5` | yes | Soft cap on how many `ACTIVE` resale listings one seller may hold at once. Listing beyond it is rejected, not queued. See docs/RESALE_EXPIRY.md.
 | `DATABASE_URL` | string | **required** | — | yes | PostgreSQL connection string for the Prisma client. This is the single system of record; see docs/DATABASE.md.

docs/TRACING.md

@@ -0,0 +1,22 @@
+# Distributed tracing
+
+OpenTelemetry tracing is disabled by default. Set `OTEL_TRACING_ENABLED=true`
+to create HTTP, Express, and NestJS spans and export them using OTLP/HTTP.
+The exporter defaults to `http://localhost:4318/v1/traces`. Point it at your
+collector with `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`; optionally set
+`OTEL_SERVICE_NAME` (default `stellar-tickets-backend`).
+
+```env
+OTEL_TRACING_ENABLED=true
+OTEL_SERVICE_NAME=stellar-tickets-backend
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+```
+
+Start an OTLP-compatible collector before starting the API. In containers,
+`localhost` refers to the API container, so use your collector's service name.
+Incoming W3C `traceparent` headers are propagated and outgoing HTTP requests
+can join the same trace. Do not attach credentials, request bodies, or ticket
+data as span attributes.
+
+Set `OTEL_TRACING_ENABLED=false` (or leave it unset) to disable tracing. The
+SDK and instrumentations are then not loaded and no spans are exported.