@onebun/trace 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/trace",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.0"
+    "@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/index.ts

@@ -16,12 +16,16 @@ export {
   createTraceMiddleware,
   Span,
   span,
-  // Backward compatibility aliases
+  Spanned,
   Trace,
+  Traced,
   TraceMiddleware,
   trace,
 } from './middleware.js';
 
+// OTLP exporter
+export { OtlpFetchSpanExporter, type OtlpExporterOptions } from './otlp-exporter.js';
+
 // Core service
 export {
   currentSpan,

package/src/middleware.ts

@@ -1,3 +1,4 @@
+import { SpanStatusCode as OtelSpanStatusCode, trace as otelTrace } from '@opentelemetry/api';
 import { Effect } from 'effect';
 
 import type { HttpTraceData, TraceHeaders } from './types.js';
@@ -183,7 +184,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) => {
@@ -194,52 +209,24 @@ export function trace(operationName?: string): MethodDecorator {
         : { 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,
-                  }),
-              );
-            }),
-          );
-        }),
-      );
+    descriptor.value = async function (...args: unknown[]) {
+      const tracer = otelTrace.getTracer('@onebun/trace');
+
+      return await tracer.startActiveSpan(spanName, async (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();
+        }
+      });
     };
 
     return descriptor;
@@ -247,7 +234,12 @@ export function trace(operationName?: string): MethodDecorator {
 }
 
 /**
- * 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) => {
@@ -258,26 +250,34 @@ export function span(name?: string): MethodDecorator {
         : { 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),
-              ),
-          ),
-        ),
-      );
+    descriptor.value = async function (...args: unknown[]) {
+      const tracer = otelTrace.getTracer('@onebun/trace');
+
+      return await tracer.startActiveSpan(spanName, async (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();
+        }
+      });
     };
 
     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> {