@clubedge/create-clubedge-app 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.14.0
+
+- Default to Starter `v0.13.0`, which adds observability (`--observability otel|sentry`): request tracing and server error reporting through OpenTelemetry, to any OTLP collector, or Sentry, behind provider-neutral hooks in `@clubedge/core`. `--observability` needs no CLI code: it comes from the Starter's manifest.
+- Test an observability project in CI and in the release smoke test, and add the observability module in the change-modules job.
+
 ## 0.13.0
 
 - Default to Starter `v0.12.0`, which adds background jobs (`--jobs pg-boss`): jobs stored in the project's PostgreSQL, run by a worker inside the app server, with retries and schedules, and `/api/jobs/run` for serverless hosts. `--jobs` needs no CLI code: it comes from the Starter's manifest.

package/README.md

@@ -12,27 +12,27 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.13.0
+create-clubedge-app v0.14.0
         |
         v
-Clubedge Starter v0.12.0
-commit 445add73c3505cd8505faccb3b0b7061a29f5356
+Clubedge Starter v0.13.0
+commit 62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.13.0` | `clubedge-starter@v0.12.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.14.0` | `clubedge-starter@v0.13.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.12.0` tag is expected to resolve to commit
-`445add73c3505cd8505faccb3b0b7061a29f5356`. The CLI verifies this before
+The `v0.13.0` tag is expected to resolve to commit
+`62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.12.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.13.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 ## Requirements
 
@@ -85,7 +85,7 @@ Either way, the app lives in `apps/web` and uses the same shared packages, so th
 
 ### Choosing services
 
-Authentication, file storage, caching, email, payments, background jobs, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
+Authentication, file storage, caching, email, payments, background jobs, observability, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
@@ -95,6 +95,7 @@ Authentication, file storage, caching, email, payments, background jobs, local i
 | `--email`   | `smtp` (any provider, or a local inbox), `resend`, `none` | `smtp` |
 | `--payments` | `stripe`, `none` (needs an auth module) | `none` |
 | `--jobs` | `pg-boss`, `none` | `none` |
+| `--observability` | `otel` (OpenTelemetry, to any OTLP collector), `sentry`, `none` | `none` |
 | `--deploy`  | `docker` (any container host), `fly`, `railway`, `render`, `vercel`, `netlify` | `docker` |
 | `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
 
@@ -140,7 +141,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.12.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.13.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -157,7 +158,7 @@ pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add aut
 pnpm dlx @clubedge/create-clubedge-app remove storage
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.12.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.13.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -208,7 +209,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.12.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.13.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.12.0",
-    "starterCommit": "445add73c3505cd8505faccb3b0b7061a29f5356"
+    "starterRef": "v0.13.0",
+    "starterCommit": "62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -68,6 +68,22 @@ JOBS_WORKER=
 CRON_SECRET=
 # clubedge:end
 
+# clubedge:if observability=otel
+# OpenTelemetry: where traces and error logs go over OTLP/HTTP, such as a collector, Grafana
+# Cloud, or Honeycomb. Empty sends nothing. Headers are key=value pairs separated by commas.
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_EXPORTER_OTLP_HEADERS=
+OTEL_SERVICE_NAME=
+# clubedge:end
+
+# clubedge:if observability=sentry
+# Sentry (https://sentry.io): the DSN from the project's Client Keys settings. Empty sends nothing.
+# The traces sample rate is the share of requests traced, from 0 to 1 (default 0.1).
+SENTRY_DSN=
+SENTRY_ENVIRONMENT=
+SENTRY_TRACES_SAMPLE_RATE=
+# clubedge:end
+
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/README.md

@@ -29,6 +29,8 @@ This repository contains the same application for two frameworks, Next.js (`apps
 - Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
 - Subscriptions with Stripe Checkout and the customer portal, kept in sync by verified webhooks, behind a provider-neutral payments interface. <!-- clubedge:only payments=stripe -->
 - Background jobs with retries and schedules, stored in PostgreSQL by pg-boss and run by a worker inside the app server, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=pg-boss -->
+- Server error reporting and request tracing with OpenTelemetry, to any OTLP collector, behind a provider-neutral observability interface. <!-- clubedge:only observability=otel -->
+- Server error reporting and request tracing with Sentry, behind a provider-neutral observability interface. <!-- clubedge:only observability=sentry -->
 - Zod environment validation, security headers, structured errors, and `/api/health`.
 - Docker support, GitHub Actions CI, Vitest, Playwright, ESLint, and Prettier.
 - A production image that includes its own migrator (`node /app/migrate.mjs`), for running migrations before each release.
@@ -227,6 +229,9 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/payments-stripe/`: Stripe payment provider <!-- clubedge:only payments=stripe -->
 - `packages/jobs/`: `JobQueue` interface, job definitions, and an in-memory queue for tests <!-- clubedge:only jobs!=none -->
 - `packages/jobs-pg-boss/`: pg-boss job queue <!-- clubedge:only jobs=pg-boss -->
+- `packages/observability/`: `ObservabilityProvider` interface and an in-memory provider for tests <!-- clubedge:only observability!=none -->
+- `packages/observability-otel/`: OpenTelemetry provider (OTLP/HTTP traces and error logs) <!-- clubedge:only observability=otel -->
+- `packages/observability-sentry/`: Sentry provider <!-- clubedge:only observability=sentry -->
 - `packages/ui/`: shared shadcn/ui components, utilities, and global theme styles
 - `.github/`: CI workflow, issue forms, and pull request template
 - `SETUP.md`, `CONTRIBUTING.md`, `SECURITY.md`: setup, contribution, and security guides

package/template/SETUP.md

@@ -47,6 +47,8 @@ The variables are:
 - `RESEND_API_KEY` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=resend -->
 - `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, and `STRIPE_PRICE_<PLAN>` (for payments): see [Payments](#payments). <!-- clubedge:only payments=stripe -->
 - `JOBS_WORKER` and `CRON_SECRET` (optional): see [Background jobs](#background-jobs). <!-- clubedge:only jobs=pg-boss -->
+- `OTEL_EXPORTER_OTLP_ENDPOINT` (to send traces and errors): see [Observability](#observability). <!-- clubedge:only observability=otel -->
+- `SENTRY_DSN` (to send errors and traces): see [Observability](#observability). <!-- clubedge:only observability=sentry -->
 - `STORAGE_*` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=s3 -->
 - `SUPABASE_STORAGE_BUCKET` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=supabase -->
 
@@ -264,6 +266,38 @@ Where no server keeps running, as on Vercel and Netlify, there is no worker: `JO
 
 Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`. To use another queue, implement that interface in a new package and return it from `apps/web/src/server/jobs.ts`; job definitions, the routes, and the jobs card stay the same.
 
+<!-- clubedge:end -->
+<!-- clubedge:if observability!=none -->
+
+## Observability
+
+Server errors and traces go to the tool you chose. Errors that escape a page, route, server action, or server function are sent with the request's method and path, and so are errors the app handles and reports with `reportError` from `@clubedge/core`, such as a failed webhook, email, or background job. Every request is traced, and so are calls through the email, storage, and payments composition roots, as spans such as `email.send` and `storage.upload`. Wrap your own work with `traced("name", () => work())` from `@clubedge/core`. Until the tool is configured nothing is sent, and errors keep going to the server log.
+
+<!-- clubedge:end -->
+<!-- clubedge:if observability=otel -->
+
+Set `OTEL_EXPORTER_OTLP_ENDPOINT` to an OpenTelemetry collector or to a vendor's OTLP/HTTP endpoint (Grafana Cloud, Honeycomb, Datadog, and others accept it), with any API key in `OTEL_EXPORTER_OTLP_HEADERS` as `key=value` pairs. Traces go to `/v1/traces` and errors to `/v1/logs` as error log records, and each error is also recorded on the span it happened in. `OTEL_SERVICE_NAME` defaults to the project's service id. The spans Next.js and pg-boss create join the same traces. <!-- clubedge:only framework=next -->
+Set `OTEL_EXPORTER_OTLP_ENDPOINT` to an OpenTelemetry collector or to a vendor's OTLP/HTTP endpoint (Grafana Cloud, Honeycomb, Datadog, and others accept it), with any API key in `OTEL_EXPORTER_OTLP_HEADERS` as `key=value` pairs. Traces go to `/v1/traces` and errors to `/v1/logs` as error log records, and each error is also recorded on the span it happened in. `OTEL_SERVICE_NAME` defaults to the project's service id. <!-- clubedge:only framework=tanstack-start -->
+
+To see traces during development, run [Jaeger](https://www.jaegertracing.io), set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`, and open http://localhost:16686:
+
+```sh
+docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest
+```
+
+<!-- clubedge:end -->
+<!-- clubedge:if observability=sentry -->
+
+Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` to its DSN. `SENTRY_TRACES_SAMPLE_RATE` is the share of requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. The spans Next.js and pg-boss create join the same traces. <!-- clubedge:only framework=next -->
+Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` to its DSN. `SENTRY_TRACES_SAMPLE_RATE` is the share of requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. <!-- clubedge:only framework=tanstack-start -->
+
+<!-- clubedge:end -->
+<!-- clubedge:if observability!=none -->
+
+Only server-side errors are reported; errors in the browser are not. On Vercel and Netlify, a function can stop right after it responds, so spans still waiting in a batch at that moment can be lost.
+
+Observability goes through the provider-neutral `ObservabilityProvider` interface in `packages/observability` and the telemetry hooks in `@clubedge/core`. To use another tool, implement that interface in a new package and install it from `apps/web/src/server/observability.ts`; error reports and spans across the app stay the same.
+
 <!-- clubedge:end -->
 <!-- clubedge:if storage!=none -->
 
@@ -404,6 +438,8 @@ Production needs these variables:
 - `STRIPE_SECRET_KEY` (live mode), `STRIPE_WEBHOOK_SECRET` from the production webhook endpoint, and `STRIPE_PRICE_<PLAN>` for each plan. <!-- clubedge:only payments=stripe -->
 - `REDIS_URL`, when you run more than one instance. <!-- clubedge:only cache=redis -->
 - `CRON_SECRET`, where no worker runs and a scheduler calls `/api/jobs/run`. <!-- clubedge:only jobs=pg-boss -->
+- `OTEL_EXPORTER_OTLP_ENDPOINT`, and `OTEL_EXPORTER_OTLP_HEADERS` if your collector needs a key. <!-- clubedge:only observability=otel -->
+- `SENTRY_DSN`, and `SENTRY_ENVIRONMENT` to tell environments apart. <!-- clubedge:only observability=sentry -->
 - The `STORAGE_*` variables for your S3-compatible bucket. <!-- clubedge:only storage=s3 -->
 - `SUPABASE_STORAGE_BUCKET`. <!-- clubedge:only storage=supabase -->
 

package/template/apps/start/.env.example

@@ -70,6 +70,22 @@ JOBS_WORKER=
 CRON_SECRET=
 # clubedge:end
 
+# clubedge:if observability=otel
+# OpenTelemetry: where traces and error logs go over OTLP/HTTP, such as a collector, Grafana
+# Cloud, or Honeycomb. Empty sends nothing. Headers are key=value pairs separated by commas.
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_EXPORTER_OTLP_HEADERS=
+OTEL_SERVICE_NAME=
+# clubedge:end
+
+# clubedge:if observability=sentry
+# Sentry (https://sentry.io): the DSN from the project's Client Keys settings. Empty sends nothing.
+# The traces sample rate is the share of requests traced, from 0 to 1 (default 0.1).
+SENTRY_DSN=
+SENTRY_ENVIRONMENT=
+SENTRY_TRACES_SAMPLE_RATE=
+# clubedge:end
+
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -24,6 +24,9 @@
     "@clubedge/email-smtp": "workspace:*",
     "@clubedge/jobs": "workspace:*",
     "@clubedge/jobs-pg-boss": "workspace:*",
+    "@clubedge/observability": "workspace:*",
+    "@clubedge/observability-otel": "workspace:*",
+    "@clubedge/observability-sentry": "workspace:*",
     "@clubedge/payments": "workspace:*",
     "@clubedge/payments-stripe": "workspace:*",
     "@clubedge/storage": "workspace:*",

package/template/apps/start/src/nitro/plugins/observability.ts

@@ -0,0 +1,10 @@
+import { definePlugin } from "nitro";
+import { startObservability } from "@/server/observability";
+
+/** Starts error reporting and tracing with the server, and sends what is buffered when it stops. */
+export default definePlugin((nitroApp) => {
+  const provider = startObservability();
+  nitroApp.hooks.hook("close", async () => {
+    await provider?.flush();
+  });
+});

package/template/apps/start/src/routes/api/webhooks/payments.ts

@@ -1,5 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { getBilling, isPaymentsConfigured, WebhookVerificationError } from "@/server/payments";
+import { reportError } from "@clubedge/core";
 
 /**
  * The payment provider's webhook. The body is read as raw text, because the signature covers
@@ -22,7 +23,7 @@ export const Route = createFileRoute("/api/webhooks/payments")({
           if (error instanceof WebhookVerificationError) {
             return Response.json({ error: "Invalid signature." }, { status: 400 });
           }
-          console.error("Payment webhook failed", error);
+          reportError(error, { message: "Payment webhook failed" });
           return Response.json({ error: "Webhook failed." }, { status: 500 });
         }
       },

package/template/apps/start/src/server/auth-forms.ts

@@ -1,6 +1,6 @@
 import "@tanstack/react-start/server-only";
 import { z } from "zod";
-import { getClientIp, safeRedirectPath } from "@clubedge/core";
+import { getClientIp, safeRedirectPath, reportError } from "@clubedge/core";
 import { getAppUrl } from "@/env/server";
 import { loginUrl } from "@/lib/login-url";
 import { getAuth, isAuthConfigured } from "./auth";
@@ -49,7 +49,7 @@ async function isRateLimited(request: Request, action: "sign-in" | "sign-up" | "
     return !result.success;
   } catch (error) {
     // Fail open: an unavailable limiter backend should not lock every user out.
-    console.error("Rate limiter unavailable", error);
+    reportError(error, { message: "Rate limiter unavailable" });
     return false;
   }
 }
@@ -142,7 +142,7 @@ export async function handleResetPassword(request: Request): Promise<Response> {
     // A Supabase reset link signed the user in; sign out so the new password is used next.
     await auth.signOut();
   } catch (error) {
-    console.error("Sign-out after password reset failed", error);
+    reportError(error, { message: "Sign-out after password reset failed" });
   }
   return seeOther(loginUrl({ notice: "password-updated" }));
 }
@@ -152,7 +152,7 @@ export async function handleSignOut(): Promise<Response> {
   try {
     await getAuth().signOut();
   } catch (error) {
-    console.error("Sign-out failed", error);
+    reportError(error, { message: "Sign-out failed" });
   }
   return seeOther("/login");
 }

package/template/apps/start/src/server/auth.ts

@@ -1,7 +1,7 @@
 import "@tanstack/react-start/server-only";
 import type { AuthProvider, AuthUser } from "@clubedge/auth";
 import { createSupabaseAuth, createSupabaseServerClient } from "@clubedge/auth-supabase";
-import { AppError } from "@clubedge/core";
+import { AppError, reportError } from "@clubedge/core";
 import { getSupabaseAuthEnv } from "@/env/auth";
 import { requestCookieStore } from "./cookies";
 
@@ -34,7 +34,7 @@ export async function refreshAuthSession(): Promise<void> {
     await getAuth().refreshSession();
   } catch (error) {
     // Pages still render; protected handlers re-check the user and reject when needed.
-    console.error("Session refresh failed", error);
+    reportError(error, { message: "Session refresh failed" });
   }
 }
 

package/template/apps/start/src/server/email.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { createConsoleEmail, type EmailProvider } from "@clubedge/email";
 import { createSmtpEmail } from "@clubedge/email-smtp";
 import { optional, parseEnv } from "@/env/server";
+import { withSpans } from "@clubedge/core";
 
 export type { EmailMessage, EmailProvider } from "@clubedge/email";
 
@@ -34,6 +35,6 @@ function resolveProvider(): EmailProvider {
 }
 
 /** The configured email provider, resolved on first use so imports stay side-effect free. */
-export const email: EmailProvider = {
+export const email: EmailProvider = withSpans("email", {
   send: (message) => resolveProvider().send(message),
-};
+});

package/template/apps/start/src/server/jobs.functions.ts

@@ -2,6 +2,7 @@ import { createServerFn } from "@tanstack/react-start";
 import { sampleJob } from "@/jobs";
 import { getJobs, isWorkerEnabled } from "./jobs";
 import { sampleJobRequester } from "./jobs-forms";
+import { reportError } from "@clubedge/core";
 
 /** What the dashboard's jobs card shows; serializable, so it can cross to the browser. */
 export const getJobsStatus = createServerFn({ method: "GET" }).handler(async () => {
@@ -21,7 +22,7 @@ export const getJobsStatus = createServerFn({ method: "GET" }).handler(async ()
       })),
     };
   } catch (error) {
-    console.error("Background jobs: could not list recent jobs.", error);
+    reportError(error, { message: "Background jobs: could not list recent jobs." });
     return { worker, jobs: null };
   }
 });

package/template/apps/start/src/server/jobs.ts

@@ -4,6 +4,7 @@ import type { JobQueue } from "@clubedge/jobs";
 import { createPgBossJobs } from "@clubedge/jobs-pg-boss";
 import { jobs } from "@/jobs";
 import { getServerEnv, optional, parseEnv } from "@/env/server";
+import { reportError } from "@clubedge/core";
 
 export type { JobRecord } from "@clubedge/jobs";
 
@@ -41,6 +42,11 @@ export function getJobs(): JobQueue {
     jobs,
     worker: isWorkerEnabled(),
     maxConnections: env.NODE_ENV === "production" ? 4 : 2,
+    onError: (error, context) =>
+      reportError(error, {
+        message: context ? `Background job "${context.job}" failed` : "Background jobs error",
+        attributes: context,
+      }),
   });
   return globalForJobs.clubedgeJobs;
 }
@@ -52,7 +58,9 @@ export function startJobsWorker() {
     getJobs()
       .startWorker()
       .catch((error: unknown) => {
-        console.error("Background jobs: the worker could not start, retrying in 5 seconds.", error);
+        reportError(error, {
+          message: "Background jobs: the worker could not start, retrying in 5 seconds.",
+        });
         setTimeout(start, 5_000).unref();
       });
   void start();

package/template/apps/start/src/server/observability.ts

@@ -0,0 +1,36 @@
+import "@tanstack/react-start/server-only";
+import { z } from "zod";
+import { setTelemetry } from "@clubedge/core";
+import type { ObservabilityProvider } from "@clubedge/observability";
+import { createOtelObservability, parseOtlpHeaders } from "@clubedge/observability-otel";
+import { siteConfig } from "@/config/site";
+import { optional, parseEnv } from "@/env/server";
+
+// OpenTelemetry: traces and error logs over OTLP/HTTP to any collector. Without an endpoint,
+// nothing is sent and errors keep going to the server log.
+const observabilityEnvSchema = z.object({
+  OTEL_EXPORTER_OTLP_ENDPOINT: optional(z.url()),
+  OTEL_EXPORTER_OTLP_HEADERS: optional(z.string()),
+  OTEL_SERVICE_NAME: optional(z.string()),
+});
+
+const globalForObservability = globalThis as typeof globalThis & {
+  clubedgeObservability?: ObservabilityProvider | null;
+};
+
+/** Installs the provider once per process; called when the server starts. */
+export function startObservability(): ObservabilityProvider | null {
+  if (globalForObservability.clubedgeObservability !== undefined)
+    return globalForObservability.clubedgeObservability;
+  const env = parseEnv(observabilityEnvSchema, "Observability");
+  const provider = env.OTEL_EXPORTER_OTLP_ENDPOINT
+    ? createOtelObservability({
+        endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT,
+        headers: parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS),
+        serviceName: env.OTEL_SERVICE_NAME || siteConfig.serviceId,
+      })
+    : null;
+  if (provider) setTelemetry(provider);
+  globalForObservability.clubedgeObservability = provider;
+  return provider;
+}

package/template/apps/start/src/server/payments.ts

@@ -1,5 +1,6 @@
 import "@tanstack/react-start/server-only";
 import { z } from "zod";
+import { withSpans } from "@clubedge/core";
 import { createBilling, type Billing } from "@clubedge/payments";
 import { createStripePayments } from "@clubedge/payments-stripe";
 import { plans } from "@/config/plans";
@@ -47,14 +48,17 @@ export function getBilling(): Billing {
     throw new Error(
       "Payments are not configured: set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET.",
     );
-  billing = createBilling({
-    db: getDb(),
-    provider: createStripePayments({
-      secretKey: env.secretKey,
-      webhookSecret: env.webhookSecret,
-      prices: prices(),
-      apiBase: env.STRIPE_API_BASE,
+  billing = withSpans(
+    "payments",
+    createBilling({
+      db: getDb(),
+      provider: createStripePayments({
+        secretKey: env.secretKey,
+        webhookSecret: env.webhookSecret,
+        prices: prices(),
+        apiBase: env.STRIPE_API_BASE,
+      }),
     }),
-  });
+  );
   return billing;
 }

package/template/apps/start/src/server/storage.ts

@@ -6,6 +6,7 @@ import { createS3Storage } from "@clubedge/storage-s3";
 import { createFileSystemStorage } from "@clubedge/storage/file-system";
 // clubedge:end
 import { optional, parseEnv } from "@/env/server";
+import { withSpans } from "@clubedge/core";
 
 export type { SignedUrlOptions, StorageProvider, UploadInput } from "@clubedge/storage";
 
@@ -46,10 +47,10 @@ function resolveProvider(): StorageProvider {
 }
 
 /** The configured storage provider, resolved on first use so imports stay side-effect free. */
-export const storage: StorageProvider = {
+export const storage: StorageProvider = withSpans("storage", {
   upload: (input) => resolveProvider().upload(input),
   download: (key) => resolveProvider().download(key),
   delete: (key) => resolveProvider().delete(key),
   exists: (key) => resolveProvider().exists(key),
   getSignedUrl: (key, options) => resolveProvider().getSignedUrl(key, options),
-};
+});

package/template/apps/start/src/server/users.ts

@@ -2,6 +2,7 @@ import "@tanstack/react-start/server-only";
 import type { AuthUser } from "@clubedge/auth";
 import { ensureUserId, upsertUserProfile } from "@clubedge/db";
 import { getDb } from "./db";
+import { reportError } from "@clubedge/core";
 
 /**
  * Keeps the app-owned users row in step with the identity provider. Failures are logged
@@ -12,7 +13,7 @@ export async function ensureUserProfile(user: AuthUser | null): Promise<void> {
   try {
     await upsertUserProfile(getDb(), { authUserId: user.id, email: user.email });
   } catch (error) {
-    console.error("Could not sync the user profile", error);
+    reportError(error, { message: "Could not sync the user profile" });
   }
 }
 

package/template/apps/start/src/server/variants/auth.better-auth.ts

@@ -8,7 +8,7 @@ import {
 } from "@clubedge/auth-better-auth";
 import { siteConfig } from "@/config/site";
 import { authEmailSender } from "@/server/auth-email";
-import { AppError } from "@clubedge/core";
+import { AppError, reportError } from "@clubedge/core";
 import { getBetterAuthEnv } from "@/env/auth";
 import { requestCookieStore } from "@/server/cookies";
 import { getDb } from "@/server/db";
@@ -47,7 +47,7 @@ export async function refreshAuthSession(): Promise<void> {
     await getAuth().refreshSession();
   } catch (error) {
     // Pages still render; protected handlers re-check the user and reject when needed.
-    console.error("Session refresh failed", error);
+    reportError(error, { message: "Session refresh failed" });
   }
 }
 

package/template/apps/start/src/server/variants/email.resend.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { createConsoleEmail, type EmailProvider } from "@clubedge/email";
 import { createResendEmail } from "@clubedge/email-resend";
 import { optional, parseEnv } from "@/env/server";
+import { withSpans } from "@clubedge/core";
 
 export type { EmailMessage, EmailProvider } from "@clubedge/email";
 
@@ -34,6 +35,6 @@ function resolveProvider(): EmailProvider {
 }
 
 /** The configured email provider, resolved on first use so imports stay side-effect free. */
-export const email: EmailProvider = {
+export const email: EmailProvider = withSpans("email", {
   send: (message) => resolveProvider().send(message),
-};
+});

package/template/apps/start/src/server/variants/observability.sentry.ts

@@ -0,0 +1,42 @@
+import "@tanstack/react-start/server-only";
+import { z } from "zod";
+import { setTelemetry } from "@clubedge/core";
+import type { ObservabilityProvider } from "@clubedge/observability";
+import { createSentryObservability } from "@clubedge/observability-sentry";
+import { optional, parseEnv } from "@/env/server";
+
+// Sentry: server errors and traces. Without a DSN, nothing is sent and errors keep going to the
+// server log.
+const observabilityEnvSchema = z.object({
+  SENTRY_DSN: optional(z.url()),
+  SENTRY_ENVIRONMENT: optional(z.string()),
+  SENTRY_RELEASE: optional(z.string()),
+  // The share of requests traced, from 0 to 1; an empty value keeps the default, 0.1.
+  SENTRY_TRACES_SAMPLE_RATE: optional(
+    z.string().regex(/^(0(\.\d+)?|1(\.0+)?)$/, "a number from 0 to 1"),
+  ),
+});
+
+const globalForObservability = globalThis as typeof globalThis & {
+  clubedgeObservability?: ObservabilityProvider | null;
+};
+
+/** Installs the provider once per process; called when the server starts. */
+export function startObservability(): ObservabilityProvider | null {
+  if (globalForObservability.clubedgeObservability !== undefined)
+    return globalForObservability.clubedgeObservability;
+  const env = parseEnv(observabilityEnvSchema, "Observability");
+  const provider = env.SENTRY_DSN
+    ? createSentryObservability({
+        dsn: env.SENTRY_DSN,
+        environment: env.SENTRY_ENVIRONMENT || process.env.NODE_ENV,
+        release: env.SENTRY_RELEASE || undefined,
+        tracesSampleRate: env.SENTRY_TRACES_SAMPLE_RATE
+          ? Number(env.SENTRY_TRACES_SAMPLE_RATE)
+          : undefined,
+      })
+    : null;
+  if (provider) setTelemetry(provider);
+  globalForObservability.clubedgeObservability = provider;
+  return provider;
+}

package/template/apps/start/src/server/variants/storage.supabase.ts

@@ -4,6 +4,7 @@ import type { StorageProvider } from "@clubedge/storage";
 import { createSupabaseStorage } from "@clubedge/storage-supabase";
 import { optional, parseEnv } from "@/env/server";
 import { getSupabaseClient } from "@/server/auth";
+import { withSpans } from "@clubedge/core";
 
 export type { SignedUrlOptions, StorageProvider, UploadInput } from "@clubedge/storage";
 
@@ -26,10 +27,10 @@ function resolveProvider(): StorageProvider {
 }
 
 /** The configured storage provider, resolved on first use so imports stay side-effect free. */
-export const storage: StorageProvider = {
+export const storage: StorageProvider = withSpans("storage", {
   upload: (input) => resolveProvider().upload(input),
   download: (key) => resolveProvider().download(key),
   delete: (key) => resolveProvider().delete(key),
   exists: (key) => resolveProvider().exists(key),
   getSignedUrl: (key, options) => resolveProvider().getSignedUrl(key, options),
-};
+});