autotel/src/index.ts

Write Once, Observe Anywhere

/**
 * autotel - Simplified OpenTelemetry instrumentation
 *
 * @example Minimal setup
 * ```typescript
 * import { init, trace, track } from 'autotel'
 *
 * init({ service: 'my-app' })
 *
 * export const createUser = trace(ctx => async (data: CreateUserData) => {
 *   track('user.signup', { userId: data.id, plan: data.plan })
 * })
 * ```
 *
 * @example With events
 * ```typescript
 * import { init, trace, track } from 'autotel'
 * import { PostHogSubscriber } from 'autotel-subscribers'
 *
 * init({
 *   service: 'my-app',
 *   subscribers: [new PostHogSubscriber({ apiKey: '...' })]
 * })
 *
 * export const createUser = trace(ctx => async (data: CreateUserData) => {
 *   track('user.signup', { userId: data.id })
 * })
 * ```
 */

// Core initialization
export { init, lockLogger, isLoggerLocked, type AutotelConfig } from './init';

// Baggage span processor
export {
  BaggageSpanProcessor,
  type BaggageSpanProcessorOptions,
} from './baggage-span-processor';

// Filtering span processor
export {
  FilteringSpanProcessor,
  type SpanFilterPredicate,
  type FilteringSpanProcessorOptions,
} from './filtering-span-processor';

// Span name normalizer
export {
  SpanNameNormalizingProcessor,
  NORMALIZER_PATTERNS,
  NORMALIZER_PRESETS,
  type SpanNameNormalizerFn,
  type SpanNameNormalizerPreset,
  type SpanNameNormalizerConfig,
  type SpanNameNormalizingProcessorOptions,
} from './span-name-normalizer';

// Attribute redacting processor
export {
  AttributeRedactingProcessor,
  REDACTOR_PATTERNS,
  REDACTOR_PRESETS,
  builtinPatterns,
  createAttributeRedactor,
  createRedactedSpan,
  normalizeAttributeRedactorConfig,
  type AttributeRedactorFn,
  type AttributeRedactorPreset,
  type AttributeRedactorConfig,
  type AttributeRedactingProcessorOptions,
  type BuiltinPatternName,
  type MaskFn,
  type ValuePatternConfig,
} from './attribute-redacting-processor';

// String redaction utility
export { createStringRedactor, type StringRedactor } from './redact-values';

// Functional API (re-export for convenience)
export type {
  TraceContext,
  SpanOptions,
  WithNewContextOptions,
  WithBaggageOptions,
  InstrumentOptions,
} from './functional';
export {
  instrument,
  withTracing,
  span,
  withNewContext,
  withBaggage,
  ctx,
} from './functional';
// `trace` is the hybrid: callable like autotel's `trace(fn)` AND carries the
// full `@opentelemetry/api` TraceAPI surface (getActiveSpan, getTracer, etc).
export { trace } from './trace-hybrid';

// Operation context (for advanced usage)
export type { OperationContext } from './operation-context';
export {
  getOperationContext,
  runInOperationContext,
} from './operation-context';

// Global track function
export { track, getEventQueue } from './track';

// Correlation ID utilities
export {
  getCorrelationId,
  getOrCreateCorrelationId,
  generateCorrelationId,
  runWithCorrelationId,
  setCorrelationId,
  setCorrelationIdInBaggage,
  CORRELATION_ID_BAGGAGE_KEY,
} from './correlation-id';

// Graceful shutdown
export { flush, shutdown } from './shutdown';

// Request logger
export {
  getRequestLogger,
  runWithRequestContext,
  type RequestLogger,
  type RequestLogSnapshot,
  type RequestLoggerOptions,
  type ForkLifecycle,
  type ForkOptions,
} from './request-logger';

// Structured errors
export {
  createStructuredError,
  structuredErrorToJSON,
  getStructuredErrorAttributes,
  recordStructuredError,
  type StructuredError,
  type StructuredErrorInput,
} from './structured-error';

// parseError
export { parseError, type ParsedError } from './parse-error';

// Attribute flattening
export { toAttributeValue, flattenToAttributes } from './flatten-attributes';

// Drain pipeline
export {
  createDrainPipeline,
  type DrainPipelineOptions,
  type PipelineDrainFn,
} from './drain-pipeline';
export {
  defineDrain,
  defineHttpDrain,
  type DrainOptions,
  type HttpDrainOptions,
  type HttpDrainRequest,
} from './drain-toolkit';
export {
  defineEnricher,
  type EnricherDefinition,
  type EnrichContext,
  type EnricherOptions,
} from './enricher-toolkit';

// Pretty log formatting
export { formatDuration } from './pretty-log-formatter';

// Re-export sampling strategies
export {
  type Sampler,
  type SamplingContext,
  type SamplingPreset,
  AlwaysSampler,
  NeverSampler,
  RandomSampler,
  AdaptiveSampler,
  UserIdSampler,
  createLinkFromHeaders,
  extractLinksFromBatch,
  samplingPresets,
  resolveSamplingPreset,
  AUTOTEL_SAMPLING_TAIL_KEEP,
  AUTOTEL_SAMPLING_TAIL_EVALUATED,
} from './sampling';

// Events API
export { Event, getEvents, resetEvents, type EventsOptions } from './event';

// Metrics API
export {
  Metric,
  getMetrics,
  resetMetrics,
  type MetricsOptions,
} from './metric';

// Meter helpers for custom metrics
export {
  getMeter,
  createCounter,
  createHistogram,
  createUpDownCounter,
  createObservableGauge,
} from './metric-helpers';

// LLM-tuned histogram buckets — pass genAiMetricViews() to your
// MeterProvider so gen_ai.* histograms have useful resolution.
export {
  GEN_AI_DURATION_BUCKETS_SECONDS,
  GEN_AI_TOKEN_USAGE_BUCKETS,
  GEN_AI_COST_USD_BUCKETS,
  genAiMetricViews,
  llmHistogramAdvice,
} from './gen-ai-metrics';

// OTel GenAI span event helpers — record prompt-sent / response-received
// / retry / tool-call / stream-first-token as timestamped events aligned
// with the published GenAI semantic conventions.
export {
  recordPromptSent,
  recordResponseReceived,
  recordRetry,
  recordToolCall,
  recordStreamFirstToken,
  type PromptSentEvent,
  type ResponseReceivedEvent,
  type RetryEvent,
  type ToolCallEvent,
  type StreamFirstTokenEvent,
} from './gen-ai-events';

// Tracer helpers for custom spans
export {
  getTracer,
  getActiveSpan,
  getActiveContext,
  runWithSpan,
  finalizeSpan,
  createDeterministicTraceId,
  flattenMetadata,
  getTraceContext,
  isTracing,
  enrichWithTraceContext,
  resolveTraceUrl,
} from './trace-helpers';

export type { TraceContext as OtelTraceContext } from './trace-helpers';

// Isolated tracer provider support (advanced - for library authors)
export {
  setAutotelTracerProvider,
  getAutotelTracerProvider,
  getAutotelTracer,
} from './tracer-provider';

// Semantic convention helpers
export {
  traceLLM,
  traceDB,
  traceHTTP,
  traceMessaging,
  type LLMConfig,
  type DBConfig,
  type HTTPConfig,
  type MessagingConfig,
} from './semantic-helpers';

// Re-export events types
export type {
  EventSubscriber,
  EventAttributes,
  FunnelStatus,
  OutcomeStatus,
} from './event-subscriber';

// Re-export OpenTelemetry APIs for convenience
// (Users shouldn't need to import @opentelemetry/api directly)
// Note: OTel's trace is exported as 'otelTrace' to avoid naming conflict with autotel's trace()
// Plugin developers can also access it directly: import { otelTrace } from 'autotel'
export {
  context,
  propagation,
  SpanStatusCode,
  trace as otelTrace,
} from '@opentelemetry/api';

// Re-export common semantic-convention keys/builders for library instrumentation
export {
  HTTPAttributes,
  ServiceAttributes,
  URLAttributes,
  httpRequestHeaderAttribute,
  httpResponseHeaderAttribute,
} from './semantic-conventions';

// Re-export common OpenTelemetry types and utilities
// This allows plugins and apps to use OTel without needing separate @opentelemetry/api installation

// Semantic attribute builders and utilities
// Provides autocomplete-first attribute construction with automatic PII redaction
// and deprecation warnings
export {
  attrs,
  setUser,
  setSession,
  setDevice,
  httpServer,
  httpClient,
  dbClient,
  mergeServiceResource,
  identify,
  request,
  setError,
  setException,
  mergeAttrs,
  safeSetAttributes,
  validateAttribute,
  autoRedactPII,
  type AttributeGuardrails,
  type AttributePolicy,
  type UserAttrs,
  type SessionAttrs,
  type DeviceAttrs,
  type HTTPServerAttrs,
  type HTTPClientAttrs,
  type DBAttrs,
  type ServiceAttrs,
  type NetworkAttrs,
  type ErrorAttrs,
  type ExceptionAttrs,
  type FeatureFlagAttrs,
  type MessagingAttrs,
  type CloudAttrs,
  type ServerAddressAttrs,
  type URLAttrs,
  type PeerAttrs,
  type ProcessAttrs,
  type ContainerAttrs,
  type K8sAttrs,
  type FaaSAttrs,
  type ThreadAttrs,
  type GenAIAttrs,
  type RPCAttrs,
  type GraphQLAttrs,
  type ClientAttrs,
  type DeploymentAttrs,
  type OTelAttrs,
  type CodeAttrs,
  type TLSAttrs,
} from './attributes';

// Re-export common OpenTelemetry types and utilities so plugins, apps, and
// existing OTel code can `import { ... } from 'autotel'` without also taking
// a separate `@opentelemetry/api` dependency.
export type {
  Span,
  SpanContext,
  SpanAttributes,
  Tracer,
  TracerProvider,
  Context,
  Attributes,
  AttributeValue,
  Link,
  Link as SpanLink,
  TimeInput,
  HrTime,
  Baggage,
  BaggageEntry,
  Exception,
  TraceFlags,
  TraceState,
  TextMapSetter,
  TextMapGetter,
} from '@opentelemetry/api';
export { SpanKind, ROOT_CONTEXT } from '@opentelemetry/api';
// Note: trace, context, propagation, SpanStatusCode already exported above
// (`trace` is the hybrid; `otelTrace` is the pure TraceAPI singleton).

// Export typed baggage helper
export { defineBaggageSchema } from './trace-context';

// Messaging helpers for event-driven architectures
export {
  traceProducer,
  traceConsumer,
  type ProducerConfig,
  type ConsumerConfig,
  type ProducerContext,
  type ConsumerContext,
  type MessagingSystem,
  type MessagingOperation,
  type LagMetricsConfig,
} from './messaging';

// Safe baggage propagation with guardrails
export {
  createSafeBaggageSchema,
  BusinessBaggage,
  type SafeBaggageOptions,
  type BaggageFieldDefinition,
  type BaggageFieldType,
  type BaggageError,
  type SafeBaggageSchema,
  type BusinessBaggageValues,
} from './business-baggage';

// Workflow and saga tracing
export {
  traceWorkflow,
  traceStep,
  getCurrentWorkflowContext,
  isInWorkflow,
  type WorkflowConfig,
  type StepConfig,
  type WorkflowContext,
  type StepContext,
  type WorkflowStatus,
  type StepStatus,
} from './workflow';