duron 0.3.0-beta.5 → 0.3.0-beta.7

package/src/telemetry/adapter.ts

@@ -108,6 +108,106 @@ export interface AddSpanAttributeOptions {
   value: string | number | boolean
 }
 
+/**
+ * Options for starting a custom span with the tracer.
+ */
+export interface StartSpanOptions {
+  /**
+   * Span kind (internal, client, server, producer, consumer).
+   * @default 'internal'
+   */
+  kind?: 'internal' | 'client' | 'server' | 'producer' | 'consumer'
+
+  /**
+   * Initial attributes for the span.
+   */
+  attributes?: Record<string, string | number | boolean>
+
+  /**
+   * Parent span to use for context propagation.
+   * If not provided, uses the current active context.
+   */
+  parentSpan?: TracerSpan
+}
+
+/**
+ * A span created by the Tracer for manual instrumentation.
+ */
+export interface TracerSpan {
+  /**
+   * Set an attribute on the span.
+   *
+   * @param key - The attribute key
+   * @param value - The attribute value
+   */
+  setAttribute(key: string, value: string | number | boolean): void
+
+  /**
+   * Set multiple attributes on the span.
+   *
+   * @param attributes - The attributes to set
+   */
+  setAttributes(attributes: Record<string, string | number | boolean>): void
+
+  /**
+   * Add an event to the span.
+   *
+   * @param name - The event name
+   * @param attributes - Optional event attributes
+   */
+  addEvent(name: string, attributes?: Record<string, string | number | boolean>): void
+
+  /**
+   * Record an exception on the span.
+   *
+   * @param error - The error to record
+   */
+  recordException(error: Error): void
+
+  /**
+   * Set the span status to OK.
+   */
+  setStatusOk(): void
+
+  /**
+   * Set the span status to error.
+   *
+   * @param message - Optional error message
+   */
+  setStatusError(message?: string): void
+
+  /**
+   * End the span.
+   * After calling this, no more operations can be performed on the span.
+   */
+  end(): void
+
+  /**
+   * Check if this span is recording.
+   */
+  isRecording(): boolean
+}
+
+/**
+ * A Tracer provides methods for creating spans.
+ * Similar to OpenTelemetry's Tracer interface.
+ */
+export interface Tracer {
+  /**
+   * The name of this tracer.
+   */
+  readonly name: string
+
+  /**
+   * Start a new span.
+   *
+   * @param name - The name of the span
+   * @param options - Optional span configuration
+   * @returns A TracerSpan for manual instrumentation
+   */
+  startSpan(name: string, options?: StartSpanOptions): TracerSpan
+}
+
 /**
  * Observe context provided to action and step handlers.
  */
@@ -136,6 +236,37 @@ export interface ObserveContext {
    * @param attributes - Optional event attributes
    */
   addSpanEvent(name: string, attributes?: Record<string, any>): void
+
+  /**
+   * Get a tracer for manual instrumentation.
+   * Similar to OpenTelemetry's `trace.getTracer()` method.
+   *
+   * @param name - The name of the tracer (typically your service or library name)
+   * @returns A Tracer for creating custom spans
+   *
+   * @example
+   * ```typescript
+   * const tracer = ctx.observe.getTracer('my-service')
+   *
+   * const span = tracer.startSpan('external-api-call', {
+   *   kind: 'client',
+   *   attributes: { 'api.endpoint': '/users' }
+   * })
+   *
+   * try {
+   *   const result = await fetch('https://api.example.com/users')
+   *   span.setStatusOk()
+   *   return result
+   * } catch (error) {
+   *   span.recordException(error)
+   *   span.setStatusError(error.message)
+   *   throw error
+   * } finally {
+   *   span.end()
+   * }
+   * ```
+   */
+  getTracer(name: string): Tracer
 }
 
 // ============================================================================
@@ -369,6 +500,41 @@ export abstract class TelemetryAdapter {
     return this._addSpanAttribute(options)
   }
 
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  /**
+   * Get a tracer for manual instrumentation.
+   * Similar to OpenTelemetry's `trace.getTracer()` method.
+   *
+   * @param name - The name of the tracer (typically your service or library name)
+   * @returns A Tracer for creating custom spans
+   *
+   * @example
+   * ```typescript
+   * const tracer = telemetry.getTracer('my-service')
+   *
+   * const span = tracer.startSpan('process-order', {
+   *   attributes: { 'order.id': orderId }
+   * })
+   *
+   * try {
+   *   // Do some work
+   *   span.addEvent('order.validated')
+   *   span.setStatusOk()
+   * } catch (error) {
+   *   span.recordException(error)
+   *   span.setStatusError(error.message)
+   * } finally {
+   *   span.end()
+   * }
+   * ```
+   */
+  getTracer(name: string): Tracer {
+    return this._getTracer(name)
+  }
+
   // ============================================================================
   // Context Methods
   // ============================================================================
@@ -404,6 +570,9 @@ export abstract class TelemetryAdapter {
           this.#logger?.error(err, 'Error adding span event')
         })
       },
+      getTracer: (name: string) => {
+        return this.getTracer(name)
+      },
     }
   }
 
@@ -465,4 +634,9 @@ export abstract class TelemetryAdapter {
    * Internal method to add a span attribute.
    */
   protected abstract _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>
+
+  /**
+   * Internal method to get a tracer for manual instrumentation.
+   */
+  protected abstract _getTracer(name: string): Tracer
 }

package/src/telemetry/index.ts

@@ -9,8 +9,11 @@ export {
   type Span,
   type StartDatabaseSpanOptions,
   type StartJobSpanOptions,
+  type StartSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 export { LocalTelemetryAdapter, type LocalTelemetryAdapterOptions, localTelemetryAdapter } from './local.js'
 export { NoopTelemetryAdapter, noopTelemetryAdapter } from './noop.js'

package/src/telemetry/local.ts

@@ -7,8 +7,11 @@ import {
   type Span,
   type StartDatabaseSpanOptions,
   type StartJobSpanOptions,
+  type StartSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 
 // ============================================================================
@@ -304,6 +307,96 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
       },
     })
   }
+
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  protected _getTracer(name: string): Tracer {
+    const adapter = this
+
+    return {
+      name,
+
+      startSpan(spanName: string, options?: StartSpanOptions): TracerSpan {
+        const spanId = `tracer:${name}:${globalThis.crypto.randomUUID()}`
+        const startTime = Date.now()
+        let ended = false
+        const attributes: Record<string, string | number | boolean> = {
+          ...options?.attributes,
+        }
+
+        // Note: Local adapter tracer spans don't have a jobId context,
+        // so they can't be stored in the database. They're essentially no-ops
+        // but provide a consistent API for code that needs a tracer.
+        // For actual metrics storage, use ctx.observe within action/step handlers.
+
+        const tracerSpan: TracerSpan = {
+          setAttribute(key: string, value: string | number | boolean): void {
+            if (!ended) {
+              attributes[key] = value
+            }
+          },
+
+          setAttributes(attrs: Record<string, string | number | boolean>): void {
+            if (!ended) {
+              Object.assign(attributes, attrs)
+            }
+          },
+
+          addEvent(eventName: string, eventAttrs?: Record<string, string | number | boolean>): void {
+            if (!ended) {
+              adapter.logger?.debug({ spanId, event: eventName, attributes: eventAttrs }, 'Tracer span event')
+            }
+          },
+
+          recordException(error: Error): void {
+            if (!ended) {
+              attributes['error.message'] = error.message
+              attributes['error.name'] = error.name
+              adapter.logger?.debug({ spanId, error: error.message }, 'Tracer span exception')
+            }
+          },
+
+          setStatusOk(): void {
+            if (!ended) {
+              // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
+              attributes['status'] = 'ok'
+            }
+          },
+
+          setStatusError(message?: string): void {
+            if (!ended) {
+              // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
+              attributes['status'] = 'error'
+              if (message) {
+                attributes['status.message'] = message
+              }
+            }
+          },
+
+          end(): void {
+            if (!ended) {
+              ended = true
+              const duration = Date.now() - startTime
+              adapter.logger?.debug(
+                { spanId, spanName, tracerName: name, durationMs: duration, attributes },
+                'Tracer span ended',
+              )
+            }
+          },
+
+          isRecording(): boolean {
+            return !ended
+          },
+        }
+
+        adapter.logger?.debug({ spanId, spanName, tracerName: name }, 'Tracer span started')
+
+        return tracerSpan
+      },
+    }
+  }
 }
 
 /**

package/src/telemetry/noop.ts

@@ -8,8 +8,41 @@ import {
   type StartJobSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 
+// ============================================================================
+// Noop Tracer Span
+// ============================================================================
+
+const noopTracerSpan: TracerSpan = {
+  setAttribute() {
+    // No-op
+  },
+  setAttributes() {
+    // No-op
+  },
+  addEvent() {
+    // No-op
+  },
+  recordException() {
+    // No-op
+  },
+  setStatusOk() {
+    // No-op
+  },
+  setStatusError() {
+    // No-op
+  },
+  end() {
+    // No-op
+  },
+  isRecording() {
+    return false
+  },
+}
+
 // ============================================================================
 // Noop Telemetry Adapter
 // ============================================================================
@@ -84,6 +117,19 @@ export class NoopTelemetryAdapter extends TelemetryAdapter {
   protected async _addSpanAttribute(_options: AddSpanAttributeOptions): Promise<void> {
     // No-op
   }
+
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  protected _getTracer(name: string): Tracer {
+    return {
+      name,
+      startSpan(): TracerSpan {
+        return noopTracerSpan
+      },
+    }
+  }
 }
 
 /**

package/src/telemetry/opentelemetry.ts

@@ -1,4 +1,4 @@
-import type { Span as OTelSpan, Tracer, TracerProvider } from '@opentelemetry/api'
+import type { Span as OTelSpan, Tracer as OTelTracer, TracerProvider } from '@opentelemetry/api'
 
 import {
   type AddSpanAttributeOptions,
@@ -8,8 +8,11 @@ import {
   type Span,
   type StartDatabaseSpanOptions,
   type StartJobSpanOptions,
+  type StartSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 
 // ============================================================================
@@ -52,8 +55,9 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
   #serviceName: string
   #tracerProvider: TracerProvider | null
   #traceDatabaseQueries: boolean
-  #tracer: Tracer | null = null
+  #tracer: OTelTracer | null = null
   #spanMap = new Map<string, OTelSpan>()
+  #tracerCache = new Map<string, Tracer>()
 
   constructor(options: OpenTelemetryAdapterOptions = {}) {
     super()
@@ -298,6 +302,145 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
       extSpan.otelSpan.setAttribute(options.key, options.value)
     }
   }
+
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  protected _getTracer(name: string): Tracer {
+    // Return cached tracer if available
+    const cached = this.#tracerCache.get(name)
+    if (cached) {
+      return cached
+    }
+
+    const adapter = this
+
+    const tracer: Tracer = {
+      name,
+
+      startSpan(spanName: string, options?: StartSpanOptions): TracerSpan {
+        // We need to dynamically get the OpenTelemetry API
+        // Since _getTracer is synchronous, we need to handle this carefully
+        let otelSpan: OTelSpan | null = null
+        let api: typeof import('@opentelemetry/api') | null = null
+        let ended = false
+
+        // Initialize the span asynchronously but return synchronously
+        const initPromise = (async () => {
+          api = await import('@opentelemetry/api')
+
+          // Get the tracer
+          let otelTracer: OTelTracer
+          if (adapter.#tracerProvider) {
+            otelTracer = adapter.#tracerProvider.getTracer(name)
+          } else {
+            otelTracer = api.trace.getTracer(name)
+          }
+
+          // Map kind
+          let spanKind = api.SpanKind.INTERNAL
+          if (options?.kind === 'client') spanKind = api.SpanKind.CLIENT
+          else if (options?.kind === 'server') spanKind = api.SpanKind.SERVER
+          else if (options?.kind === 'producer') spanKind = api.SpanKind.PRODUCER
+          else if (options?.kind === 'consumer') spanKind = api.SpanKind.CONSUMER
+
+          // Get parent context
+          let parentContext = api.context.active()
+          if (options?.parentSpan) {
+            const parentOtelSpan = (options.parentSpan as any)._otelSpan as OTelSpan | undefined
+            if (parentOtelSpan) {
+              parentContext = api.trace.setSpan(api.context.active(), parentOtelSpan)
+            }
+          }
+
+          otelSpan = otelTracer.startSpan(
+            spanName,
+            {
+              kind: spanKind,
+              attributes: options?.attributes,
+            },
+            parentContext,
+          )
+        })()
+
+        const tracerSpan: TracerSpan & { _otelSpan?: OTelSpan } = {
+          setAttribute(key: string, value: string | number | boolean): void {
+            initPromise.then(() => {
+              if (otelSpan && !ended) {
+                otelSpan.setAttribute(key, value)
+              }
+            })
+          },
+
+          setAttributes(attributes: Record<string, string | number | boolean>): void {
+            initPromise.then(() => {
+              if (otelSpan && !ended) {
+                otelSpan.setAttributes(attributes)
+              }
+            })
+          },
+
+          addEvent(eventName: string, attributes?: Record<string, string | number | boolean>): void {
+            initPromise.then(() => {
+              if (otelSpan && !ended) {
+                otelSpan.addEvent(eventName, attributes)
+              }
+            })
+          },
+
+          recordException(error: Error): void {
+            initPromise.then(() => {
+              if (otelSpan && !ended) {
+                otelSpan.recordException(error)
+              }
+            })
+          },
+
+          setStatusOk(): void {
+            initPromise.then(() => {
+              if (otelSpan && api && !ended) {
+                otelSpan.setStatus({ code: api.SpanStatusCode.OK })
+              }
+            })
+          },
+
+          setStatusError(message?: string): void {
+            initPromise.then(() => {
+              if (otelSpan && api && !ended) {
+                otelSpan.setStatus({ code: api.SpanStatusCode.ERROR, message })
+              }
+            })
+          },
+
+          end(): void {
+            initPromise.then(() => {
+              if (otelSpan && !ended) {
+                ended = true
+                otelSpan.end()
+              }
+            })
+          },
+
+          isRecording(): boolean {
+            return otelSpan?.isRecording() ?? false
+          },
+        }
+
+        // Store reference for parent context propagation
+        initPromise.then(() => {
+          if (otelSpan) {
+            ;(tracerSpan as any)._otelSpan = otelSpan
+          }
+        })
+
+        return tracerSpan
+      },
+    }
+
+    this.#tracerCache.set(name, tracer)
+    return tracer
+  }
 }
 
 /**