@onebun/trace 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/trace",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "OpenTelemetry-compatible tracing for OneBun framework - distributed tracing support",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",
@@ -38,9 +38,13 @@
     "dev": "bun run --watch src/index.ts"
   },
   "dependencies": {
-    "effect": "^3.13.10",
+    "@onebun/requests": "^0.2.1",
     "@opentelemetry/api": "^1.8.0",
-    "@onebun/requests": "^0.2.1"
+    "@opentelemetry/core": "^2.6.1",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "effect": "^3.13.10"
   },
   "devDependencies": {
     "bun-types": "^1.3.8"

package/src/auto-trace.ts

@@ -0,0 +1,343 @@
+import { SpanStatusCode as OtelSpanStatusCode, trace as otelTrace } from '@opentelemetry/api';
+
+import { type SpanAttributeEntry, SPAN_ATTRIBUTES } from './middleware.js';
+
+/**
+ * Symbols for trace metadata on classes and methods
+ */
+export const NO_TRACE = Symbol.for('onebun:noTrace');
+export const TRACE_ALL = Symbol.for('onebun:traceAll');
+export const ALREADY_TRACED = Symbol.for('onebun:traced');
+
+/**
+ * Filter options for auto-tracing
+ */
+export interface TraceFilterOptions {
+  asyncOnly?: boolean;
+  excludeMethods?: string[];
+  includeClasses?: string[];
+  excludeClasses?: string[];
+}
+
+/**
+ * Built-in methods that should never be auto-traced.
+ * Includes framework base class methods, lifecycle hooks, and internals.
+ */
+const EXCLUDED_METHODS = new Set([
+  'constructor',
+  // BaseService
+  'initializeService',
+  'runEffect',
+  'formatError',
+  // BaseController
+  'initializeController',
+  'getService',
+  'setService',
+  'isJson',
+  'parseJson',
+  'success',
+  'error',
+  'json',
+  'text',
+  'sse',
+  // Lifecycle hooks
+  'onModuleInit',
+  'onApplicationInit',
+  'onModuleDestroy',
+  'beforeApplicationDestroy',
+  'onApplicationDestroy',
+  'onQueueReady',
+  // Middleware
+  'use',
+  'configureMiddleware',
+  // WebSocket
+  '_initializeBase',
+  'afterInit',
+  'handleConnection',
+  'handleDisconnect',
+  // BaseService/Controller span getter
+  'span',
+]);
+
+/**
+ * Simple glob matching: supports `*` as wildcard.
+ * `*Service` matches `UserService`, `OrderService`.
+ * `User*` matches `UserService`, `UserController`.
+ * `*` matches everything.
+ */
+function matchGlob(pattern: string, name: string): boolean {
+  if (pattern === '*') {
+    return true;
+  }
+
+  if (pattern.startsWith('*') && pattern.endsWith('*')) {
+    return name.includes(pattern.slice(1, -1));
+  }
+
+  if (pattern.startsWith('*')) {
+    return name.endsWith(pattern.slice(1));
+  }
+
+  if (pattern.endsWith('*')) {
+    return name.startsWith(pattern.slice(0, -1));
+  }
+
+  return name === pattern;
+}
+
+/**
+ * Check if a class name matches the glob filter.
+ */
+function matchesClassFilter(
+  className: string,
+  filter?: TraceFilterOptions,
+): boolean {
+  if (!filter) {
+    return true;
+  }
+
+  // If includeClasses is set, class must match at least one pattern
+  if (filter.includeClasses && filter.includeClasses.length > 0) {
+    if (!filter.includeClasses.some((pattern) => matchGlob(pattern, className))) {
+      return false;
+    }
+  }
+
+  // If excludeClasses is set, class must NOT match any pattern
+  if (filter.excludeClasses && filter.excludeClasses.length > 0) {
+    if (filter.excludeClasses.some((pattern) => matchGlob(pattern, className))) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Check if a method is async (its constructor is AsyncFunction).
+ */
+function isAsyncFunction(fn: unknown): boolean {
+  return typeof fn === 'function' && fn.constructor.name === 'AsyncFunction';
+}
+
+/**
+ * Wrap a method with a span. Same pattern as @Traced() but applied at runtime.
+ */
+function wrapMethodWithSpan(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  prototype: any,
+  methodName: string,
+  className: string,
+): void {
+  const original = prototype[methodName];
+  const spanName = `${className}.${methodName}`;
+
+  const wrapped = async function (
+    this: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ...args: any[]
+  ) {
+    const tracer = otelTrace.getTracer('@onebun/trace');
+
+    return await tracer.startActiveSpan(spanName, async (activeSpan) => {
+      // Apply @SpanAttribute metadata if present
+      const meta = prototype[SPAN_ATTRIBUTES]?.[methodName] as
+        | SpanAttributeEntry[]
+        | undefined;
+      if (meta) {
+        for (const { paramIndex, attrName } of meta) {
+          const value = args[paramIndex];
+          if (value !== undefined && value !== null) {
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+              activeSpan.setAttribute(attrName, value);
+            } else {
+              activeSpan.setAttribute(attrName, JSON.stringify(value));
+            }
+          }
+        }
+      }
+
+      try {
+        const result = await original.apply(this, args);
+        activeSpan.setStatus({ code: OtelSpanStatusCode.OK });
+
+        return result;
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        activeSpan.setStatus({ code: OtelSpanStatusCode.ERROR, message: err.message });
+        activeSpan.recordException(err);
+        throw error;
+      } finally {
+        activeSpan.end();
+      }
+    });
+  };
+
+  // Mark as auto-traced to prevent double-wrapping
+  (wrapped as unknown as Record<symbol, boolean>)[ALREADY_TRACED] = true;
+  prototype[methodName] = wrapped;
+}
+
+/**
+ * Apply automatic tracing to all eligible methods on an instance.
+ *
+ * Walks the prototype chain (stopping at Object.prototype) and wraps
+ * methods with OpenTelemetry spans. Respects @NoTrace(), @Traced(),
+ * and filter options.
+ *
+ * @param instance - The service or controller instance
+ * @param className - The class name for span naming
+ * @param filter - Optional filter options
+ */
+export function applyAutoTrace(
+  instance: unknown,
+  className: string,
+  filter?: TraceFilterOptions,
+): void {
+  if (!instance || typeof instance !== 'object') {
+    return;
+  }
+
+  const asyncOnly = filter?.asyncOnly ?? true;
+  const extraExcludedMethods = filter?.excludeMethods
+    ? new Set(filter.excludeMethods)
+    : null;
+
+  // Walk prototype chain, collecting methods to wrap
+  let proto = Object.getPrototypeOf(instance);
+  while (proto && proto !== Object.prototype) {
+    const methodNames = Object.getOwnPropertyNames(proto);
+
+    for (const methodName of methodNames) {
+      // Skip built-in excluded methods
+      if (EXCLUDED_METHODS.has(methodName)) {
+        continue;
+      }
+
+      // Skip user-specified excluded methods
+      if (extraExcludedMethods?.has(methodName)) {
+        continue;
+      }
+
+      const descriptor = Object.getOwnPropertyDescriptor(proto, methodName);
+      if (!descriptor || !descriptor.value || typeof descriptor.value !== 'function') {
+        continue;
+      }
+
+      // Skip getters/setters
+      if (descriptor.get || descriptor.set) {
+        continue;
+      }
+
+      const method = descriptor.value;
+
+      // Skip already-traced methods (@Traced was applied manually)
+      if ((method as unknown as Record<symbol, boolean>)[ALREADY_TRACED]) {
+        continue;
+      }
+
+      // Skip @NoTrace methods
+      if ((method as unknown as Record<symbol, boolean>)[NO_TRACE]) {
+        continue;
+      }
+
+      // If asyncOnly, skip sync methods
+      if (asyncOnly && !isAsyncFunction(method)) {
+        continue;
+      }
+
+      wrapMethodWithSpan(proto, methodName, className);
+    }
+
+    proto = Object.getPrototypeOf(proto);
+  }
+}
+
+/**
+ * @TraceAll() — class decorator.
+ * Marks a class for auto-tracing even when traceAll is false in config.
+ *
+ * @example
+ * ```typescript
+ * \@Service()
+ * \@TraceAll()
+ * class UserService extends BaseService {
+ *   async findAll() { ... } // auto-traced
+ * }
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function TraceAll(): ClassDecorator {
+  return (target: Function) => {
+    (target as unknown as Record<symbol, boolean>)[TRACE_ALL] = true;
+  };
+}
+
+/**
+ * @NoTrace() — class or method decorator.
+ * Excludes a class or method from auto-tracing.
+ *
+ * On a class: prevents all methods from being auto-traced.
+ * On a method: prevents that specific method from being auto-traced.
+ * Note: @Traced() on a method takes priority over @NoTrace() on the class.
+ *
+ * @example
+ * ```typescript
+ * \@Service()
+ * \@NoTrace()
+ * class InternalService extends BaseService {
+ *   async internalWork() { ... } // NOT auto-traced
+ *
+ *   \@Traced() // Override: this method IS traced
+ *   async importantWork() { ... }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function NoTrace(): ClassDecorator & MethodDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => {
+    if (descriptor && propertyKey) {
+      // Method decorator
+      (descriptor.value as unknown as Record<symbol, boolean>)[NO_TRACE] = true;
+    } else {
+      // Class decorator
+      (target as unknown as Record<symbol, boolean>)[NO_TRACE] = true;
+    }
+  };
+}
+
+/**
+ * Check if a class should be auto-traced based on global config and decorators.
+ *
+ * @param classConstructor - The class constructor
+ * @param className - The class name
+ * @param traceAll - Global traceAll setting
+ * @param filter - Filter options
+ * @returns true if the class should have auto-tracing applied
+ */
+export function shouldAutoTrace(
+  classConstructor: Function,
+  className: string,
+  traceAll: boolean,
+  filter?: TraceFilterOptions,
+): boolean {
+  const hasTraceAll = (classConstructor as unknown as Record<symbol, boolean>)[TRACE_ALL] === true;
+  const hasNoTrace = (classConstructor as unknown as Record<symbol, boolean>)[NO_TRACE] === true;
+
+  // @NoTrace on class → skip (unless method-level @Traced, but that's handled in applyAutoTrace)
+  if (hasNoTrace) {
+    return false;
+  }
+
+  // @TraceAll on class → trace regardless of global setting
+  if (hasTraceAll) {
+    return matchesClassFilter(className, filter);
+  }
+
+  // Global traceAll
+  if (traceAll) {
+    return matchesClassFilter(className, filter);
+  }
+
+  return false;
+}

package/src/index.ts

@@ -15,13 +15,32 @@ export type { Context } from '@opentelemetry/api';
 export {
   createTraceMiddleware,
   Span,
+  SPAN_ATTRIBUTES,
+  SpanAttribute,
+  type SpanAttributeEntry,
   span,
-  // Backward compatibility aliases
+  Spanned,
   Trace,
+  Traced,
   TraceMiddleware,
   trace,
 } from './middleware.js';
 
+// Auto-trace
+export {
+  ALREADY_TRACED,
+  applyAutoTrace,
+  NO_TRACE,
+  NoTrace,
+  shouldAutoTrace,
+  TRACE_ALL,
+  TraceAll,
+  type TraceFilterOptions,
+} from './auto-trace.js';
+
+// OTLP exporter
+export { OtlpFetchSpanExporter, type OtlpExporterOptions } from './otlp-exporter.js';
+
 // Core service
 export {
   currentSpan,

package/src/middleware.ts

@@ -1,11 +1,90 @@
+import { SpanStatusCode as OtelSpanStatusCode, trace as otelTrace } from '@opentelemetry/api';
 import { Effect } from 'effect';
 
 import type { HttpTraceData, TraceHeaders } from './types.js';
 
 import { HttpStatusCode } from '@onebun/requests';
 
+import { ALREADY_TRACED } from './auto-trace.js';
 import { traceService } from './trace.service.js';
 
+/**
+ * Symbol for storing @SpanAttribute metadata on the prototype
+ */
+export const SPAN_ATTRIBUTES = Symbol.for('onebun:spanAttributes');
+
+/**
+ * Metadata entry for a @SpanAttribute parameter
+ */
+export interface SpanAttributeEntry {
+  paramIndex: number;
+  attrName: string;
+}
+
+/**
+ * Read @SpanAttribute metadata and set span attributes from method arguments
+ */
+function applySpanAttributes(
+  target: unknown,
+  methodName: string | symbol,
+  args: unknown[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  activeSpan: any,
+): void {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const meta = (target as any)?.[SPAN_ATTRIBUTES]?.[String(methodName)] as
+    | SpanAttributeEntry[]
+    | undefined;
+  if (!meta) {
+    return;
+  }
+
+  for (const { paramIndex, attrName } of meta) {
+    const value = args[paramIndex];
+    if (value === undefined || value === null) {
+      continue;
+    }
+
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      activeSpan.setAttribute(attrName, value);
+    } else {
+      activeSpan.setAttribute(attrName, JSON.stringify(value));
+    }
+  }
+}
+
+/**
+ * @SpanAttribute() — parameter decorator.
+ * Automatically records the method argument as a span attribute when used
+ * with @Traced() or @Spanned().
+ *
+ * @param name - The span attribute name (e.g. 'user.id', 'db.operation')
+ *
+ * @example
+ * ```typescript
+ * \@Traced()
+ * async findById(
+ *   \@SpanAttribute('user.id') id: string,
+ * ): Promise<User | null> { ... }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function SpanAttribute(name: string): ParameterDecorator {
+  return (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => {
+    if (!propertyKey) {
+      return;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const existing = (target as any)[SPAN_ATTRIBUTES] ?? {};
+    const key = String(propertyKey);
+    existing[key] = existing[key] ?? [];
+    existing[key].push({ paramIndex: parameterIndex, attrName: name });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (target as any)[SPAN_ATTRIBUTES] = existing;
+  };
+}
+
 /**
  * HTTP trace middleware for OneBun applications
  */
@@ -183,7 +262,21 @@ export const createTraceMiddleware = (): TraceMiddleware => {
 };
 
 /**
- * Trace decorator for controller methods
+ * Trace decorator for async/await controller and service methods.
+ *
+ * Creates an OpenTelemetry span around the decorated method. Works with
+ * methods that return Promises — the span is automatically ended when
+ * the Promise resolves or rejects.
+ *
+ * @param operationName - Custom span name. Defaults to `ClassName.methodName`
+ *
+ * @example
+ * ```typescript
+ * class WorkspaceService extends BaseService {
+ *   \@Traced('workspace.findAll')
+ *   async findAll(): Promise<Workspace[]> { ... }
+ * }
+ * ```
  */
 export function trace(operationName?: string): MethodDecorator {
   return (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
@@ -193,61 +286,45 @@ export function trace(operationName?: string): MethodDecorator {
         ? 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,
-                  }),
-              );
-            }),
-          );
-        }),
-      );
+    const decoratorTarget = target;
+
+    const wrapped = async function (this: unknown, ...args: unknown[]) {
+      const tracer = otelTrace.getTracer('@onebun/trace');
+
+      return await tracer.startActiveSpan(spanName, async (activeSpan) => {
+        applySpanAttributes(decoratorTarget, propertyKey, args, activeSpan);
+
+        try {
+          const result = await originalMethod.apply(this, args);
+          activeSpan.setStatus({ code: OtelSpanStatusCode.OK });
+
+          return result;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          activeSpan.setStatus({ code: OtelSpanStatusCode.ERROR, message: err.message });
+          activeSpan.recordException(err);
+          throw error;
+        } finally {
+          activeSpan.end();
+        }
+      });
     };
 
+    // Mark as traced to prevent auto-trace from double-wrapping
+    (wrapped as unknown as Record<symbol, boolean>)[ALREADY_TRACED] = true;
+    descriptor.value = wrapped;
+
     return descriptor;
   };
 }
 
 /**
- * Span decorator for creating custom spans
+ * Span decorator for creating custom spans around async methods.
+ *
+ * Lighter version of \@trace — creates a span without automatic error attribute
+ * enrichment. Best for internal methods where you want basic span tracking.
+ *
+ * @param name - Custom span name. Defaults to `ClassName.methodName`
  */
 export function span(name?: string): MethodDecorator {
   return (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
@@ -256,28 +333,43 @@ export function span(name?: string): MethodDecorator {
       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),
-              ),
-          ),
-        ),
-      );
+    const resolvedName = name || `${targetConstructor.name}.${String(propertyKey)}`;
+    const decoratorTarget = target;
+
+    const wrapped = async function (this: unknown, ...args: unknown[]) {
+      const tracer = otelTrace.getTracer('@onebun/trace');
+
+      return await tracer.startActiveSpan(resolvedName, async (activeSpan) => {
+        applySpanAttributes(decoratorTarget, propertyKey, args, activeSpan);
+
+        try {
+          const result = await originalMethod.apply(this, args);
+
+          return result;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          activeSpan.setStatus({ code: OtelSpanStatusCode.ERROR, message: err.message });
+          throw error;
+        } finally {
+          activeSpan.end();
+        }
+      });
     };
 
+    // Mark as traced to prevent auto-trace from double-wrapping
+    (wrapped as unknown as Record<symbol, boolean>)[ALREADY_TRACED] = true;
+    descriptor.value = wrapped;
+
     return descriptor;
   };
 }
 
-// Backward compatibility aliases
+// Aliases — all point to the same async-compatible implementations
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Trace = trace;
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Span = span;
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Traced = trace;
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Spanned = span;

package/src/otlp-exporter.ts

@@ -0,0 +1,245 @@
+import { ExportResultCode } from '@opentelemetry/core';
+
+import type { ExportResult } from '@opentelemetry/core';
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+
+/**
+ * OTLP Span Exporter options
+ */
+export interface OtlpExporterOptions {
+  /**
+   * OTLP endpoint URL (e.g. 'http://localhost:4318')
+   */
+  endpoint: string;
+
+  /**
+   * Custom HTTP headers for export requests
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Request timeout in milliseconds
+   * @defaultValue 10000
+   */
+  timeout?: number;
+}
+
+const DEFAULT_TIMEOUT = 10000;
+const NANOSECONDS_PER_MILLISECOND = 1000000;
+const NANOSECONDS_PER_SECOND = 1000000000;
+
+/**
+ * Convert hrtime [seconds, nanoseconds] to nanosecond string
+ */
+function hrTimeToNanos(hrTime: [number, number]): string {
+  const nanos = BigInt(hrTime[0]) * BigInt(NANOSECONDS_PER_SECOND) + BigInt(hrTime[1]);
+
+  return nanos.toString();
+}
+
+/**
+ * Convert OTel attribute value to OTLP JSON attribute value
+ */
+function toOtlpValue(value: unknown): Record<string, unknown> {
+  if (typeof value === 'string') {
+    return { stringValue: value };
+  }
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };
+  }
+  if (typeof value === 'boolean') {
+    return { boolValue: value };
+  }
+
+  return { stringValue: String(value) };
+}
+
+/**
+ * Convert OTel attributes to OTLP JSON format
+ */
+function toOtlpAttributes(
+  attributes: Record<string, unknown>,
+): Array<{ key: string; value: Record<string, unknown> }> {
+  return Object.entries(attributes).map(([key, value]) => ({
+    key,
+    value: toOtlpValue(value),
+  }));
+}
+
+/**
+ * Map OTel SpanKind to OTLP integer
+ */
+function mapSpanKind(kind: number): number {
+  // OTel SpanKind: INTERNAL=0, SERVER=1, CLIENT=2, PRODUCER=3, CONSUMER=4
+  // OTLP:          INTERNAL=1, SERVER=2, CLIENT=3, PRODUCER=4, CONSUMER=5
+  return kind + 1;
+}
+
+/**
+ * Map OTel SpanStatusCode to OTLP status code
+ */
+function mapStatusCode(code: number): number {
+  // OTel: UNSET=0, OK=1, ERROR=2
+  // OTLP: STATUS_CODE_UNSET=0, STATUS_CODE_OK=1, STATUS_CODE_ERROR=2
+  return code;
+}
+
+/**
+ * Convert a ReadableSpan to OTLP JSON span format
+ */
+function spanToOtlp(span: ReadableSpan): Record<string, unknown> {
+  const spanContext = span.spanContext();
+
+  const otlpSpan: Record<string, unknown> = {
+    traceId: spanContext.traceId,
+    spanId: spanContext.spanId,
+    name: span.name,
+    kind: mapSpanKind(span.kind),
+    startTimeUnixNano: hrTimeToNanos(span.startTime),
+    endTimeUnixNano: hrTimeToNanos(span.endTime),
+    attributes: toOtlpAttributes(span.attributes as Record<string, unknown>),
+    status: {
+      code: mapStatusCode(span.status.code),
+      message: span.status.message || '',
+    },
+    events: span.events.map((event) => ({
+      timeUnixNano: hrTimeToNanos(event.time),
+      name: event.name,
+      attributes: event.attributes
+        ? toOtlpAttributes(event.attributes as Record<string, unknown>)
+        : [],
+    })),
+    links: span.links.map((link) => ({
+      traceId: link.context.traceId,
+      spanId: link.context.spanId,
+      attributes: link.attributes
+        ? toOtlpAttributes(link.attributes as Record<string, unknown>)
+        : [],
+    })),
+  };
+
+  if (span.parentSpanContext?.spanId) {
+    otlpSpan.parentSpanId = span.parentSpanContext.spanId;
+  }
+
+  if (span.droppedAttributesCount > 0) {
+    otlpSpan.droppedAttributesCount = span.droppedAttributesCount;
+  }
+
+  if (span.droppedEventsCount > 0) {
+    otlpSpan.droppedEventsCount = span.droppedEventsCount;
+  }
+
+  if (span.droppedLinksCount > 0) {
+    otlpSpan.droppedLinksCount = span.droppedLinksCount;
+  }
+
+  return otlpSpan;
+}
+
+/**
+ * Custom OTLP Span Exporter using native fetch() for Bun compatibility.
+ *
+ * Unlike @opentelemetry/exporter-trace-otlp-http which relies on XMLHttpRequest
+ * or Node's http module, this exporter uses the native fetch() API that is
+ * guaranteed to work in Bun.
+ */
+export class OtlpFetchSpanExporter implements SpanExporter {
+  private readonly endpoint: string;
+  private readonly headers: Record<string, string>;
+  private readonly timeout: number;
+  private isShutdown = false;
+
+  constructor(options: OtlpExporterOptions) {
+    this.endpoint = options.endpoint.replace(/\/$/, '');
+    this.headers = {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      'Content-Type': 'application/json',
+      ...options.headers,
+    };
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  }
+
+  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
+    if (this.isShutdown) {
+      resultCallback({ code: ExportResultCode.FAILED });
+
+      return;
+    }
+
+    this.sendSpans(spans)
+      .then(() => {
+        resultCallback({ code: ExportResultCode.SUCCESS });
+      })
+      .catch(() => {
+        resultCallback({ code: ExportResultCode.FAILED });
+      });
+  }
+
+  async shutdown(): Promise<void> {
+    this.isShutdown = true;
+  }
+
+  async forceFlush(): Promise<void> {
+    // No internal buffering — BatchSpanProcessor handles batching
+  }
+
+  private async sendSpans(spans: ReadableSpan[]): Promise<void> {
+    if (spans.length === 0) {
+      return;
+    }
+
+    // Group spans by instrumentation scope
+    const scopeSpans = new Map<string, Record<string, unknown>[]>();
+    for (const span of spans) {
+      const scopeName = span.instrumentationScope.name;
+      if (!scopeSpans.has(scopeName)) {
+        scopeSpans.set(scopeName, []);
+      }
+      scopeSpans.get(scopeName)!.push(spanToOtlp(span));
+    }
+
+    // Build resource attributes from the first span's resource
+    const resource = spans[0].resource;
+    const resourceAttributes = toOtlpAttributes(
+      resource.attributes as Record<string, unknown>,
+    );
+
+    const payload = {
+      resourceSpans: [
+        {
+          resource: { attributes: resourceAttributes },
+          scopeSpans: Array.from(scopeSpans.entries()).map(([name, scopeSpanList]) => ({
+            scope: { name },
+            spans: scopeSpanList,
+          })),
+        },
+      ],
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.endpoint}/v1/traces`, {
+        method: 'POST',
+        headers: this.headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`OTLP export failed: ${response.status} ${response.statusText}`);
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+/**
+ * Utility: convert milliseconds to nanosecond string
+ */
+export function msToNanos(ms: number): string {
+  return (BigInt(Math.round(ms)) * BigInt(NANOSECONDS_PER_MILLISECOND)).toString();
+}

package/src/provider.ts

@@ -0,0 +1,73 @@
+import { trace } from '@opentelemetry/api';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BatchSpanProcessor, BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+import type { TraceOptions } from './types.js';
+
+import { OtlpFetchSpanExporter } from './otlp-exporter.js';
+
+/**
+ * Result of TracerProvider initialization
+ */
+export interface TracerProviderResult {
+  /**
+   * The initialized BasicTracerProvider
+   */
+  provider: BasicTracerProvider;
+
+  /**
+   * Shutdown function that flushes pending spans and shuts down the provider
+   */
+  shutdown: () => Promise<void>;
+}
+
+/**
+ * Initialize and register a global TracerProvider.
+ *
+ * When `exportOptions.endpoint` is configured, creates a BatchSpanProcessor
+ * with a custom fetch-based OTLP exporter for Bun compatibility.
+ *
+ * @param options - Trace configuration options
+ * @returns Provider instance and shutdown function
+ */
+export function initTracerProvider(options: TraceOptions): TracerProviderResult {
+  const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: options.serviceName ?? 'onebun-service',
+    [ATTR_SERVICE_VERSION]: options.serviceVersion ?? '1.0.0',
+  });
+
+  const spanProcessors = [];
+
+  if (options.exportOptions?.endpoint) {
+    const exporter = new OtlpFetchSpanExporter({
+      endpoint: options.exportOptions.endpoint,
+      headers: options.exportOptions.headers,
+      timeout: options.exportOptions.timeout,
+    });
+
+    spanProcessors.push(
+      new BatchSpanProcessor(exporter, {
+        maxExportBatchSize: options.exportOptions.batchSize,
+        scheduledDelayMillis: options.exportOptions.batchTimeout,
+      }),
+    );
+  }
+
+  const provider = new BasicTracerProvider({
+    resource,
+    spanProcessors,
+  });
+
+  // Register as global TracerProvider so trace.getTracer() returns real tracers
+  trace.setGlobalTracerProvider(provider);
+
+  return {
+    provider,
+    async shutdown() {
+      await provider.shutdown();
+      // Disable the global provider to avoid using a shutdown provider
+      trace.disable();
+    },
+  };
+}

package/src/trace.service.ts

@@ -13,6 +13,7 @@ import {
 
 import { HttpStatusCode } from '@onebun/requests';
 
+import { initTracerProvider, type TracerProviderResult } from './provider.js';
 import {
   type HttpTraceData,
   type SpanStatus,
@@ -89,6 +90,11 @@ export interface TraceService {
    * End HTTP request tracing
    */
   endHttpTrace(span: TraceSpan, data: Partial<HttpTraceData>): Effect.Effect<void>;
+
+  /**
+   * Shutdown the trace service, flushing pending spans
+   */
+  shutdown(): Promise<void>;
 }
 
 /**
@@ -111,8 +117,9 @@ 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 tracer;
   private readonly options: Required<TraceOptions>;
+  private readonly providerResult: TracerProviderResult | null = null;
 
   constructor(options: TraceOptions = {}) {
     this.options = {
@@ -126,6 +133,20 @@ export class TraceServiceImpl implements TraceService {
       exportOptions: {},
       ...options,
     };
+
+    // Initialize TracerProvider BEFORE creating the tracer
+    // so trace.getTracer() returns a real tracer, not NoopTracer
+    if (this.options.enabled) {
+      this.providerResult = initTracerProvider(this.options);
+    }
+
+    this.tracer = trace.getTracer('@onebun/trace');
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.providerResult) {
+      await this.providerResult.shutdown();
+    }
   }
 
   getCurrentContext(): Effect.Effect<TraceContext | null> {