@onebun/trace 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+# @onebun/trace
+
+OpenTelemetry-compatible tracing module for the OneBun framework.
+
+## Features
+
+- 🔍 Automatic HTTP request tracing
+- 📊 W3C Trace Context support (traceparent, tracestate)
+- 🎯 Effect.js integration
+- 🏷️ Method tracing decorators
+- 📝 Automatic trace information in logs
+- 🔗 Custom span creation
+- 🚀 OpenTelemetry-compatible API
+
+## Installation
+
+```bash
+bun add @onebun/trace
+```
+
+## Usage
+
+### Basic setup
+
+```typescript
+import { OneBunApplication } from '@onebun/core';
+import { AppModule } from './app.module';
+
+const app = new OneBunApplication(AppModule, {
+  tracing: {
+    enabled: true,
+    serviceName: 'my-service',
+    serviceVersion: '1.0.0',
+    samplingRate: 1.0, // 100% sampling
+    traceHttpRequests: true,
+    traceDatabaseQueries: true,
+    defaultAttributes: {
+      'service.name': 'my-service',
+      'service.version': '1.0.0',
+      'deployment.environment': 'production'
+    }
+  }
+});
+```
+
+### Configuration options
+
+```typescript
+interface TraceOptions {
+  enabled?: boolean;              // Enable/disable tracing (default: true)
+  serviceName?: string;           // Service name (default: 'onebun-service')
+  serviceVersion?: string;        // Service version (default: '1.0.0')
+  samplingRate?: number;          // Sampling rate 0.0-1.0 (default: 1.0)
+  traceHttpRequests?: boolean;    // Automatic HTTP tracing (default: true)
+  traceDatabaseQueries?: boolean; // Automatic DB tracing (default: true)
+  defaultAttributes?: Record<string, string | number | boolean>;
+  exportOptions?: TraceExportOptions;
+}
+```
+
+### Decorators
+
+#### @Trace
+
+Used for tracing controller methods:
+
+```typescript
+import { Controller, Get, Post } from '@onebun/core';
+import { Trace } from '@onebun/trace';
+
+@Controller('/api')
+export class UserController {
+  @Get('/users')
+  @Trace('get-all-users')
+  async getUsers() {
+    // Automatically creates a span named 'get-all-users'
+    return this.userService.findAll();
+  }
+
+  @Post('/users')
+  @Trace() // Uses method name as span name
+  async createUser(@Body() userData: CreateUserDto) {
+    return this.userService.create(userData);
+  }
+}
+```
+
+#### @Span
+
+Used for creating custom spans in services:
+
+```typescript
+import { Service } from '@onebun/core';
+import { Span } from '@onebun/trace';
+
+@Service()
+export class UserService {
+  @Span('database-query')
+  async findAll() {
+    // Creates a span for tracking database query
+    return await this.database.query('SELECT * FROM users');
+  }
+
+  @Span() // Uses 'UserService.validateUser' as name
+  async validateUser(id: string) {
+    // Span for validation
+    return await this.validateUserLogic(id);
+  }
+}
+```
+
+### Manual trace management
+
+```typescript
+import { TraceService } from '@onebun/trace';
+import { Effect } from 'effect';
+
+export class CustomService {
+  constructor(private traceService: TraceService) {}
+
+  async complexOperation() {
+    return Effect.runPromise(
+      Effect.flatMap(
+        this.traceService.startSpan('complex-operation'),
+        (span) => Effect.flatMap(
+          this.traceService.setAttributes({
+            'operation.type': 'data-processing',
+            'operation.complexity': 'high'
+          }),
+          () => Effect.flatMap(
+            this.performOperation(),
+            (result) => Effect.flatMap(
+              this.traceService.addEvent('operation-completed', {
+                'result.size': result.length,
+                'result.status': 'success'
+              }),
+              () => Effect.flatMap(
+                this.traceService.endSpan(span),
+                () => Effect.succeed(result)
+              )
+            )
+          )
+        )
+      )
+    );
+  }
+}
+```
+
+### Extracting and injecting trace context
+
+```typescript
+// Extract from HTTP headers
+const traceContext = await Effect.runPromise(
+  traceService.extractFromHeaders({
+    'traceparent': '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+    'tracestate': 'rojo=00f067aa0ba902b7,congo=t61rcWkgMzE'
+  })
+);
+
+// Inject into HTTP headers
+const headers = await Effect.runPromise(
+  traceService.injectIntoHeaders(traceContext)
+);
+
+// headers = {
+//   'traceparent': '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+//   'x-trace-id': '4bf92f3577b34da6a3ce929d0e0e4736',
+//   'x-span-id': '00f067aa0ba902b7'
+// }
+```
+
+### Log integration
+
+Traces are automatically added to logs:
+
+```typescript
+// In controller
+@Get('/users/:id')
+@Trace('get-user-by-id')
+async getUser(@Param('id') id: string) {
+  this.logger.info('Fetching user', { userId: id });
+  // Log automatically includes trace information:
+  // {
+  //   "timestamp": "2024-01-15T10:30:00.000Z",
+  //   "level": "info",
+  //   "message": "Fetching user",
+  //   "trace": {
+  //     "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+  //     "spanId": "00f067aa0ba902b7"
+  //   },
+  //   "context": { "userId": "123" }
+  // }
+  
+  return this.userService.findById(id);
+}
+```
+
+### Log formats
+
+#### Pretty format (development)
+```
+2024-01-15T10:30:00.000Z [INFO   ] [trace:34da6a3c span:902b7f00] Fetching user
+```
+
+#### JSON format (production)
+```json
+{
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "level": "info", 
+  "message": "Fetching user",
+  "trace": {
+    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+    "spanId": "00f067aa0ba902b7",
+    "parentSpanId": "a3ce929d0e0e4736"
+  },
+  "context": { "userId": "123" }
+}
+```
+
+### Automatic HTTP tracing
+
+All HTTP requests are automatically traced with attributes:
+
+- `http.method` - HTTP method
+- `http.url` - Request URL  
+- `http.route` - Route (pattern)
+- `http.status_code` - Response status code
+- `http.duration` - Duration in milliseconds
+- `http.user_agent` - Client User-Agent
+- `http.remote_addr` - Client IP address
+
+### Effect.js integration
+
+The module is fully integrated with Effect.js:
+
+```typescript
+import { Effect } from 'effect';
+import { TraceService } from '@onebun/trace';
+
+const tracedOperation = Effect.flatMap(
+  TraceService,
+  (traceService) => Effect.flatMap(
+    traceService.startSpan('my-operation'),
+    (span) => Effect.flatMap(
+      performSomeWork(),
+      (result) => Effect.flatMap(
+        traceService.endSpan(span),
+        () => Effect.succeed(result)
+      )
+    )
+  )
+);
+```
+
+## OpenTelemetry compatibility
+
+The module uses OpenTelemetry API and supports:
+
+- W3C Trace Context propagation
+- Standard span attributes
+- Span events and statuses
+- Export to external systems (when configured)
+
+## License
+
+MIT 

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@onebun/trace",
+  "version": "0.1.0",
+  "description": "OpenTelemetry-compatible tracing module for OneBun framework",
+  "license": "LGPL-3.0",
+  "author": "RemRyahirev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RemRyahirev/onebun.git",
+    "directory": "packages/trace"
+  },
+  "bugs": {
+    "url": "https://github.com/RemRyahirev/onebun/issues"
+  },
+  "homepage": "https://github.com/RemRyahirev/onebun/tree/master/packages/trace#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "dev": "bun run --watch src/index.ts"
+  },
+  "dependencies": {
+    "effect": "^3.13.10",
+    "@opentelemetry/api": "^1.8.0",
+    "@onebun/requests": "^0.1.0"
+  },
+  "devDependencies": {
+    "bun-types": "1.2.2"
+  },
+  "engines": {
+    "bun": "1.2.12"
+  }
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * \@onebun/trace - OpenTelemetry-compatible tracing module for OneBun framework
+ *
+ * This module provides:
+ * - Automatic HTTP request tracing
+ * - W3C trace context propagation
+ * - Effect.js integration
+ * - Decorators for method tracing
+ * - Custom span creation and management
+ */
+
+// Re-export some OpenTelemetry types for convenience
+export type { Context } from '@opentelemetry/api';
+// Middleware and decorators
+export {
+  createTraceMiddleware,
+  Span,
+  span,
+  // Backward compatibility aliases
+  Trace,
+  TraceMiddleware,
+  trace,
+} from './middleware.js';
+
+// Core service
+export {
+  currentSpan,
+  currentTraceContext,
+  makeTraceService,
+  // Backward compatibility aliases
+  TraceService,
+  TraceServiceImpl,
+  TraceServiceLive,
+  traceService,
+  traceServiceLive,
+} from './trace.service.js';
+// Types
+export type {
+  HttpTraceData,
+  SpanStatus,
+  TraceContext,
+  TraceEvent,
+  TraceExportOptions,
+  TraceHeaders,
+  TraceOptions,
+  TraceSpan,
+} from './types.js';
+export { SpanStatusCode } from './types.js';

package/src/middleware.ts

@@ -0,0 +1,283 @@
+import { Effect } from 'effect';
+
+import type { HttpTraceData, TraceHeaders } from './types.js';
+
+import { HttpStatusCode } from '@onebun/requests';
+
+import { traceService } from './trace.service.js';
+
+/**
+ * HTTP trace middleware for OneBun applications
+ */
+export class TraceMiddleware {
+  /**
+   * Create trace middleware Effect
+   */
+  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+  static create() {
+    return Effect.flatMap(traceService, (traceServiceInstance) =>
+      Effect.succeed((request: Request, next: () => Promise<Response>) => {
+        return Effect.runPromise(
+          Effect.flatMap(
+            traceServiceInstance.extractFromHeaders(TraceMiddleware.extractHeaders(request)),
+            (extractedContext) =>
+              Effect.flatMap(
+                extractedContext
+                  ? traceServiceInstance.setContext(extractedContext)
+                  : Effect.flatMap(traceServiceInstance.generateTraceContext(), (newContext) =>
+                    traceServiceInstance.setContext(newContext),
+                  ),
+                () => {
+                  const httpData: Partial<HttpTraceData> = {
+                    method: request.method,
+                    url: request.url,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    route: (request as any).route?.path,
+                    userAgent: request.headers.get('user-agent') || undefined,
+                    remoteAddr: TraceMiddleware.getRemoteAddress(request),
+                    requestSize: TraceMiddleware.getRequestSize(request),
+                  };
+
+                  const startTime = Date.now();
+
+                  return Effect.flatMap(
+                    traceServiceInstance.startHttpTrace(httpData),
+                    (_httpSpan) =>
+                      Effect.tryPromise({
+                        try: () => next(),
+                        catch: (error) => error as Error,
+                      }).pipe(
+                        Effect.tap((response) => {
+                          const endTime = Date.now();
+                          const finalData: Partial<HttpTraceData> = {
+                            statusCode:
+                              (response && typeof response === 'object' && 'status' in response
+                                ? (response.status as number)
+                                : undefined) || HttpStatusCode.OK,
+                            responseSize: TraceMiddleware.getResponseSize(response),
+                            duration: endTime - startTime,
+                          };
+
+                          return traceServiceInstance.endHttpTrace(_httpSpan, finalData);
+                        }),
+                        Effect.tapError((error) => {
+                          const endTime = Date.now();
+                          const errorData: Partial<HttpTraceData> = {
+                            statusCode: HttpStatusCode.INTERNAL_SERVER_ERROR,
+                            duration: endTime - startTime,
+                          };
+
+                          return Effect.flatMap(
+                            traceServiceInstance.addEvent('error', {
+                              // eslint-disable-next-line @typescript-eslint/naming-convention
+                              'error.type': error.constructor.name,
+                              // eslint-disable-next-line @typescript-eslint/naming-convention
+                              'error.message': error.message,
+                            }),
+                            () => traceServiceInstance.endHttpTrace(_httpSpan, errorData),
+                          );
+                        }),
+                      ),
+                  );
+                },
+              ),
+          ),
+        );
+      }),
+    );
+  }
+
+  /**
+   * Extract trace headers from HTTP request
+   */
+  private static extractHeaders(request: Request): TraceHeaders {
+    return {
+      traceparent: request.headers.get('traceparent') || undefined,
+      tracestate: request.headers.get('tracestate') || undefined,
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      'x-trace-id': request.headers.get('x-trace-id') || undefined,
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      'x-span-id': request.headers.get('x-span-id') || undefined,
+    };
+  }
+
+  /**
+   * Get remote address from request
+   */
+  private static getRemoteAddress(request: unknown): string | undefined {
+    if (!request || typeof request !== 'object') {
+      return undefined;
+    }
+
+    const headers = 'headers' in request ? (request.headers as Record<string, string>) : {};
+    const socket = 'socket' in request ? (request.socket as { remoteAddress?: string }) : {};
+    const connection =
+      'connection' in request ? (request.connection as { remoteAddress?: string }) : {};
+
+    return (
+      headers['x-forwarded-for'] ||
+      headers['x-real-ip'] ||
+      socket.remoteAddress ||
+      connection.remoteAddress
+    );
+  }
+
+  /**
+   * Get request content length
+   */
+  private static getRequestSize(request: unknown): number | undefined {
+    if (!request || typeof request !== 'object' || !('headers' in request)) {
+      return undefined;
+    }
+
+    const headers = request.headers as Record<string, string>;
+    const contentLength = headers['content-length'];
+
+    return contentLength ? parseInt(contentLength, 10) : undefined;
+  }
+
+  /**
+   * Get response content length
+   */
+  private static getResponseSize(response: unknown): number | undefined {
+    if (!response || typeof response !== 'object') {
+      return undefined;
+    }
+
+    const DECIMAL_BASE = 10;
+
+    if ('headers' in response) {
+      const headers = response.headers as Record<string, string>;
+      const contentLength = headers['content-length'];
+      if (contentLength) {
+        return parseInt(contentLength, DECIMAL_BASE);
+      }
+    }
+
+    // Try to estimate from body
+    if ('body' in response) {
+      const body = response.body;
+
+      if (typeof body === 'string') {
+        return Buffer.byteLength(body);
+      }
+
+      if (Buffer.isBuffer(body)) {
+        return body.length;
+      }
+
+      if (body && typeof body === 'object') {
+        return Buffer.byteLength(JSON.stringify(body));
+      }
+    }
+
+    return undefined;
+  }
+}
+
+/**
+ * Create trace middleware function for Bun server
+ */
+export const createTraceMiddleware = (): TraceMiddleware => {
+  return TraceMiddleware.create();
+};
+
+/**
+ * Trace decorator for controller methods
+ */
+export function trace(operationName?: string): MethodDecorator {
+  return (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    const targetConstructor =
+      target && typeof target === 'object' && target.constructor
+        ? target.constructor
+        : { name: 'Unknown' };
+    const spanName = operationName || `${targetConstructor.name}.${String(propertyKey)}`;
+
+    descriptor.value = function (...args: unknown[]) {
+      return Effect.flatMap(traceService, (traceServiceInstance) =>
+        Effect.flatMap(traceServiceInstance.startSpan(spanName), (_traceSpan) => {
+          const startTime = Date.now();
+
+          return Effect.tryPromise({
+            try: () => originalMethod.apply(this, args),
+            catch: (error) => error as Error,
+          }).pipe(
+            Effect.tap(() => {
+              const duration = Date.now() - startTime;
+
+              return Effect.flatMap(
+                traceServiceInstance.setAttributes({
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'method.name': String(propertyKey),
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'method.duration': duration,
+                }),
+                () => traceServiceInstance.endSpan(_traceSpan),
+              );
+            }),
+            Effect.tapError((error) => {
+              const duration = Date.now() - startTime;
+
+              return Effect.flatMap(
+                traceServiceInstance.setAttributes({
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'method.name': String(propertyKey),
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'method.duration': duration,
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'error.type': error.constructor.name,
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'error.message': error.message,
+                }),
+                () =>
+                  traceServiceInstance.endSpan(_traceSpan, {
+                    code: 2, // ERROR
+                    message: error.message,
+                  }),
+              );
+            }),
+          );
+        }),
+      );
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Span decorator for creating custom spans
+ */
+export function span(name?: string): MethodDecorator {
+  return (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    const targetConstructor =
+      target && typeof target === 'object' && target.constructor
+        ? target.constructor
+        : { name: 'Unknown' };
+    const spanName = name || `${targetConstructor.name}.${String(propertyKey)}`;
+
+    descriptor.value = function (...args: unknown[]) {
+      return Effect.flatMap(traceService, (traceServiceInstance) =>
+        Effect.flatMap(traceServiceInstance.startSpan(spanName), (spanInstance) =>
+          Effect.flatMap(
+            Effect.try(() => originalMethod.apply(this, args)),
+            (result) =>
+              Effect.flatMap(traceServiceInstance.endSpan(spanInstance), () =>
+                Effect.succeed(result),
+              ),
+          ),
+        ),
+      );
+    };
+
+    return descriptor;
+  };
+}
+
+// Backward compatibility aliases
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Trace = trace;
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Span = span;

package/src/trace.service.ts

@@ -0,0 +1,409 @@
+import {
+  context,
+  SpanStatusCode as OtelSpanStatusCode,
+  SpanKind,
+  trace,
+} from '@opentelemetry/api';
+import {
+  Context,
+  Effect,
+  FiberRef,
+  Layer,
+} from 'effect';
+
+import { HttpStatusCode } from '@onebun/requests';
+
+import {
+  type HttpTraceData,
+  type SpanStatus,
+  SpanStatusCode,
+  type TraceContext,
+  type TraceHeaders,
+  type TraceOptions,
+  type TraceSpan,
+} from './types.js';
+
+/**
+ * Index of trace flags in W3C traceparent header regex match array
+ */
+const TRACE_FLAGS_MATCH_INDEX = 3;
+
+/**
+ * Trace service interface
+ */
+export interface TraceService {
+  /**
+   * Get current trace context
+   */
+  getCurrentContext(): Effect.Effect<TraceContext | null>;
+
+  /**
+   * Set trace context
+   */
+  setContext(traceContext: TraceContext): Effect.Effect<void>;
+
+  /**
+   * Start a new span
+   */
+  startSpan(name: string, parentContext?: TraceContext): Effect.Effect<TraceSpan>;
+
+  /**
+   * End a span
+   */
+  endSpan(span: TraceSpan, status?: SpanStatus): Effect.Effect<void>;
+
+  /**
+   * Add event to current span
+   */
+  addEvent(
+    name: string,
+    attributes?: Record<string, string | number | boolean>,
+  ): Effect.Effect<void>;
+
+  /**
+   * Set span attributes
+   */
+  setAttributes(attributes: Record<string, string | number | boolean>): Effect.Effect<void>;
+
+  /**
+   * Extract trace context from HTTP headers
+   */
+  extractFromHeaders(headers: TraceHeaders): Effect.Effect<TraceContext | null>;
+
+  /**
+   * Inject trace context into HTTP headers
+   */
+  injectIntoHeaders(traceContext: TraceContext): Effect.Effect<TraceHeaders>;
+
+  /**
+   * Generate new trace context
+   */
+  generateTraceContext(): Effect.Effect<TraceContext>;
+
+  /**
+   * Start HTTP request tracing
+   */
+  startHttpTrace(data: Partial<HttpTraceData>): Effect.Effect<TraceSpan>;
+
+  /**
+   * End HTTP request tracing
+   */
+  endHttpTrace(span: TraceSpan, data: Partial<HttpTraceData>): Effect.Effect<void>;
+}
+
+/**
+ * Trace service tag for Effect dependency injection
+ */
+export const traceService = Context.GenericTag<TraceService>('@onebun/trace/TraceService');
+
+/**
+ * Current trace context stored in fiber
+ */
+export const currentTraceContext = FiberRef.unsafeMake<TraceContext | null>(null);
+
+/**
+ * Current span stored in fiber
+ */
+
+export const currentSpan = FiberRef.unsafeMake<TraceSpan | null>(null);
+
+/**
+ * Implementation of TraceService
+ */
+export class TraceServiceImpl implements TraceService {
+  private readonly tracer = trace.getTracer('@onebun/trace');
+  private readonly options: Required<TraceOptions>;
+
+  constructor(options: TraceOptions = {}) {
+    this.options = {
+      enabled: true,
+      serviceName: 'onebun-service',
+      serviceVersion: '1.0.0',
+      samplingRate: 1.0,
+      traceHttpRequests: true,
+      traceDatabaseQueries: true,
+      defaultAttributes: {},
+      exportOptions: {},
+      ...options,
+    };
+  }
+
+  getCurrentContext(): Effect.Effect<TraceContext | null> {
+    return FiberRef.get(currentTraceContext);
+  }
+
+  setContext(traceContext: TraceContext): Effect.Effect<void> {
+    return FiberRef.set(currentTraceContext, traceContext);
+  }
+
+  startSpan(name: string, parentContext?: TraceContext): Effect.Effect<TraceSpan> {
+    if (!this.options.enabled) {
+      return Effect.flatMap(
+        this.generateTraceContext(),
+        // eslint-disable-next-line @typescript-eslint/no-shadow
+        (context) => {
+          const mockSpan: TraceSpan = {
+            context,
+            name,
+            startTime: Date.now(),
+            attributes: {},
+            events: [],
+            status: { code: SpanStatusCode.OK },
+          };
+
+          return Effect.flatMap(FiberRef.set(currentSpan, mockSpan), () =>
+            Effect.succeed(mockSpan),
+          );
+        },
+      );
+    }
+
+    const currentContext = context.active();
+    const span = this.tracer.startSpan(
+      name,
+      {
+        kind: SpanKind.INTERNAL,
+        attributes: this.options.defaultAttributes,
+      },
+      currentContext,
+    );
+
+    const spanContext = span.spanContext();
+    const traceContext: TraceContext = {
+      traceId: spanContext.traceId,
+      spanId: spanContext.spanId,
+      traceFlags: spanContext.traceFlags,
+      parentSpanId: parentContext?.spanId,
+    };
+
+    const traceSpan: TraceSpan = {
+      context: traceContext,
+      name,
+      startTime: Date.now(),
+      attributes: { ...this.options.defaultAttributes },
+      events: [],
+      status: { code: SpanStatusCode.OK },
+    };
+
+    return Effect.flatMap(FiberRef.set(currentSpan, traceSpan), () =>
+      Effect.flatMap(this.setContext(traceContext), () => Effect.succeed(traceSpan)),
+    );
+  }
+
+  endSpan(span: TraceSpan, status?: SpanStatus): Effect.Effect<void> {
+    if (!this.options.enabled) {
+      return Effect.void;
+    }
+
+    span.endTime = Date.now();
+    if (status) {
+      span.status = status;
+    }
+
+    // Find the OTel span and end it
+    const activeSpan = trace.getActiveSpan();
+    if (activeSpan && activeSpan.spanContext().spanId === span.context.spanId) {
+      if (status?.code === SpanStatusCode.ERROR) {
+        activeSpan.setStatus({
+          code: OtelSpanStatusCode.ERROR,
+          message: status.message,
+        });
+      }
+      activeSpan.end();
+    }
+
+    return FiberRef.set(currentSpan, null);
+  }
+
+  addEvent(
+    name: string,
+    attributes?: Record<string, string | number | boolean>,
+  ): Effect.Effect<void> {
+    if (!this.options.enabled) {
+      return Effect.void;
+    }
+
+    return Effect.flatMap(FiberRef.get(currentSpan), (span) => {
+      if (span) {
+        span.events.push({
+          name,
+          timestamp: Date.now(),
+          attributes,
+        });
+
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan) {
+          activeSpan.addEvent(name, attributes);
+        }
+      }
+
+      return Effect.void;
+    });
+  }
+
+  setAttributes(attributes: Record<string, string | number | boolean>): Effect.Effect<void> {
+    if (!this.options.enabled) {
+      return Effect.void;
+    }
+
+    return Effect.flatMap(FiberRef.get(currentSpan), (span) => {
+      if (span) {
+        Object.assign(span.attributes, attributes);
+
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan) {
+          activeSpan.setAttributes(attributes);
+        }
+      }
+
+      return Effect.void;
+    });
+  }
+
+  extractFromHeaders(headers: TraceHeaders): Effect.Effect<TraceContext | null> {
+    if (!this.options.enabled) {
+      return Effect.succeed(null);
+    }
+
+    // Try W3C traceparent header first
+    const TRACE_ID_LENGTH = 32;
+    const SPAN_ID_LENGTH = 16;
+    const FLAGS_LENGTH = 2;
+    const HEX_BASE = 16;
+    const traceparent = headers['traceparent'];
+    if (traceparent) {
+      const match = traceparent.match(
+        new RegExp(
+          `^00-([0-9a-f]{${TRACE_ID_LENGTH}})-([0-9a-f]{${SPAN_ID_LENGTH}})-([0-9a-f]{${FLAGS_LENGTH}})$`,
+        ),
+      );
+      if (match) {
+        return Effect.succeed({
+          traceId: match[1],
+          spanId: match[2],
+          traceFlags: parseInt(match[TRACE_FLAGS_MATCH_INDEX], HEX_BASE),
+        });
+      }
+    }
+
+    // Fallback to custom headers
+    const traceId = headers['x-trace-id'];
+    const spanId = headers['x-span-id'];
+
+    if (traceId && spanId) {
+      return Effect.succeed({
+        traceId,
+        spanId,
+        traceFlags: 1,
+      });
+    }
+
+    return Effect.succeed(null);
+  }
+
+  injectIntoHeaders(traceContext: TraceContext): Effect.Effect<TraceHeaders> {
+    const HEX_BASE = 16;
+    const PAD_LENGTH = 2;
+
+    return Effect.succeed({
+      traceparent: `00-${traceContext.traceId}-${traceContext.spanId}-${traceContext.traceFlags.toString(HEX_BASE).padStart(PAD_LENGTH, '0')}`,
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      'x-trace-id': traceContext.traceId,
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      'x-span-id': traceContext.spanId,
+    });
+  }
+
+  generateTraceContext(): Effect.Effect<TraceContext> {
+    const TRACE_ID_LENGTH = 32;
+    const SPAN_ID_LENGTH = 16;
+
+    return Effect.succeed({
+      traceId: this.generateId(TRACE_ID_LENGTH),
+      spanId: this.generateId(SPAN_ID_LENGTH),
+      traceFlags: Math.random() < this.options.samplingRate ? 1 : 0,
+    });
+  }
+
+  startHttpTrace(data: Partial<HttpTraceData>): Effect.Effect<TraceSpan> {
+    const spanName = `HTTP ${data.method || 'REQUEST'} ${data.route || data.url || '/'}`;
+
+    return Effect.flatMap(this.startSpan(spanName), (span) => {
+      const attributes: Record<string, string | number | boolean> = {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'http.method': data.method || 'UNKNOWN',
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'http.url': data.url || '',
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'http.route': data.route || '',
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'http.user_agent': data.userAgent || '',
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'http.remote_addr': data.remoteAddr || '',
+      };
+
+      if (data.requestSize !== undefined) {
+        attributes['http.request_content_length'] = data.requestSize;
+      }
+
+      return Effect.flatMap(this.setAttributes(attributes), () => Effect.succeed(span));
+    });
+  }
+
+  endHttpTrace(span: TraceSpan, data: Partial<HttpTraceData>): Effect.Effect<void> {
+    const attributes: Record<string, string | number | boolean> = {};
+
+    if (data.statusCode !== undefined) {
+      attributes['http.status_code'] = data.statusCode;
+    }
+
+    if (data.responseSize !== undefined) {
+      attributes['http.response_content_length'] = data.responseSize;
+    }
+
+    if (data.duration !== undefined) {
+      attributes['http.duration'] = data.duration;
+    }
+
+    const HTTP_ERROR_THRESHOLD = HttpStatusCode.BAD_REQUEST;
+    const status: SpanStatus = {
+      code:
+        data.statusCode && data.statusCode >= HTTP_ERROR_THRESHOLD
+          ? SpanStatusCode.ERROR
+          : SpanStatusCode.OK,
+      message:
+        data.statusCode && data.statusCode >= HTTP_ERROR_THRESHOLD
+          ? `HTTP ${data.statusCode}`
+          : undefined,
+    };
+
+    return Effect.flatMap(this.setAttributes(attributes), () => this.endSpan(span, status));
+  }
+
+  private generateId(length: number): string {
+    const chars = '0123456789abcdef';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+      result += chars[Math.floor(Math.random() * chars.length)];
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Create TraceService layer
+ */
+export const makeTraceService = (options?: TraceOptions): Layer.Layer<TraceService> =>
+  Layer.succeed(traceService, new TraceServiceImpl(options));
+
+/**
+ * Default trace service layer
+ */
+export const traceServiceLive = makeTraceService();
+
+// Backward compatibility aliases
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const TraceService = traceService;
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const TraceServiceLive = traceServiceLive;

package/src/types.ts

@@ -0,0 +1,243 @@
+/**
+ * Trace context interface
+ */
+export interface TraceContext {
+  /**
+   * Trace ID
+   */
+  traceId: string;
+
+  /**
+   * Span ID
+   */
+  spanId: string;
+
+  /**
+   * Parent span ID
+   */
+  parentSpanId?: string;
+
+  /**
+   * Trace flags
+   */
+  traceFlags: number;
+
+  /**
+   * Baggage items
+   */
+  baggage?: Record<string, string>;
+}
+
+/**
+ * Span interface
+ */
+export interface TraceSpan {
+  /**
+   * Span context
+   */
+  context: TraceContext;
+
+  /**
+   * Span name
+   */
+  name: string;
+
+  /**
+   * Start time
+   */
+  startTime: number;
+
+  /**
+   * End time
+   */
+  endTime?: number;
+
+  /**
+   * Span attributes
+   */
+  attributes: Record<string, string | number | boolean>;
+
+  /**
+   * Span events
+   */
+  events: TraceEvent[];
+
+  /**
+   * Span status
+   */
+  status: SpanStatus;
+}
+
+/**
+ * Span event interface
+ */
+export interface TraceEvent {
+  /**
+   * Event name
+   */
+  name: string;
+
+  /**
+   * Event timestamp
+   */
+  timestamp: number;
+
+  /**
+   * Event attributes
+   */
+  attributes?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Span status
+ */
+export interface SpanStatus {
+  /**
+   * Status code
+   */
+  code: SpanStatusCode;
+
+  /**
+   * Status message
+   */
+  message?: string;
+}
+
+/**
+ * Span status codes
+ */
+export enum SpanStatusCode {
+  /**
+   * The operation completed successfully.
+   */
+  OK = 1,
+
+  /**
+   * An error occurred.
+   */
+  ERROR = 2,
+}
+
+/**
+ * HTTP trace headers
+ */
+export interface TraceHeaders {
+  /**
+   * Trace parent header (W3C)
+   */
+  traceparent?: string;
+
+  /**
+   * Trace state header (W3C)
+   */
+  tracestate?: string;
+
+  /**
+   * X-Trace-Id header (custom)
+   */
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  'x-trace-id'?: string;
+
+  /**
+   * X-Span-Id header (custom)
+   */
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  'x-span-id'?: string;
+}
+
+/**
+ * Trace options configuration
+ */
+export interface TraceOptions {
+  /**
+   * Enable/disable tracing
+   * @defaultValue true
+   */
+  enabled?: boolean;
+
+  /**
+   * Service name for tracing
+   */
+  serviceName?: string;
+
+  /**
+   * Service version
+   */
+  serviceVersion?: string;
+
+  /**
+   * Sampling rate (0.0 to 1.0)
+   * @defaultValue 1.0
+   */
+  samplingRate?: number;
+
+  /**
+   * Enable automatic HTTP request tracing
+   * @defaultValue true
+   */
+  traceHttpRequests?: boolean;
+
+  /**
+   * Enable automatic database query tracing
+   * @defaultValue true
+   */
+  traceDatabaseQueries?: boolean;
+
+  /**
+   * Custom attributes to add to all spans
+   */
+  defaultAttributes?: Record<string, string | number | boolean>;
+
+  /**
+   * Export traces to external system
+   */
+  exportOptions?: TraceExportOptions;
+}
+
+/**
+ * Trace export options
+ */
+export interface TraceExportOptions {
+  /**
+   * Export endpoint URL
+   */
+  endpoint?: string;
+
+  /**
+   * Export headers
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Export timeout in milliseconds
+   * @defaultValue 10000
+   */
+  timeout?: number;
+
+  /**
+   * Batch size for exporting
+   * @defaultValue 100
+   */
+  batchSize?: number;
+
+  /**
+   * Batch timeout in milliseconds
+   * @defaultValue 5000
+   */
+  batchTimeout?: number;
+}
+
+/**
+ * HTTP request trace data
+ */
+export interface HttpTraceData {
+  method: string;
+  url: string;
+  route?: string;
+  statusCode?: number;
+  userAgent?: string;
+  remoteAddr?: string;
+  requestSize?: number;
+  responseSize?: number;
+  duration?: number;
+}