@reactionary/source 0.0.28 → 0.0.29

package/core/package.json

@@ -3,6 +3,7 @@
   "version": "0.0.1",
   "dependencies": {
     "zod": "4.0.0-beta.20250430T185432",
-    "@upstash/redis": "^1.34.9"
+    "@upstash/redis": "^1.34.9",
+    "@reactionary/otel": "0.0.1"
   }
 }

package/core/src/providers/base.provider.ts

@@ -3,6 +3,7 @@ import { Session } from '../schemas/session.schema';
 import { BaseQuery } from '../schemas/queries/base.query';
 import { BaseMutation } from '../schemas/mutations/base.mutation';
 import { BaseModel } from '../schemas/models/base.model';
+import { createProviderInstrumentation } from '@reactionary/otel';
 
 /**
  * Base capability provider, responsible for mutations (changes) and queries (fetches)
@@ -13,7 +14,11 @@ export abstract class BaseProvider<
   Q extends BaseQuery = BaseQuery,
   M extends BaseMutation = BaseMutation
 > {
-  constructor(public readonly schema: z.ZodType<T>, public readonly querySchema: z.ZodType<Q, Q>, public readonly mutationSchema: z.ZodType<M, M>) {}
+  private instrumentation: ReturnType<typeof createProviderInstrumentation>;
+  
+  constructor(public readonly schema: z.ZodType<T>, public readonly querySchema: z.ZodType<Q, Q>, public readonly mutationSchema: z.ZodType<M, M>) {
+    this.instrumentation = createProviderInstrumentation(this.constructor.name);
+  }
 
   /**
    * Validates that the final domain model constructed by the provider
@@ -37,13 +42,21 @@ export abstract class BaseProvider<
    * of the results will match the order of the queries.
    */
   public async query(queries: Q[], session: Session): Promise<T[]> {
-    const results = await this.fetch(queries, session);
+    return this.instrumentation.traceQuery(
+      'query',
+      async (span) => {
+        span.setAttribute('provider.query.count', queries.length);
+        const results = await this.fetch(queries, session);
 
-    for (const result of results) {
-      this.assert(result);
-    }
+        for (const result of results) {
+          this.assert(result);
+        }
 
-    return results;
+        span.setAttribute('provider.result.count', results.length);
+        return results;
+      },
+      { queryCount: queries.length }
+    );
   }
 
   /**
@@ -51,11 +64,18 @@ export abstract class BaseProvider<
    * resulting from that set of operations.
    */
   public async mutate(mutations: M[], session: Session): Promise<T> {
-    const result = await this.process(mutations, session);
+    return this.instrumentation.traceMutation(
+      'mutate',
+      async (span) => {
+        span.setAttribute('provider.mutation.count', mutations.length);
+        const result = await this.process(mutations, session);
 
-    this.assert(result);
+        this.assert(result);
 
-    return result;
+        return result;
+      },
+      { mutationCount: mutations.length }
+    );
   }
 
   /**

package/examples/trpc-node/.env.example

@@ -0,0 +1,52 @@
+# OpenTelemetry Configuration (Standard Environment Variables)
+# See: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+# ============================
+
+# Service identification
+OTEL_SERVICE_NAME=reactionary-trpc-example
+OTEL_SERVICE_VERSION=1.0.0
+DEPLOYMENT_ENVIRONMENT=development
+
+# Traces exporter: console | otlp | otlp/http | none
+OTEL_TRACES_EXPORTER=console
+
+# Metrics exporter: console | otlp | otlp/http | none  
+OTEL_METRICS_EXPORTER=console
+
+# For OTLP exporters (e.g., Honeycomb, Jaeger, Grafana)
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+# OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your-api-key
+
+# Or use specific endpoints for traces/metrics
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.honeycomb.io/v1/traces
+# OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.honeycomb.io/v1/metrics
+
+# For local Jaeger
+# OTEL_TRACES_EXPORTER=otlp
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+# Debug logging
+# OTEL_LOG_LEVEL=debug
+
+# Metrics export interval (milliseconds)
+OTEL_METRIC_EXPORT_INTERVAL=60000
+
+# Session Store Configuration
+# ============================
+SESSION_STORE_REDIS_CONNECTION=redis://localhost:6379
+SESSION_STORE_SECRET=your-session-secret-here
+
+# Provider API Keys
+# ==================
+ALGOLIA_API_KEY=your-algolia-api-key
+ALGOLIA_APP_ID=your-algolia-app-id
+ALGOLIA_INDEX=your-algolia-index
+
+COMMERCETOOLS_API_URL=https://api.commercetools.com
+COMMERCETOOLS_AUTH_URL=https://auth.commercetools.com
+COMMERCETOOLS_CLIENT_ID=your-client-id
+COMMERCETOOLS_CLIENT_SECRET=your-client-secret
+COMMERCETOOLS_PROJECT_KEY=your-project-key
+
+POSTHOG_API_KEY=your-posthog-api-key
+POSTHOG_HOST=https://app.posthog.com

package/examples/trpc-node/src/main.ts

@@ -52,4 +52,12 @@ app.use(
   })
 );
 
-app.listen(3000);
+const server = app.listen(3000, () => {
+  console.log('Server started on http://localhost:3000');
+  // OTEL auto-initializes based on standard env vars
+  if (process.env['OTEL_LOG_LEVEL'] === 'debug') {
+    console.log('OTEL traces exporter:', process.env['OTEL_TRACES_EXPORTER'] || 'console');
+    console.log('OTEL metrics exporter:', process.env['OTEL_METRICS_EXPORTER'] || 'console');
+  }
+});
+

package/otel/README.md

@@ -0,0 +1,248 @@
+# @reactionary/otel
+
+Zero-configuration OpenTelemetry instrumentation for Reactionary framework. Automatically instruments tRPC routes and providers using standard OTEL environment variables.
+
+## Features
+
+- **Zero Configuration**: Auto-initializes on first use with standard OTEL env vars
+- **Automatic tRPC Route Tracing**: All tRPC procedures automatically traced
+- **Provider Instrumentation**: BaseProvider operations automatically instrumented
+- **Standard Compliance**: Uses official OpenTelemetry environment variables
+- **Multiple Exporters**: Console, OTLP/HTTP, or custom exporters
+- **Metrics Collection**: Request counts, durations, errors automatically tracked
+- **Lazy Initialization**: Only starts when actually used
+
+## Installation
+
+```bash
+pnpm add @reactionary/otel
+```
+
+That's it! No initialization code needed.
+
+## How It Works
+
+The OTEL package automatically initializes itself on first use, reading configuration from standard OpenTelemetry environment variables. When your code first creates a span or metric, the SDK initializes with your environment configuration.
+
+```typescript
+// No imports or initialization needed!
+// Just use your tRPC router or providers normally
+import { createTRPCRouter } from '@reactionary/trpc';
+
+const router = createTRPCRouter(client);
+// ↑ Automatically instrumented when OTEL env vars are set
+```
+
+## Configuration
+
+Use standard OpenTelemetry environment variables. No code changes needed.
+
+### Standard Environment Variables
+
+```bash
+# Service identification
+OTEL_SERVICE_NAME=my-service
+OTEL_SERVICE_VERSION=1.0.0
+DEPLOYMENT_ENVIRONMENT=production
+
+# Traces exporter (console | otlp | otlp/http | none)
+OTEL_TRACES_EXPORTER=otlp
+
+# Metrics exporter (console | otlp | otlp/http | none)
+OTEL_METRICS_EXPORTER=otlp
+
+# OTLP endpoint and headers
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your-api-key
+
+# Or use specific endpoints
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.honeycomb.io/v1/traces
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.honeycomb.io/v1/metrics
+
+# Debug logging
+OTEL_LOG_LEVEL=debug
+
+# Metrics export interval (milliseconds)
+OTEL_METRIC_EXPORT_INTERVAL=60000
+```
+
+See the [OpenTelemetry specification](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) for all available options.
+
+## Exporters
+
+### Console (Development)
+```bash
+OTEL_TRACES_EXPORTER=console
+OTEL_METRICS_EXPORTER=console
+```
+
+### OTLP (Production)
+Works with any OTLP-compatible backend:
+
+```bash
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your-api-key
+```
+
+### Disable
+```bash
+OTEL_TRACES_EXPORTER=none
+OTEL_METRICS_EXPORTER=none
+```
+
+## Custom Instrumentation
+
+### Manual Spans
+
+Create custom spans for specific operations:
+
+```typescript
+import { withSpan, getTracer } from '@reactionary/otel';
+
+// Using withSpan helper
+const result = await withSpan('custom-operation', async (span) => {
+  span.setAttribute('custom.attribute', 'value');
+  // Your operation here
+  return someAsyncOperation();
+});
+
+// Using tracer directly
+const tracer = getTracer();
+const span = tracer.startSpan('manual-span');
+try {
+  // Your operation
+  span.setStatus({ code: SpanStatusCode.OK });
+} catch (error) {
+  span.recordException(error);
+  span.setStatus({ code: SpanStatusCode.ERROR });
+  throw error;
+} finally {
+  span.end();
+}
+```
+
+### Provider Instrumentation
+
+Providers are automatically instrumented when extending BaseProvider:
+
+```typescript
+import { BaseProvider } from '@reactionary/core';
+
+class MyProvider extends BaseProvider {
+  // Automatically traced when OTEL is initialized
+  protected async fetch(queries, session) {
+    // Your implementation
+  }
+  
+  protected async process(mutations, session) {
+    // Your implementation
+  }
+}
+```
+
+### Custom Metrics
+
+Track custom business metrics:
+
+```typescript
+import { getMetrics } from '@reactionary/otel';
+
+const metrics = getMetrics();
+
+// Increment counter
+metrics.requestCounter.add(1, {
+  'endpoint': '/api/users',
+  'method': 'GET'
+});
+
+// Record histogram
+metrics.requestDuration.record(150, {
+  'endpoint': '/api/users',
+  'status': 'success'
+});
+```
+
+## Examples
+
+### Honeycomb
+
+```bash
+OTEL_SERVICE_NAME=my-service
+OTEL_TRACES_EXPORTER=otlp
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your-api-key
+```
+
+### Local Development
+
+```bash
+OTEL_SERVICE_NAME=my-service-dev
+OTEL_TRACES_EXPORTER=console
+OTEL_METRICS_EXPORTER=none  # Disable metrics in dev
+```
+
+### Docker Compose with Jaeger
+
+```yaml
+services:
+  app:
+    environment:
+      - OTEL_EXPORTER_TYPE=otlp
+      - OTEL_COLLECTOR_ENDPOINT=http://jaeger:4318
+      - OTEL_SERVICE_NAME=my-service
+      
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    ports:
+      - "16686:16686"  # Jaeger UI
+      - "4318:4318"    # OTLP HTTP
+```
+
+## Metrics Reference
+
+The following metrics are automatically collected:
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `reactionary.requests` | Counter | Total number of requests |
+| `reactionary.request.duration` | Histogram | Request duration in milliseconds |
+| `reactionary.requests.active` | UpDownCounter | Number of active requests |
+| `reactionary.errors` | Counter | Total number of errors |
+| `reactionary.provider.calls` | Counter | Total provider calls |
+| `reactionary.provider.duration` | Histogram | Provider call duration |
+| `reactionary.cache.hits` | Counter | Cache hit count |
+| `reactionary.cache.misses` | Counter | Cache miss count |
+
+## Best Practices
+
+1. **Use Standard Variables**: Stick to OpenTelemetry standard environment variables
+2. **Set Service Name**: Always set `OTEL_SERVICE_NAME` for service identification
+3. **Environment-based Config**: Use different configs for dev/staging/production
+4. **Add Context**: Use span attributes to add business context to traces
+5. **Handle Errors**: Ensure spans are properly closed even on errors
+6. **Sample Wisely**: Consider sampling strategies for high-volume services
+7. **Monitor Performance**: Watch for overhead in high-throughput scenarios
+
+## Troubleshooting
+
+### Traces Not Appearing
+
+1. Check OTEL is initialized before other components
+2. Verify `OTEL_TRACE_ENABLED` is not set to `false`
+3. Check exporter configuration and endpoint connectivity
+4. Look for initialization errors in console
+
+### Performance Impact
+
+- Use sampling to reduce overhead
+- Disable metrics if not needed
+- Consider using batch exporters
+- Increase export intervals for metrics
+
+### Memory Usage
+
+- Monitor span processor queue size
+- Adjust batch size and timeout
+- Consider using sampling for high-volume services

package/otel/eslint.config.mjs

@@ -0,0 +1,23 @@
+import baseConfig from '../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: [
+            '{projectRoot}/eslint.config.{js,cjs,mjs}',
+            '{projectRoot}/esbuild.config.{js,ts,mjs,mts}',
+            '{projectRoot}/vite.config.{js,ts,mjs,mts}',
+          ],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/otel/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@reactionary/otel",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-node": "^0.203.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/sdk-metrics": "^2.0.1",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/semantic-conventions": "^1.36.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.203.0",
+    "@opentelemetry/instrumentation-http": "^0.203.0",
+    "@opentelemetry/instrumentation-express": "^0.52.0",
+    "@trpc/server": "^11.1.2"
+  }
+}

package/otel/project.json

@@ -0,0 +1,33 @@
+{
+  "name": "otel",
+  "$schema": "../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "otel/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "manifestRootsToUpdate": ["dist/{projectRoot}"],
+      "currentVersionResolver": "git-tag",
+      "fallbackCurrentVersionResolver": "disk"
+    }
+  },
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/esbuild:esbuild",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/otel",
+        "main": "otel/src/index.ts",
+        "tsConfig": "otel/tsconfig.lib.json",
+        "assets": ["otel/*.md"],
+        "format": ["cjs"],
+        "generatePackageJson": true
+      }
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    }
+  }
+}

package/otel/src/config.ts

@@ -0,0 +1,139 @@
+import { SpanExporter } from '@opentelemetry/sdk-trace-base';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { MetricReader, PeriodicExportingMetricReader, ConsoleMetricExporter } from '@opentelemetry/sdk-metrics';
+
+// Internal config interface - not exported
+interface OtelConfig {
+  serviceName: string;
+  serviceVersion?: string;
+  environment?: string;
+  otlpEndpoint?: string;
+  otlpHeaders?: Record<string, string>;
+  traceEnabled: boolean;
+  metricsEnabled: boolean;
+  metricExportIntervalMillis: number;
+}
+
+// Detect if we're running in a browser environment
+function isBrowser(): boolean {
+  return typeof window !== 'undefined' && typeof process === 'undefined';
+}
+
+// Parse config from standard OTEL environment variables
+// https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+export function getConfigFromEnv(): OtelConfig {
+  // In browser environments, return disabled config
+  if (isBrowser()) {
+    return {
+      serviceName: 'browser-service',
+      serviceVersion: undefined,
+      environment: 'browser',
+      otlpEndpoint: undefined,
+      otlpHeaders: undefined,
+      traceEnabled: false,
+      metricsEnabled: false,
+      metricExportIntervalMillis: 60000,
+    };
+  }
+
+  // Determine exporter type from standard OTEL vars
+  const tracesExporter = process.env['OTEL_TRACES_EXPORTER'] || 'console';
+  const metricsExporter = process.env['OTEL_METRICS_EXPORTER'] || 'console';
+  
+  return {
+    serviceName: process.env['OTEL_SERVICE_NAME'] || 'unknown_service',
+    serviceVersion: process.env['OTEL_SERVICE_VERSION'],
+    environment: process.env['DEPLOYMENT_ENVIRONMENT'] || process.env['NODE_ENV'] || 'development',
+    otlpEndpoint: process.env['OTEL_EXPORTER_OTLP_ENDPOINT'],
+    otlpHeaders: process.env['OTEL_EXPORTER_OTLP_HEADERS'] 
+      ? parseHeaders(process.env['OTEL_EXPORTER_OTLP_HEADERS'])
+      : undefined,
+    traceEnabled: tracesExporter !== 'none',
+    metricsEnabled: metricsExporter !== 'none',
+    metricExportIntervalMillis: process.env['OTEL_METRIC_EXPORT_INTERVAL'] 
+      ? parseInt(process.env['OTEL_METRIC_EXPORT_INTERVAL'], 10)
+      : 60000, // Default 60 seconds per OTEL spec
+  };
+}
+
+function parseHeaders(headerString: string): Record<string, string> {
+  const headers: Record<string, string> = {};
+  headerString.split(',').forEach(header => {
+    const [key, value] = header.split('=');
+    if (key && value) {
+      headers[key.trim()] = value.trim();
+    }
+  });
+  return headers;
+}
+
+export function createTraceExporter(config: OtelConfig): SpanExporter | undefined {
+  if (!config.traceEnabled) {
+    return undefined;
+  }
+
+  const tracesExporter = process.env['OTEL_TRACES_EXPORTER'] || 'console';
+  
+  switch (tracesExporter) {
+    case 'otlp':
+    case 'otlp/http': {
+      if (!config.otlpEndpoint) {
+        console.warn('OTEL_EXPORTER_OTLP_ENDPOINT not set, falling back to console');
+        return new ConsoleSpanExporter();
+      }
+      // Use standard endpoint resolution
+      const tracesEndpoint = process.env['OTEL_EXPORTER_OTLP_TRACES_ENDPOINT'] || 
+                            `${config.otlpEndpoint}/v1/traces`;
+      return new OTLPTraceExporter({
+        url: tracesEndpoint,
+        headers: config.otlpHeaders,
+      });
+    }
+    case 'console':
+      return new ConsoleSpanExporter();
+    case 'none':
+    default:
+      return undefined;
+  }
+}
+
+export function createMetricReader(config: OtelConfig): MetricReader | undefined {
+  if (!config.metricsEnabled) {
+    return undefined;
+  }
+
+  const metricsExporter = process.env['OTEL_METRICS_EXPORTER'] || 'console';
+  let exporter;
+  
+  switch (metricsExporter) {
+    case 'otlp':
+    case 'otlp/http': {
+      if (!config.otlpEndpoint) {
+        console.warn('OTEL_EXPORTER_OTLP_ENDPOINT not set, falling back to console');
+        exporter = new ConsoleMetricExporter();
+      } else {
+        // Use standard endpoint resolution
+        const metricsEndpoint = process.env['OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'] || 
+                              `${config.otlpEndpoint}/v1/metrics`;
+        exporter = new OTLPMetricExporter({
+          url: metricsEndpoint,
+          headers: config.otlpHeaders,
+        });
+      }
+      break;
+    }
+    case 'console':
+      exporter = new ConsoleMetricExporter();
+      break;
+    case 'none':
+    default:
+      return undefined;
+  }
+
+  return new PeriodicExportingMetricReader({
+    exporter,
+    exportIntervalMillis: config.metricExportIntervalMillis,
+  });
+}

package/otel/src/index.ts

@@ -0,0 +1,12 @@
+// SDK functions - auto-initialization handled internally
+export { isOtelInitialized, shutdownOtel } from './sdk';
+
+// Tracing utilities
+export * from './tracer';
+export * from './metrics';
+export * from './trpc-middleware';
+export * from './provider-instrumentation';
+
+// Re-export common OTEL types
+export { trace, context, SpanKind, SpanStatusCode } from '@opentelemetry/api';
+export type { Span, Tracer, SpanOptions, Attributes } from '@opentelemetry/api';