@reactionary/source 0.0.28 → 0.0.30

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
+
+# 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
+# OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+# 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,8 @@ app.use(
   })
 );
 
-app.listen(3000);
+const server = app.listen(3000, () => {
+  console.log('Server started on http://localhost:3000');
+  // OpenTelemetry automatically initializes based on OTEL_* environment variables
+});
+

package/otel/README.md

@@ -0,0 +1,247 @@
+# @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
+
+# 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,12 @@
+{
+  "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",
+    "@trpc/server": "^11.1.2"
+  }
+}