feat: CATALYST-676 add generic otel setup (#2708)

Co-authored-by: Chancellor Clark <[email protected]>

Author: jordanarldt

.changeset/silent-pillows-sip.md

@@ -0,0 +1,9 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Adds OpenTelemetry instrumentation for Catalyst, enabling the collection of spans for Catalyst storefronts.
+
+### Migration
+
+Change is new code only, so just copy over `/core/instrumentation.ts` and `core/lib/otel/tracers.ts`.

core/.env.example

@@ -30,3 +30,16 @@ TURBO_REMOTE_CACHE_SIGNATURE_KEY=
 # https://nextjs.org/docs/app/building-your-application/caching#data-cache
 # This sets a sensible revalidation target for cached requests
 DEFAULT_REVALIDATE_TARGET=3600
+
+# OpenTelemetry Configuration (Optional)
+# See OPENTELEMETRY.md for detailed setup and usage instructions
+# See https://nextjs.org/docs/app/guides/open-telemetry for Next.js guide
+
+# Set a custom service name for your traces (defaults to 'next-app')
+# OTEL_SERVICE_NAME=catalyst-storefront
+
+# Enable verbose tracing to see all spans (useful for debugging, increases data volume)
+# NEXT_OTEL_VERBOSE=1
+
+# Disable automatic fetch instrumentation (not recommended unless using custom instrumentation)
+# NEXT_OTEL_FETCH_DISABLED=1

core/instrumentation.ts

@@ -0,0 +1,58 @@
+import { registerOTel } from '@vercel/otel';
+
+// eslint-disable-next-line valid-jsdoc
+/**
+ * Initializes OpenTelemetry instrumentation for the Next.js application.
+ *
+ * This function is automatically called by Next.js during application startup
+ * to set up distributed tracing and observability.
+ *
+ * @see https://nextjs.org/docs/app/guides/instrumentation
+ * @see https://nextjs.org/docs/app/guides/open-telemetry
+ *
+ * Configuration:
+ * - Uses @vercel/otel for simplified OpenTelemetry setup
+ * - Automatically instruments Next.js internals (requests, rendering, fetches)
+ * - Service name is read from OTEL_SERVICE_NAME environment variable
+ * - If OTEL_SERVICE_NAME is not set, defaults to 'next-app'
+ *
+ * Environment Variables:
+ * - OTEL_SERVICE_NAME: Custom service name (e.g., 'catalyst-storefront')
+ * - NEXT_OTEL_VERBOSE: Set to '1' to see all spans (default: essential spans only)
+ * - NEXT_OTEL_FETCH_DISABLED: Set to '1' to disable automatic fetch instrumentation
+ *
+ * What's automatically instrumented:
+ * - All HTTP requests (route, method, status)
+ * - App Router page and layout rendering
+ * - API route handler execution
+ * - fetch() calls to external APIs
+ * - Metadata generation (generateMetadata)
+ *
+ * Custom instrumentation:
+ * Import the tracer from ~/lib/otel/tracer to create custom spans:
+ *
+ * @example
+ * import { tracer } from '~/lib/otel/tracer';
+ *
+ * export async function myFunction() {
+ *   return await tracer.startActiveSpan('myFunction', async (span) => {
+ *     try {
+ *       const result = await doWork();
+ *       span.setAttribute('result.count', result.length);
+ *       return result;
+ *     } finally {
+ *       span.end();
+ *     }
+ *   });
+ * }
+ *
+ * For more information about using OpenTelemetry in Catalyst, see:
+ * - OPENTELEMETRY.md in this directory
+ * - Official Next.js guide: https://nextjs.org/docs/app/guides/open-telemetry
+ */
+export function register() {
+  // Service name is pulled from the OTEL_SERVICE_NAME env var.
+  // If you wish to manually set it, you can remove the env var and set it here:
+  // registerOTel({ serviceName: 'catalyst-storefront' });
+  registerOTel();
+}

core/lib/otel/tracer.ts

@@ -0,0 +1,93 @@
+import { trace } from '@opentelemetry/api';
+
+/**
+ * OpenTelemetry tracer for creating custom spans in the Catalyst application.
+ *
+ * Use this tracer to instrument important operations and track their performance.
+ * Spans created with this tracer will appear in your observability dashboard
+ * nested under the appropriate HTTP request trace.
+ *
+ * @see https://nextjs.org/docs/app/guides/open-telemetry#custom-spans
+ * @see OPENTELEMETRY.md for detailed usage guide
+ *
+ * @example Basic usage
+ * import { tracer } from '~/lib/otel/tracer';
+ *
+ * export async function fetchProductRecommendations(productId: string) {
+ *   return await tracer.startActiveSpan('fetchProductRecommendations', async (span) => {
+ *     try {
+ *       // Add attributes for context
+ *       span.setAttribute('product.id', productId);
+ *
+ *       const recommendations = await fetch(`/api/recommendations/${productId}`);
+ *
+ *       span.setAttribute('recommendations.count', recommendations.length);
+ *
+ *       return recommendations;
+ *     } finally {
+ *       // Always end the span, even if an error occurs
+ *       span.end();
+ *     }
+ *   });
+ * }
+ *
+ * @example With error handling
+ * import { tracer } from '~/lib/otel/tracer';
+ * import { SpanStatusCode } from '@opentelemetry/api';
+ *
+ * export async function processOrder(orderId: string) {
+ *   return await tracer.startActiveSpan('processOrder', async (span) => {
+ *     try {
+ *       span.setAttribute('order.id', orderId);
+ *
+ *       const result = await submitOrder(orderId);
+ *
+ *       return result;
+ *     } catch (error) {
+ *       // Record the exception and mark span as error
+ *       span.recordException(error);
+ *       span.setStatus({ code: SpanStatusCode.ERROR });
+ *       throw error;
+ *     } finally {
+ *       span.end();
+ *     }
+ *   });
+ * }
+ *
+ * @example Data transformation
+ * export async function transformCartData(rawCart: RawCart) {
+ *   return await tracer.startActiveSpan('transformCartData', async (span) => {
+ *     try {
+ *       span.setAttribute('cart.itemCount', rawCart.lineItems.length);
+ *
+ *       const transformed = {
+ *         items: rawCart.lineItems.map(transformLineItem),
+ *         total: calculateTotal(rawCart),
+ *       };
+ *
+ *       return transformed;
+ *     } finally {
+ *       span.end();
+ *     }
+ *   });
+ * }
+ *
+ * When to use custom spans:
+ * - Operations that might be slow (> 100ms)
+ * - Critical business logic (pricing, inventory, checkout)
+ * - External API integrations
+ * - Data transformations with variable performance
+ * - Any operation you want to monitor and optimize
+ *
+ * When NOT to use custom spans:
+ * - Operations already instrumented by Next.js (fetch calls, route rendering)
+ * - Simple utility functions
+ * - Trivial operations (< 10ms)
+ *
+ * Best practices:
+ * - Use descriptive span names (e.g., 'cart.calculateDiscounts')
+ * - Add meaningful attributes for filtering and debugging
+ * - Always end spans in finally blocks
+ * - Use hierarchical naming (e.g., 'cart.validate', 'cart.addItem')
+ */
+export const tracer = trace.getTracer('default');

core/package.json

@@ -19,6 +19,10 @@
     "@conform-to/react": "^1.6.1",
     "@conform-to/zod": "^1.6.1",
     "@icons-pack/react-simple-icons": "^11.2.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.208.0",
+    "@opentelemetry/instrumentation": "^0.208.0",
+    "@opentelemetry/sdk-logs": "^0.208.0",
     "@radix-ui/react-accordion": "^1.2.11",
     "@radix-ui/react-checkbox": "^1.3.2",
     "@radix-ui/react-dialog": "^1.1.14",
@@ -37,6 +41,7 @@
     "@upstash/redis": "^1.35.0",
     "@vercel/analytics": "^1.5.0",
     "@vercel/functions": "^2.2.12",
+    "@vercel/otel": "^2.1.0",
     "@vercel/speed-insights": "^1.2.0",
     "clsx": "^2.1.1",
     "content-security-policy-builder": "^2.3.0",