@parsrun/service 0.1.0

package/dist/tracing/index.js

@@ -0,0 +1,820 @@
+// src/tracing/context.ts
+function generateTraceId() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function generateSpanId() {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function createTraceContext(options) {
+  const ctx = {
+    traceId: options?.traceId ?? generateTraceId(),
+    spanId: options?.spanId ?? generateSpanId(),
+    traceFlags: options?.traceFlags ?? 1
+    // Default: sampled
+  };
+  if (options?.traceState) {
+    ctx.traceState = options.traceState;
+  }
+  return ctx;
+}
+function createChildContext(parent) {
+  const ctx = {
+    traceId: parent.traceId,
+    spanId: generateSpanId(),
+    traceFlags: parent.traceFlags
+  };
+  if (parent.traceState) {
+    ctx.traceState = parent.traceState;
+  }
+  return ctx;
+}
+function formatTraceparent(ctx) {
+  const version = "00";
+  const flags = ctx.traceFlags.toString(16).padStart(2, "0");
+  return `${version}-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}
+function parseTraceparent(header) {
+  const parts = header.trim().split("-");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const [version, traceId, spanId, flags] = parts;
+  if (version !== "00") {
+    return null;
+  }
+  if (!traceId || traceId.length !== 32 || !/^[0-9a-f]+$/i.test(traceId)) {
+    return null;
+  }
+  if (!spanId || spanId.length !== 16 || !/^[0-9a-f]+$/i.test(spanId)) {
+    return null;
+  }
+  if (!flags || flags.length !== 2 || !/^[0-9a-f]+$/i.test(flags)) {
+    return null;
+  }
+  return {
+    traceId: traceId.toLowerCase(),
+    spanId: spanId.toLowerCase(),
+    traceFlags: parseInt(flags, 16)
+  };
+}
+function formatTracestate(state) {
+  return Object.entries(state).map(([key, value]) => `${key}=${value}`).join(",");
+}
+function parseTracestate(header) {
+  const state = {};
+  for (const pair of header.split(",")) {
+    const [key, value] = pair.trim().split("=");
+    if (key && value) {
+      state[key] = value;
+    }
+  }
+  return state;
+}
+var TraceContextManager = class {
+  stack = [];
+  /**
+   * Get current trace context
+   */
+  current() {
+    return this.stack[this.stack.length - 1];
+  }
+  /**
+   * Run a function with a trace context
+   */
+  async run(ctx, fn) {
+    this.stack.push(ctx);
+    try {
+      return await fn();
+    } finally {
+      this.stack.pop();
+    }
+  }
+  /**
+   * Run a function with a new child context
+   */
+  async runChild(fn) {
+    const parent = this.current();
+    const child = parent ? createChildContext(parent) : createTraceContext();
+    return this.run(child, fn);
+  }
+  /**
+   * Create context from incoming request headers
+   */
+  fromHeaders(headers) {
+    const traceparent = headers instanceof Headers ? headers.get("traceparent") : headers["traceparent"];
+    if (!traceparent) {
+      return void 0;
+    }
+    const ctx = parseTraceparent(traceparent);
+    if (!ctx) {
+      return void 0;
+    }
+    const tracestate = headers instanceof Headers ? headers.get("tracestate") : headers["tracestate"];
+    if (tracestate) {
+      ctx.traceState = tracestate;
+    }
+    return ctx;
+  }
+  /**
+   * Add trace context to outgoing request headers
+   */
+  toHeaders(ctx) {
+    const headers = {
+      traceparent: formatTraceparent(ctx)
+    };
+    if (ctx.traceState) {
+      headers["tracestate"] = ctx.traceState;
+    }
+    return headers;
+  }
+  /**
+   * Check if current context is sampled
+   */
+  isSampled() {
+    const ctx = this.current();
+    return ctx ? (ctx.traceFlags & 1) === 1 : false;
+  }
+  /**
+   * Clear all contexts (for testing)
+   */
+  clear() {
+    this.stack.length = 0;
+  }
+};
+function shouldSample(sampler, traceId) {
+  if (sampler === "always") {
+    return true;
+  }
+  if (sampler === "never") {
+    return false;
+  }
+  if (traceId) {
+    const hash = parseInt(traceId.slice(-8), 16);
+    const threshold = Math.floor(sampler.ratio * 4294967295);
+    return hash < threshold;
+  }
+  return Math.random() < sampler.ratio;
+}
+
+// src/tracing/spans.ts
+function createSpan(options) {
+  let traceContext;
+  if (options.parent) {
+    traceContext = {
+      traceId: options.parent.traceId,
+      spanId: generateSpanId(),
+      traceFlags: options.parent.traceFlags
+    };
+    if (options.parent.traceState) {
+      traceContext.traceState = options.parent.traceState;
+    }
+  } else {
+    traceContext = createTraceContext();
+  }
+  const span = {
+    name: options.name,
+    kind: options.kind ?? "internal",
+    traceContext,
+    startTime: options.startTime ?? Date.now(),
+    status: "unset",
+    attributes: options.attributes ?? {},
+    events: []
+  };
+  if (options.parent?.spanId) {
+    span.parentSpanId = options.parent.spanId;
+  }
+  return span;
+}
+var SpanManager = class {
+  spans = /* @__PURE__ */ new Map();
+  /**
+   * Start a new span
+   */
+  startSpan(options) {
+    const span = createSpan(options);
+    this.spans.set(span.traceContext.spanId, span);
+    return span;
+  }
+  /**
+   * End a span
+   */
+  endSpan(span, status) {
+    span.endTime = Date.now();
+    if (status) {
+      span.status = status;
+    } else if (span.status === "unset") {
+      span.status = "ok";
+    }
+    return span;
+  }
+  /**
+   * Set span attribute
+   */
+  setAttribute(span, key, value) {
+    span.attributes[key] = value;
+  }
+  /**
+   * Set multiple span attributes
+   */
+  setAttributes(span, attributes) {
+    Object.assign(span.attributes, attributes);
+  }
+  /**
+   * Add span event
+   */
+  addEvent(span, name, attributes) {
+    const event = {
+      name,
+      time: Date.now()
+    };
+    if (attributes) {
+      event.attributes = attributes;
+    }
+    span.events.push(event);
+  }
+  /**
+   * Set span status
+   */
+  setStatus(span, status) {
+    span.status = status;
+  }
+  /**
+   * Record exception on span
+   */
+  recordException(span, error) {
+    span.status = "error";
+    this.addEvent(span, "exception", {
+      "exception.type": error.name,
+      "exception.message": error.message,
+      "exception.stacktrace": error.stack ?? ""
+    });
+  }
+  /**
+   * Get span by ID
+   */
+  getSpan(spanId) {
+    return this.spans.get(spanId);
+  }
+  /**
+   * Get all completed spans and clear
+   */
+  flush() {
+    const completed = Array.from(this.spans.values()).filter((s) => s.endTime);
+    for (const span of completed) {
+      this.spans.delete(span.traceContext.spanId);
+    }
+    return completed;
+  }
+  /**
+   * Clear all spans
+   */
+  clear() {
+    this.spans.clear();
+  }
+};
+function getSpanDuration(span) {
+  if (!span.endTime) return void 0;
+  return span.endTime - span.startTime;
+}
+function isSpanCompleted(span) {
+  return span.endTime !== void 0;
+}
+function spanToLogObject(span) {
+  return {
+    traceId: span.traceContext.traceId,
+    spanId: span.traceContext.spanId,
+    parentSpanId: span.parentSpanId,
+    name: span.name,
+    kind: span.kind,
+    status: span.status,
+    startTime: new Date(span.startTime).toISOString(),
+    endTime: span.endTime ? new Date(span.endTime).toISOString() : void 0,
+    durationMs: getSpanDuration(span),
+    attributes: span.attributes,
+    events: span.events.map((e) => ({
+      name: e.name,
+      time: new Date(e.time).toISOString(),
+      attributes: e.attributes
+    }))
+  };
+}
+var SpanAttributes = {
+  // HTTP
+  HTTP_METHOD: "http.method",
+  HTTP_URL: "http.url",
+  HTTP_STATUS_CODE: "http.status_code",
+  HTTP_REQUEST_CONTENT_LENGTH: "http.request_content_length",
+  HTTP_RESPONSE_CONTENT_LENGTH: "http.response_content_length",
+  // RPC
+  RPC_SYSTEM: "rpc.system",
+  RPC_SERVICE: "rpc.service",
+  RPC_METHOD: "rpc.method",
+  // Database
+  DB_SYSTEM: "db.system",
+  DB_NAME: "db.name",
+  DB_OPERATION: "db.operation",
+  DB_STATEMENT: "db.statement",
+  // Messaging
+  MESSAGING_SYSTEM: "messaging.system",
+  MESSAGING_DESTINATION: "messaging.destination",
+  MESSAGING_MESSAGE_ID: "messaging.message_id",
+  // Service
+  SERVICE_NAME: "service.name",
+  SERVICE_VERSION: "service.version",
+  // Error
+  EXCEPTION_TYPE: "exception.type",
+  EXCEPTION_MESSAGE: "exception.message",
+  EXCEPTION_STACKTRACE: "exception.stacktrace",
+  // Custom Pars attributes
+  PARS_TENANT_ID: "pars.tenant_id",
+  PARS_USER_ID: "pars.user_id",
+  PARS_REQUEST_ID: "pars.request_id"
+};
+
+// src/tracing/exporters.ts
+import { createLogger } from "@parsrun/core";
+var ConsoleExporter = class {
+  name = "console";
+  logger;
+  pretty;
+  includeAttributes;
+  includeEvents;
+  constructor(options = {}) {
+    this.logger = options.logger ?? createLogger({ name: "trace-exporter" });
+    this.pretty = options.pretty ?? true;
+    this.includeAttributes = options.includeAttributes ?? true;
+    this.includeEvents = options.includeEvents ?? true;
+  }
+  async export(spans) {
+    for (const span of spans) {
+      const duration = getSpanDuration(span);
+      const status = span.status === "error" ? "ERROR" : span.status === "ok" ? "OK" : "UNSET";
+      if (this.pretty) {
+        const indent = span.parentSpanId ? "  \u2514\u2500" : "\u2500\u2500";
+        const statusIcon = span.status === "error" ? "\u2717" : span.status === "ok" ? "\u2713" : "\u25CB";
+        const durationStr = duration !== void 0 ? `${duration}ms` : "?ms";
+        console.log(
+          `${indent} ${statusIcon} [${span.kind}] ${span.name} (${durationStr}) trace=${span.traceContext.traceId.slice(0, 8)}`
+        );
+        if (this.includeAttributes && Object.keys(span.attributes).length > 0) {
+          console.log(`     attributes:`, span.attributes);
+        }
+        if (this.includeEvents && span.events.length > 0) {
+          for (const event of span.events) {
+            console.log(`     event: ${event.name}`, event.attributes ?? "");
+          }
+        }
+      } else {
+        const logObj = spanToLogObject(span);
+        this.logger.info(`Span: ${span.name}`, {
+          ...logObj,
+          status,
+          durationMs: duration
+        });
+      }
+    }
+  }
+  async shutdown() {
+  }
+};
+function createConsoleExporter(options) {
+  return new ConsoleExporter(options);
+}
+var OtlpExporter = class {
+  name = "otlp";
+  endpoint;
+  serviceName;
+  serviceVersion;
+  headers;
+  timeout;
+  batchSize;
+  flushInterval;
+  logger;
+  buffer = [];
+  flushTimer = null;
+  constructor(options) {
+    this.endpoint = options.endpoint.replace(/\/$/, "");
+    this.serviceName = options.serviceName;
+    this.serviceVersion = options.serviceVersion ?? "1.0.0";
+    this.headers = options.headers ?? {};
+    this.timeout = options.timeout ?? 1e4;
+    this.batchSize = options.batchSize ?? 100;
+    this.flushInterval = options.flushInterval ?? 5e3;
+    this.logger = options.logger ?? createLogger({ name: "otlp-exporter" });
+    this.flushTimer = setInterval(() => this.flush(), this.flushInterval);
+  }
+  async export(spans) {
+    this.buffer.push(...spans);
+    if (this.buffer.length >= this.batchSize) {
+      await this.flush();
+    }
+  }
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const spansToExport = this.buffer.splice(0, this.batchSize);
+    try {
+      const payload = this.buildOtlpPayload(spansToExport);
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(`${this.endpoint}/v1/traces`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...this.headers
+          },
+          body: JSON.stringify(payload),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`OTLP export failed: ${response.status} ${response.statusText}`);
+        }
+        this.logger.debug(`Exported ${spansToExport.length} spans to OTLP`);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (error) {
+      this.logger.error(`Failed to export spans to OTLP`, error);
+      this.buffer.unshift(...spansToExport);
+    }
+  }
+  buildOtlpPayload(spans) {
+    return {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [
+              { key: "service.name", value: { stringValue: this.serviceName } },
+              { key: "service.version", value: { stringValue: this.serviceVersion } }
+            ]
+          },
+          scopeSpans: [
+            {
+              scope: {
+                name: "@parsrun/service",
+                version: "0.1.0"
+              },
+              spans: spans.map((span) => this.convertSpan(span))
+            }
+          ]
+        }
+      ]
+    };
+  }
+  convertSpan(span) {
+    const otlpSpan = {
+      traceId: span.traceContext.traceId,
+      spanId: span.traceContext.spanId,
+      name: span.name,
+      kind: this.convertSpanKind(span.kind),
+      startTimeUnixNano: String(span.startTime * 1e6),
+      attributes: Object.entries(span.attributes).map(([key, value]) => ({
+        key,
+        value: this.convertAttributeValue(value)
+      })),
+      events: span.events.map((event) => ({
+        name: event.name,
+        timeUnixNano: String(event.time * 1e6),
+        attributes: event.attributes ? Object.entries(event.attributes).map(([key, value]) => ({
+          key,
+          value: this.convertAttributeValue(value)
+        })) : []
+      })),
+      status: {
+        code: span.status === "error" ? 2 : span.status === "ok" ? 1 : 0
+      }
+    };
+    if (span.parentSpanId) {
+      otlpSpan.parentSpanId = span.parentSpanId;
+    }
+    if (span.endTime) {
+      otlpSpan.endTimeUnixNano = String(span.endTime * 1e6);
+    }
+    return otlpSpan;
+  }
+  convertSpanKind(kind) {
+    switch (kind) {
+      case "internal":
+        return 1;
+      case "server":
+        return 2;
+      case "client":
+        return 3;
+      case "producer":
+        return 4;
+      case "consumer":
+        return 5;
+      default:
+        return 0;
+    }
+  }
+  convertAttributeValue(value) {
+    if (typeof value === "string") {
+      return { stringValue: value };
+    }
+    if (typeof value === "number") {
+      if (Number.isInteger(value)) {
+        return { intValue: String(value) };
+      }
+      return { doubleValue: value };
+    }
+    if (typeof value === "boolean") {
+      return { boolValue: value };
+    }
+    if (Array.isArray(value)) {
+      return {
+        arrayValue: {
+          values: value.map((v) => this.convertAttributeValue(v))
+        }
+      };
+    }
+    return { stringValue: String(value) };
+  }
+  async shutdown() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+};
+function createOtlpExporter(options) {
+  return new OtlpExporter(options);
+}
+
+// src/tracing/tracer.ts
+import { createLogger as createLogger2 } from "@parsrun/core";
+var Tracer = class {
+  serviceName;
+  serviceVersion;
+  sampler;
+  exporter;
+  logger;
+  contextManager;
+  spanManager;
+  enabled;
+  flushTimer = null;
+  constructor(options) {
+    this.serviceName = options.serviceName;
+    this.serviceVersion = options.serviceVersion ?? "1.0.0";
+    this.enabled = options.config?.enabled ?? true;
+    this.sampler = options.config?.sampler ?? { ratio: 0.1 };
+    this.exporter = options.exporter ?? new ConsoleExporter();
+    this.logger = options.logger ?? createLogger2({ name: `tracer:${options.serviceName}` });
+    this.contextManager = new TraceContextManager();
+    this.spanManager = new SpanManager();
+    if (this.enabled) {
+      this.flushTimer = setInterval(() => this.flush(), 5e3);
+    }
+  }
+  /**
+   * Start a new span
+   */
+  startSpan(name, options) {
+    if (!this.enabled) return null;
+    const parent = options?.parent ?? this.contextManager.current();
+    if (!parent && !shouldSample(this.sampler)) {
+      return null;
+    }
+    const spanOptions = {
+      name,
+      kind: options?.kind ?? "internal",
+      attributes: {
+        [SpanAttributes.SERVICE_NAME]: this.serviceName,
+        [SpanAttributes.SERVICE_VERSION]: this.serviceVersion,
+        ...options?.attributes
+      }
+    };
+    if (parent) {
+      spanOptions.parent = parent;
+    }
+    const span = this.spanManager.startSpan(spanOptions);
+    return span;
+  }
+  /**
+   * End a span
+   */
+  endSpan(span, error) {
+    if (!span) return;
+    if (error) {
+      this.spanManager.recordException(span, error);
+    }
+    this.spanManager.endSpan(span, error ? "error" : "ok");
+  }
+  /**
+   * Run a function with automatic span creation
+   */
+  async trace(name, fn, options) {
+    const span = this.startSpan(name, options);
+    if (!span) {
+      return fn(null);
+    }
+    try {
+      const result = await this.contextManager.run(span.traceContext, () => fn(span));
+      this.endSpan(span);
+      return result;
+    } catch (error) {
+      this.endSpan(span, error);
+      throw error;
+    }
+  }
+  /**
+   * Add attribute to current span
+   */
+  setAttribute(key, value) {
+    const ctx = this.contextManager.current();
+    if (!ctx) return;
+    const span = this.spanManager.getSpan(ctx.spanId);
+    if (span) {
+      this.spanManager.setAttribute(span, key, value);
+    }
+  }
+  /**
+   * Add event to current span
+   */
+  addEvent(name, attributes) {
+    const ctx = this.contextManager.current();
+    if (!ctx) return;
+    const span = this.spanManager.getSpan(ctx.spanId);
+    if (span) {
+      this.spanManager.addEvent(span, name, attributes);
+    }
+  }
+  /**
+   * Get current trace context
+   */
+  currentContext() {
+    return this.contextManager.current();
+  }
+  /**
+   * Get context manager for advanced use
+   */
+  getContextManager() {
+    return this.contextManager;
+  }
+  /**
+   * Extract trace context from incoming request
+   */
+  extract(headers) {
+    return this.contextManager.fromHeaders(headers);
+  }
+  /**
+   * Inject trace context into outgoing request headers
+   */
+  inject(ctx) {
+    const context = ctx ?? this.contextManager.current();
+    if (!context) return {};
+    return this.contextManager.toHeaders(context);
+  }
+  /**
+   * Flush completed spans to exporter
+   */
+  async flush() {
+    const spans = this.spanManager.flush();
+    if (spans.length > 0) {
+      try {
+        await this.exporter.export(spans);
+      } catch (error) {
+        this.logger.error("Failed to export spans", error);
+      }
+    }
+  }
+  /**
+   * Shutdown tracer
+   */
+  async shutdown() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+    await this.exporter.shutdown();
+    this.spanManager.clear();
+    this.contextManager.clear();
+  }
+};
+function createTracer(options) {
+  return new Tracer(options);
+}
+var globalTracer = null;
+function getGlobalTracer() {
+  return globalTracer;
+}
+function setGlobalTracer(tracer) {
+  globalTracer = tracer;
+}
+function resetGlobalTracer() {
+  globalTracer = null;
+}
+function createTracingMiddleware(tracer) {
+  return async (request, next) => {
+    const parentCtx = tracer.extract(request.headers);
+    const url = new URL(request.url);
+    const spanOpts = {
+      kind: "server",
+      attributes: {
+        [SpanAttributes.HTTP_METHOD]: request.method,
+        [SpanAttributes.HTTP_URL]: request.url
+      }
+    };
+    if (parentCtx) {
+      spanOpts.parent = parentCtx;
+    }
+    const span = tracer.startSpan(`${request.method} ${url.pathname}`, spanOpts);
+    if (!span) {
+      return next();
+    }
+    try {
+      const response = await tracer.getContextManager().run(span.traceContext, next);
+      tracer.endSpan(span);
+      span.attributes[SpanAttributes.HTTP_STATUS_CODE] = response.status;
+      return response;
+    } catch (error) {
+      tracer.endSpan(span, error);
+      throw error;
+    }
+  };
+}
+function createRpcTracing(tracer) {
+  return {
+    /**
+     * Trace an outgoing RPC call
+     */
+    async traceCall(service, method, fn) {
+      return tracer.trace(
+        `rpc.${service}.${method}`,
+        fn,
+        {
+          kind: "client",
+          attributes: {
+            [SpanAttributes.RPC_SYSTEM]: "pars",
+            [SpanAttributes.RPC_SERVICE]: service,
+            [SpanAttributes.RPC_METHOD]: method
+          }
+        }
+      );
+    },
+    /**
+     * Trace an incoming RPC request
+     */
+    async traceHandler(service, method, fn, parentCtx) {
+      const handlerOpts = {
+        kind: "server",
+        attributes: {
+          [SpanAttributes.RPC_SYSTEM]: "pars",
+          [SpanAttributes.RPC_SERVICE]: service,
+          [SpanAttributes.RPC_METHOD]: method
+        }
+      };
+      if (parentCtx) {
+        handlerOpts.parent = parentCtx;
+      }
+      const span = tracer.startSpan(`rpc.${service}.${method}`, handlerOpts);
+      if (!span) {
+        return fn();
+      }
+      try {
+        const result = await tracer.getContextManager().run(span.traceContext, fn);
+        tracer.endSpan(span);
+        return result;
+      } catch (error) {
+        tracer.endSpan(span, error);
+        throw error;
+      }
+    }
+  };
+}
+export {
+  ConsoleExporter,
+  OtlpExporter,
+  SpanAttributes,
+  SpanManager,
+  TraceContextManager,
+  Tracer,
+  createChildContext,
+  createConsoleExporter,
+  createOtlpExporter,
+  createRpcTracing,
+  createSpan,
+  createTraceContext,
+  createTracer,
+  createTracingMiddleware,
+  formatTraceparent,
+  formatTracestate,
+  generateSpanId,
+  generateTraceId,
+  getGlobalTracer,
+  getSpanDuration,
+  isSpanCompleted,
+  parseTraceparent,
+  parseTracestate,
+  resetGlobalTracer,
+  setGlobalTracer,
+  shouldSample,
+  spanToLogObject
+};
+//# sourceMappingURL=index.js.map