@powerhousedao/switchboard 6.0.0-dev.24 → 6.0.0-dev.240

package/README.md

@@ -13,6 +13,7 @@ A powerful document-driven server that provides a unified API for managing and s
 - **HTTPS Support**: Built-in HTTPS server with custom certificates
 - **Profiling**: Integration with Pyroscope for performance monitoring
 - **Error Tracking**: Sentry integration for error monitoring and reporting
+- **Observability**: Unified OpenTelemetry tracing + metrics bootstrap, with optional Sentry APM bridging (same trace IDs in Tempo and Sentry)
 
 ## 📦 Installation
 
@@ -50,6 +51,7 @@ docker compose -f packages/reactor/docker-compose.yml up -d
 ```
 
 This starts:
+
 - PostgreSQL on port `5433` (mapped from container port 5432)
 - Adminer (database UI) on port `8080`
 
@@ -94,22 +96,21 @@ pnpm add -g @powerhousedao/switchboard
 
 ## 🏃‍♂️ Quick Start
 
-
 ## ⚙️ Configuration
 
 ### Environment Variables
 
-| Variable                     | Description                        | Default               |
-| ---------------------------- | ---------------------------------- | --------------------- |
-| `PORT`                       | Server port                        | `4001`                |
-| `DATABASE_URL`               | Database connection string         | `./.ph/drive-storage` |
-| `PH_REACTOR_DATABASE_URL`    | PostgreSQL URL (takes precedence)  | -                     |
-| `REDIS_URL`                  | Redis connection URL               | -                     |
-| `REDIS_TLS_URL`              | Redis TLS connection URL           | -                     |
-| `SENTRY_DSN`                 | Sentry DSN for error tracking      | -                     |
-| `SENTRY_ENV`                 | Sentry environment                 | -                     |
-| `PYROSCOPE_SERVER_ADDRESS`   | Pyroscope server address           | -                     |
-| `FEATURE_REACTORV2_ENABLED`  | Enable Reactor v2 subgraph feature | `false`               |
+| Variable                    | Description                        | Default               |
+| --------------------------- | ---------------------------------- | --------------------- |
+| `PORT`                      | Server port                        | `4001`                |
+| `DATABASE_URL`              | Database connection string         | `./.ph/drive-storage` |
+| `PH_REACTOR_DATABASE_URL`   | PostgreSQL URL (takes precedence)  | -                     |
+| `REDIS_URL`                 | Redis connection URL               | -                     |
+| `REDIS_TLS_URL`             | Redis TLS connection URL           | -                     |
+| `PYROSCOPE_SERVER_ADDRESS`  | Pyroscope server address           | -                     |
+| `FEATURE_REACTORV2_ENABLED` | Enable Reactor v2 subgraph feature | `false`               |
+
+See [Observability](#observability) below for Sentry and OpenTelemetry variables.
 
 ### Authentication Configuration
 
@@ -132,6 +133,47 @@ Switchboard supports multiple storage backends:
 - **PostgreSQL**: Persistent database storage
 - **Redis**: Caching layer (optional)
 
+### Observability
+
+Switchboard bootstraps Sentry and OpenTelemetry from a single module (`src/observability.mts`) that is imported as the very first thing in `src/index.mts`. The OpenTelemetry instrumentations (`http`, `express`, `pg`, `graphql`) register require-time hooks at load, so the import order must not be changed.
+
+What runs depends on which environment variables are set:
+
+- `SENTRY_DSN` set → Sentry error reporting is initialized.
+- `ENABLE_TRACING=true` or `NODE_ENV=production`, **and** at least one trace destination is configured (`TEMPO_ENDPOINT` or `SENTRY_DSN`) → OpenTelemetry tracing is initialized. Spans go to Tempo over OTLP HTTP if `TEMPO_ENDPOINT` is set, and/or to Sentry via `SentrySpanProcessor` if `SENTRY_DSN` is set. When both are set, the same trace IDs appear in Tempo and Sentry and cross-link in Grafana.
+- Tracing requested (prod or `ENABLE_TRACING=true`) but no destination configured → a warning is logged and tracing is **not** started. This avoids the cost of patching `http`/`express`/`pg`/`graphql` and generating spans only to drop them. Set `TEMPO_ENDPOINT` and/or `SENTRY_DSN` to enable.
+- `OTEL_EXPORTER_OTLP_ENDPOINT` set → metrics export to that OTLP HTTP endpoint via a periodic reader. Reactor metrics emitted by `@powerhousedao/opentelemetry-instrumentation-reactor` flow through the same global meter provider.
+
+If neither Sentry nor a tracing destination is configured, the module is a no-op and no exporters or instrumentations are registered.
+
+#### Environment Variables
+
+| Variable                      | Description                                                                                                                                                                  | Default                                             |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `SENTRY_DSN`                  | Sentry DSN. When unset, Sentry is disabled.                                                                                                                                  | -                                                   |
+| `SENTRY_ENV`                  | `environment` tag passed to `Sentry.init`.                                                                                                                                   | -                                                   |
+| `SENTRY_RELEASE`              | Release tag (must match the version uploaded by CI for source maps to resolve).                                                                                              | `v${npm_package_version}` if available              |
+| `SENTRY_TRACES_SAMPLE_RATE`   | APM sampling rate (0.0–1.0).                                                                                                                                                 | `0.1`                                               |
+| `ENABLE_TRACING`              | Set to `true` to request tracing outside production. Tracing only starts when a destination is also set.                                                                     | `false` (also requested when `NODE_ENV=production`) |
+| `NODE_ENV`                    | When `production`, tracing is requested automatically. Also exported as `deployment.environment` attribute.                                                                  | `development`                                       |
+| `OTEL_SERVICE_NAME`           | `service.name` resource attribute.                                                                                                                                           | `switchboard`                                       |
+| `TENANT_ID`                   | `tenant.id` resource attribute (used to slice traces by tenant in Grafana).                                                                                                  | `default`                                           |
+| `TEMPO_ENDPOINT`              | OTLP HTTP endpoint for trace export. When unset, OTLP trace export is disabled. In-cluster deploys typically set `http://tempo.monitoring.svc.cluster.local:4318/v1/traces`. | -                                                   |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP HTTP endpoint for metrics export. Metrics export is disabled when unset.                                                                                                | -                                                   |
+| `OTEL_METRIC_EXPORT_INTERVAL` | Metric export interval in milliseconds.                                                                                                                                      | `60000`                                             |
+
+#### Local Development
+
+Tracing is off by default outside production, so a bare `pnpm dev` does not need any of these set. To exercise the full pipeline locally, point `TEMPO_ENDPOINT` and `OTEL_EXPORTER_OTLP_ENDPOINT` at a local OTel collector (or Tempo + Prometheus) and run with `ENABLE_TRACING=true`:
+
+```bash
+ENABLE_TRACING=true \
+TEMPO_ENDPOINT=http://localhost:4318/v1/traces \
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/metrics \
+SENTRY_DSN=... \
+pnpm dev
+```
+
 ## 🐳 Docker Deployment
 
 ### Using Docker Compose
@@ -245,6 +287,7 @@ ph switchboard --db-path postgresql://user:pass@localhost:5432/db --migrate-stat
 #### Environment Variables for Migrations
 
 The migration commands check for a PostgreSQL URL in this order:
+
 1. `PH_REACTOR_DATABASE_URL`
 2. `DATABASE_URL`
 3. Config file (`powerhouse.config.json` -> `switchboard.database.url`)