@statly/observe 0.1.2 → 1.1.0

package/dist/index.d.ts

@@ -2,6 +2,55 @@ export { expressErrorHandler, requestHandler } from './integrations/express.js';
 export { captureNextJsError, withStatly, withStatlyGetServerSideProps, withStatlyGetStaticProps, withStatlyPagesApi, withStatlyServerAction } from './integrations/nextjs.js';
 export { createRequestCapture, statlyFastifyPlugin, statlyPlugin } from './integrations/fastify.js';
 
+/**
+ * Span module for Statly Observe SDK
+ * Handles distributed tracing spans
+ */
+declare enum SpanStatus {
+    OK = "ok",
+    ERROR = "error"
+}
+interface SpanContext {
+    traceId: string;
+    spanId: string;
+    parentId?: string | null;
+}
+interface SpanData {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentId?: string | null;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: SpanStatus;
+    tags: Record<string, string>;
+    metadata: Record<string, unknown>;
+}
+declare class Span {
+    readonly name: string;
+    readonly context: SpanContext;
+    readonly startTime: number;
+    private _endTime?;
+    private _durationMs?;
+    private _status;
+    private _tags;
+    private _metadata;
+    private _finished;
+    constructor(name: string, context: SpanContext, tags?: Record<string, string>);
+    /**
+     * Finish the span and calculate duration
+     */
+    finish(endTime?: number): void;
+    setTag(key: string, value: string): this;
+    setMetadata(key: string, value: unknown): this;
+    setStatus(status: SpanStatus): this;
+    get status(): SpanStatus;
+    get tags(): Record<string, string>;
+    get durationMs(): number | undefined;
+    toDict(): SpanData;
+}
+
 /**
  * Statly Observe SDK Types
  */
@@ -79,9 +128,10 @@ interface DeviceInfo {
 interface StatlyEvent {
     message: string;
     timestamp?: number;
-    level?: 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+    level?: 'debug' | 'info' | 'warning' | 'error' | 'fatal' | 'span';
     stack?: string;
     exception?: Exception;
+    span?: SpanData;
     environment?: string;
     release?: string;
     url?: string;
@@ -130,6 +180,18 @@ declare class StatlyClient {
      * Capture a message
      */
     captureMessage(message: string, level?: EventLevel): string;
+    /**
+     * Capture a completed span
+     */
+    captureSpan(span: Span): string;
+    /**
+     * Start a new tracing span
+     */
+    startSpan(name: string, tags?: Record<string, string>): Span;
+    /**
+     * Execute a function within a trace span
+     */
+    trace<T>(name: string, operation: (span: Span) => Promise<T> | T, tags?: Record<string, string>): Promise<T>;
     /**
      * Internal method to capture an error
      */
@@ -181,47 +243,6 @@ declare class StatlyClient {
     flush(): Promise<void>;
 }
 
-/**
- * Statly Observe SDK
- *
- * Error tracking and monitoring for JavaScript applications.
- *
- * @example
- * ```typescript
- * import { Statly } from '@statly/observe-sdk';
- *
- * Statly.init({
- *   dsn: 'https://sk_live_xxx@statly.live/your-org',
- *   release: '1.0.0',
- *   environment: 'production',
- * });
- *
- * // Errors are captured automatically
- *
- * // Manual capture
- * try {
- *   riskyOperation();
- * } catch (error) {
- *   Statly.captureException(error);
- * }
- *
- * // Capture a message
- * Statly.captureMessage('Something happened', 'warning');
- *
- * // Set user context
- * Statly.setUser({
- *   id: 'user-123',
- *   email: 'user@example.com',
- * });
- *
- * // Add breadcrumb
- * Statly.addBreadcrumb({
- *   category: 'auth',
- *   message: 'User logged in',
- * });
- * ```
- */
-
 /**
  * Initialize the Statly SDK
  *
@@ -274,6 +295,18 @@ declare function close(): Promise<void>;
  * Get the current client instance
  */
 declare function getClient(): StatlyClient | null;
+/**
+ * Execute a function within a trace span
+ */
+declare function trace<T>(name: string, operation: (span: Span) => Promise<T> | T, tags?: Record<string, string>): Promise<T>;
+/**
+ * Start a new tracing span
+ */
+declare function startSpan(name: string, tags?: Record<string, string>): Span | null;
+/**
+ * Capture a completed span
+ */
+declare function captureSpan(span: Span): string;
 declare const Statly: {
     readonly init: typeof init;
     readonly captureException: typeof captureException;
@@ -285,6 +318,9 @@ declare const Statly: {
     readonly flush: typeof flush;
     readonly close: typeof close;
     readonly getClient: typeof getClient;
+    readonly trace: typeof trace;
+    readonly startSpan: typeof startSpan;
+    readonly captureSpan: typeof captureSpan;
 };
 
-export { type Breadcrumb, type BrowserInfo, type DeviceInfo, type EventLevel, type Exception, type OSInfo, type StackFrame, Statly, StatlyClient, type StatlyEvent, type StatlyOptions, type User, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, setTag, setTags, setUser };
+export { type Breadcrumb, type BrowserInfo, type DeviceInfo, type EventLevel, type Exception, type OSInfo, type StackFrame, Statly, StatlyClient, type StatlyEvent, type StatlyOptions, type User, addBreadcrumb, captureException, captureMessage, captureSpan, close, flush, getClient, init, setTag, setTags, setUser, startSpan, trace };

package/dist/index.js

@@ -3,6 +3,9 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -17,6 +20,155 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/span.ts
+var Span, TraceContext;
+var init_span = __esm({
+  "src/span.ts"() {
+    "use strict";
+    Span = class {
+      constructor(name, context, tags) {
+        this._status = "ok" /* OK */;
+        this._tags = {};
+        this._metadata = {};
+        this._finished = false;
+        this.name = name;
+        this.context = context;
+        this.startTime = Date.now();
+        if (tags) this._tags = { ...tags };
+      }
+      /**
+       * Finish the span and calculate duration
+       */
+      finish(endTime) {
+        if (this._finished) return;
+        this._endTime = endTime || Date.now();
+        this._durationMs = this._endTime - this.startTime;
+        this._finished = true;
+      }
+      setTag(key, value) {
+        this._tags[key] = value;
+        return this;
+      }
+      setMetadata(key, value) {
+        this._metadata[key] = value;
+        return this;
+      }
+      setStatus(status) {
+        this._status = status;
+        return this;
+      }
+      get status() {
+        return this._status;
+      }
+      get tags() {
+        return { ...this._tags };
+      }
+      get durationMs() {
+        return this._durationMs;
+      }
+      toDict() {
+        return {
+          name: this.name,
+          traceId: this.context.traceId,
+          spanId: this.context.spanId,
+          parentId: this.context.parentId,
+          startTime: this.startTime,
+          endTime: this._endTime,
+          durationMs: this._durationMs,
+          status: this._status,
+          tags: this._tags,
+          metadata: this._metadata
+        };
+      }
+    };
+    TraceContext = class {
+      static getActiveSpan() {
+        return this.currentSpan;
+      }
+      static setActiveSpan(span) {
+        this.currentSpan = span;
+      }
+    };
+    TraceContext.currentSpan = null;
+  }
+});
+
+// src/telemetry.ts
+var telemetry_exports = {};
+__export(telemetry_exports, {
+  TelemetryProvider: () => TelemetryProvider,
+  trace: () => trace
+});
+async function trace(name, operation, tags) {
+  const provider = TelemetryProvider.getInstance();
+  const span = provider.startSpan(name, tags);
+  try {
+    const result = await operation(span);
+    return result;
+  } catch (error) {
+    span.setStatus("error" /* ERROR */);
+    span.setTag("error", "true");
+    if (error instanceof Error) {
+      span.setTag("exception.type", error.name);
+      span.setTag("exception.message", error.message);
+    }
+    throw error;
+  } finally {
+    provider.finishSpan(span);
+  }
+}
+var TelemetryProvider;
+var init_telemetry = __esm({
+  "src/telemetry.ts"() {
+    "use strict";
+    init_span();
+    TelemetryProvider = class _TelemetryProvider {
+      constructor() {
+        this.client = null;
+      }
+      static getInstance() {
+        if (!_TelemetryProvider.instance) {
+          _TelemetryProvider.instance = new _TelemetryProvider();
+        }
+        return _TelemetryProvider.instance;
+      }
+      setClient(client2) {
+        this.client = client2;
+      }
+      /**
+       * Start a new span
+       */
+      startSpan(name, tags) {
+        const parent = TraceContext.getActiveSpan();
+        const traceId = parent ? parent.context.traceId : this.generateId();
+        const parentId = parent ? parent.context.spanId : null;
+        const span = new Span(name, {
+          traceId,
+          spanId: this.generateId(),
+          parentId
+        }, tags);
+        TraceContext.setActiveSpan(span);
+        return span;
+      }
+      /**
+       * Finish and report a span
+       */
+      finishSpan(span) {
+        span.finish();
+        if (TraceContext.getActiveSpan() === span) {
+          TraceContext.setActiveSpan(null);
+        }
+        if (this.client) {
+          this.client.captureSpan(span);
+        }
+      }
+      generateId() {
+        return Math.random().toString(16).substring(2, 18);
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -26,6 +178,7 @@ __export(index_exports, {
   captureException: () => captureException,
   captureMessage: () => captureMessage,
   captureNextJsError: () => captureNextJsError,
+  captureSpan: () => captureSpan,
   close: () => close,
   createRequestCapture: () => createRequestCapture,
   expressErrorHandler: () => expressErrorHandler,
@@ -36,8 +189,10 @@ __export(index_exports, {
   setTag: () => setTag,
   setTags: () => setTags,
   setUser: () => setUser,
+  startSpan: () => startSpan,
   statlyFastifyPlugin: () => statlyFastifyPlugin,
   statlyPlugin: () => statlyPlugin,
+  trace: () => trace2,
   withStatly: () => withStatly,
   withStatlyGetServerSideProps: () => withStatlyGetServerSideProps,
   withStatlyGetStaticProps: () => withStatlyGetStaticProps,
@@ -390,6 +545,7 @@ var ConsoleIntegration = class {
 };
 
 // src/client.ts
+init_telemetry();
 var SDK_NAME = "@statly/observe-sdk";
 var SDK_VERSION = "0.1.0";
 var StatlyClient = class {
@@ -404,6 +560,7 @@ var StatlyClient = class {
     this.breadcrumbs = new BreadcrumbManager(this.options.maxBreadcrumbs);
     this.globalHandlers = new GlobalHandlers();
     this.consoleIntegration = new ConsoleIntegration();
+    TelemetryProvider.getInstance().setClient(this);
   }
   mergeOptions(options) {
     return {
@@ -489,6 +646,30 @@ var StatlyClient = class {
     });
     return this.sendEvent(event);
   }
+  /**
+   * Capture a completed span
+   */
+  captureSpan(span) {
+    const event = this.buildEvent({
+      message: `Span: ${span.name}`,
+      level: "span",
+      span: span.toDict()
+    });
+    return this.sendEvent(event);
+  }
+  /**
+   * Start a new tracing span
+   */
+  startSpan(name, tags) {
+    return TelemetryProvider.getInstance().startSpan(name, tags);
+  }
+  /**
+   * Execute a function within a trace span
+   */
+  async trace(name, operation, tags) {
+    const { trace: traceFn } = await Promise.resolve().then(() => (init_telemetry(), telemetry_exports));
+    return traceFn(name, operation, tags);
+  }
   /**
    * Internal method to capture an error
    */
@@ -798,66 +979,81 @@ function sanitizeBody(body) {
 // src/integrations/nextjs.ts
 function withStatlyPagesApi(handler) {
   return async (req, res) => {
-    Statly.addBreadcrumb({
-      category: "http",
-      message: `${req.method} ${req.url}`,
-      level: "info",
-      data: {
-        method: req.method,
-        url: req.url
-      }
-    });
-    try {
-      return await handler(req, res);
-    } catch (error) {
-      const context = {
-        request: {
+    return Statly.trace(`${req.method} ${req.url}`, async (span) => {
+      span.setTag("component", "nextjs-pages-api");
+      span.setTag("http.method", req.method || "GET");
+      span.setTag("http.url", req.url || "unknown");
+      Statly.addBreadcrumb({
+        category: "http",
+        message: `${req.method} ${req.url}`,
+        level: "info",
+        data: {
           method: req.method,
-          url: req.url,
-          headers: sanitizeHeaders2(req.headers),
-          query: req.query
+          url: req.url
         }
-      };
-      Statly.captureException(error, context);
-      throw error;
-    }
+      });
+      try {
+        const result = await handler(req, res);
+        return result;
+      } catch (error) {
+        const context = {
+          request: {
+            method: req.method,
+            url: req.url,
+            headers: sanitizeHeaders2(req.headers),
+            query: req.query
+          }
+        };
+        Statly.captureException(error, context);
+        throw error;
+      }
+    });
   };
 }
 function withStatly(handler) {
   const wrappedHandler = async (request, context) => {
-    Statly.addBreadcrumb({
-      category: "http",
-      message: `${request.method} ${request.nextUrl?.pathname || request.url}`,
-      level: "info",
-      data: {
-        method: request.method,
-        url: request.nextUrl?.pathname || request.url
-      }
-    });
-    try {
-      return await handler(request, context);
-    } catch (error) {
-      const headers = {};
-      request.headers.forEach((value, key) => {
-        headers[key] = value;
-      });
-      const errorContext = {
-        request: {
+    return Statly.trace(`${request.method} ${request.nextUrl?.pathname || request.url}`, async (span) => {
+      span.setTag("component", "nextjs-app-router");
+      span.setTag("http.method", request.method);
+      span.setTag("http.url", request.nextUrl?.pathname || request.url);
+      Statly.addBreadcrumb({
+        category: "http",
+        message: `${request.method} ${request.nextUrl?.pathname || request.url}`,
+        level: "info",
+        data: {
           method: request.method,
-          url: request.nextUrl?.pathname || request.url,
-          headers: sanitizeHeaders2(headers),
-          searchParams: request.nextUrl?.searchParams?.toString()
+          url: request.nextUrl?.pathname || request.url
         }
-      };
-      if (context?.params) {
-        try {
-          errorContext.params = await context.params;
-        } catch {
+      });
+      try {
+        const result = await handler(request, context);
+        if (result instanceof Response) {
+          span.setTag("http.status_code", result.status.toString());
         }
+        return result;
+      } catch (error) {
+        const headers = {};
+        request.headers.forEach((value, key) => {
+          headers[key] = value;
+        });
+        const errorContext = {
+          request: {
+            method: request.method,
+            url: request.nextUrl?.pathname || request.url,
+            headers: sanitizeHeaders2(headers),
+            searchParams: request.nextUrl?.searchParams?.toString()
+          }
+        };
+        if (context?.params) {
+          try {
+            errorContext.params = await context.params;
+          } catch {
+          }
+        }
+        Statly.captureException(error, errorContext);
+        throw error;
       }
-      Statly.captureException(error, errorContext);
-      throw error;
-    }
+    });
   };
   return wrappedHandler;
 }
@@ -896,20 +1092,24 @@ function withStatlyGetStaticProps(handler) {
 }
 function withStatlyServerAction(action, actionName) {
   return async (...args) => {
-    Statly.addBreadcrumb({
-      category: "action",
-      message: `Server action: ${actionName || "unknown"}`,
-      level: "info"
-    });
-    try {
-      return await action(...args);
-    } catch (error) {
-      Statly.captureException(error, {
-        source: "server-action",
-        actionName
+    return Statly.trace(`Action: ${actionName || "unknown"}`, async (span) => {
+      span.setTag("component", "nextjs-server-action");
+      span.setTag("action.name", actionName || "unknown");
+      Statly.addBreadcrumb({
+        category: "action",
+        message: `Server action: ${actionName || "unknown"}`,
+        level: "info"
       });
-      throw error;
-    }
+      try {
+        return await action(...args);
+      } catch (error) {
+        Statly.captureException(error, {
+          source: "server-action",
+          actionName
+        });
+        throw error;
+      }
+    });
   };
 }
 function sanitizeHeaders2(headers) {
@@ -1122,6 +1322,20 @@ async function close() {
 function getClient() {
   return client;
 }
+async function trace2(name, operation, tags) {
+  if (!client) {
+    return operation(null);
+  }
+  return client.trace(name, operation, tags);
+}
+function startSpan(name, tags) {
+  if (!client) return null;
+  return client.startSpan(name, tags);
+}
+function captureSpan(span) {
+  if (!client) return "";
+  return client.captureSpan(span);
+}
 var Statly = {
   init,
   captureException,
@@ -1132,7 +1346,10 @@ var Statly = {
   addBreadcrumb,
   flush,
   close,
-  getClient
+  getClient,
+  trace: trace2,
+  startSpan,
+  captureSpan
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -1142,6 +1359,7 @@ var Statly = {
   captureException,
   captureMessage,
   captureNextJsError,
+  captureSpan,
   close,
   createRequestCapture,
   expressErrorHandler,
@@ -1152,8 +1370,10 @@ var Statly = {
   setTag,
   setTags,
   setUser,
+  startSpan,
   statlyFastifyPlugin,
   statlyPlugin,
+  trace,
   withStatly,
   withStatlyGetServerSideProps,
   withStatlyGetStaticProps,

package/dist/index.mjs

@@ -5,6 +5,7 @@ import {
   captureException,
   captureMessage,
   captureNextJsError,
+  captureSpan,
   close,
   createRequestCapture,
   expressErrorHandler,
@@ -15,14 +16,17 @@ import {
   setTag,
   setTags,
   setUser,
+  startSpan,
   statlyFastifyPlugin,
   statlyPlugin,
+  trace,
   withStatly,
   withStatlyGetServerSideProps,
   withStatlyGetStaticProps,
   withStatlyPagesApi,
   withStatlyServerAction
-} from "./chunk-UNDSALI5.mjs";
+} from "./chunk-HYFH22G6.mjs";
+import "./chunk-J5AHUFP2.mjs";
 export {
   Statly,
   StatlyClient,
@@ -30,6 +34,7 @@ export {
   captureException,
   captureMessage,
   captureNextJsError,
+  captureSpan,
   close,
   createRequestCapture,
   expressErrorHandler,
@@ -40,8 +45,10 @@ export {
   setTag,
   setTags,
   setUser,
+  startSpan,
   statlyFastifyPlugin,
   statlyPlugin,
+  trace,
   withStatly,
   withStatlyGetServerSideProps,
   withStatlyGetStaticProps,