@zerotal/telemetry 1.6.2 → 1.7.0

package/api-surface.md

@@ -0,0 +1,159 @@
+# @zerotal/telemetry — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class ConsoleExporter = {
+  new (): ConsoleExporter
+  export: (span: SpanData) => Promise<void>
+}
+
+class NoopExporter = {
+  new (): NoopExporter
+  export: (_span: SpanData) => Promise<void>
+}
+
+class NoopSpan = {
+  new (): NoopSpan
+  addEvent: (_name: string, _attributes?: Record<string, unknown>) => NoopSpan
+  durationMs: number
+  end: () => void
+  isEnded: boolean
+  readonly data: SpanData
+  recordException: (_error: Error) => NoopSpan
+  setAttribute: (_key: string, _value: string | number | boolean) => NoopSpan
+  setAttributes: (_attrs: Record<string, string | number | boolean>) => NoopSpan
+  setStatus: (_code: 'ok' | 'error', _message?: string) => NoopSpan
+}
+
+class OtlpExporter = {
+  new (options?: OtlpExporterOptions): OtlpExporter
+  export: (span: SpanData) => Promise<void>
+}
+
+class Span = {
+  new (name: string, parentId?: string, traceId?: string, kind?: SpanKind): Span
+  addEvent: (name: string, attributes?: Record<string, unknown>) => Span
+  durationMs: number
+  end: () => void
+  isEnded: boolean
+  readonly data: SpanData
+  recordException: (error: Error) => Span
+  setAttribute: (key: string, value: string | number | boolean) => Span
+  setAttributes: (attrs: Record<string, string | number | boolean>) => Span
+  setStatus: (code: 'ok' | 'error', message?: string) => Span
+}
+
+class TelemetryMiddleware = {
+  new (): TelemetryMiddleware
+  static with: <T extends new (...args: any[]) => BaseMiddleware<any>, Opts = T extends new (...args: any[]) => BaseMiddleware<infer U> ? U : object>(this: T, options: DeepPartial<NoInfer<Opts>>) => new () => InstanceType<T>
+  afterResponse?: (ctx: HttpContext) => Promise<void>
+  handle: (http: HttpContext, next: NextFn) => Promise<Response | void>
+  onError?: (ctx: HttpContext, error: Error) => Promise<void>
+}
+
+class TelemetryProvider = {
+  new (app: Application): TelemetryProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly ['telemetry']
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class Tracer = {
+  new (options: TracerOptions): Tracer
+  recordCompleted: (name: string, durationMs: number, options?: SpanOptions & {    status?: 'ok' | 'error';    errorMessage?: string;}) => Promise<void>
+  shutdown: () => Promise<void>
+  startSpan: (name: string, options?: SpanOptions) => Span
+  withSpan: <T>(name: string, fn: (span: Span) => Promise<T>, options?: SpanOptions) => Promise<T>
+}
+
+const SpanContext = AsyncLocalStorage<ActiveContext>
+
+function _randomHex = (bytes: number) => string
+
+function currentSpan = () => Span | undefined
+
+function installEventBridge = (tracer: Tracer) => () => void
+
+function TelemetryConfig = (options?: Partial<TelemetryConfigShape>) => TelemetryConfigShape
+
+function withSpan = <T>(name: string, fn: (span: Span) => Promise<T>, options?: SpanOptions) => Promise<T>
+
+interface OtlpExporterOptions = {
+  endpoint?: string
+  headers?: Record<string, string>
+  serviceName?: string
+  serviceVersion?: string
+}
+
+interface SpanData = {
+  attributes: Record<string, string | number | boolean>
+  endMs: number | undefined
+  events: SpanEvent[]
+  kind: SpanKind
+  name: string
+  parentId: string | undefined
+  spanId: string
+  startMs: number
+  status: SpanStatus
+  traceId: string
+}
+
+interface SpanEvent = {
+  attributes?: Record<string, unknown>
+  name: string
+  timeMs: number
+}
+
+interface SpanExporter = {
+  export: (span: SpanData) => Promise<void>
+  shutdown?: () => Promise<void>
+}
+
+interface SpanOptions = {
+  attributes?: Record<string, string | number | boolean>
+  kind?: SpanKind
+}
+
+interface SpanStatus = {
+  code: SpanStatusCode
+  message?: string
+}
+
+interface TelemetryConfigShape = {
+  exporter?: 'console' | 'noop' | 'otlp'
+  minDurationMs?: number
+  otlp?: {    endpoint?: string;    headers?: Record<string, string>;}
+  serviceName?: string
+  serviceVersion?: string
+}
+
+interface TelemetryOptions = {
+  spanName?: (ctx: HttpContext) => string
+}
+
+interface TracerOptions = {
+  exporter: SpanExporter
+  minDurationMs?: number
+  rethrowExportErrors?: boolean
+}
+
+type SpanKind = 'client' | 'internal' | 'server' | 'producer' | 'consumer'
+
+type SpanStatusCode = 'error' | 'ok' | 'unset'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/telemetry",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -12,6 +12,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -29,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.2"
+    "@zerotal/core": "1.7.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"