@statly/observe 1.0.0 → 1.1.0

package/README.md

@@ -12,6 +12,8 @@ Error tracking and monitoring for JavaScript and TypeScript applications. Captur
 ## Features
 
 - Automatic error capturing with stack traces
+- **Distributed Tracing**: Visualize function execution and call hierarchies
+- **Performance Metrics**: Automated capture of latency and success rates
 - Breadcrumbs for debugging context
 - User context tracking
 - Release tracking
@@ -86,10 +88,45 @@ Statly.addBreadcrumb({
   level: 'info',
 });
 
-// Flush before exit (important for serverless)
+# Flush before exit (important for serverless)
 await Statly.close();
 ```
 
+## Tracing & Performance
+
+Statly Observe supports distributed tracing to help you visualize execution flow and measure backend performance.
+
+### Automatic Tracing
+
+Use `Statly.trace()` to wrap functions. It works with both synchronous and asynchronous code:
+
+```typescript
+import { Statly } from '@statly/observe';
+
+const result = await Statly.trace('process_payment', async (span) => {
+  span.setTag('provider', 'stripe');
+  
+  // Your logic here
+  const payment = await stripe.charges.create({...});
+  
+  return payment;
+});
+```
+
+### Manual Spans
+
+For low-level control, you can start spans manually:
+
+```typescript
+const span = Statly.startSpan('database_query');
+try {
+  await db.query('...');
+  span.setTag('query_type', 'SELECT');
+} finally {
+  span.finish(); // Reports to Statly
+}
+```
+
 ## Framework Integrations
 
 ### Express

package/dist/{chunk-UNDSALI5.mjs → chunk-HYFH22G6.mjs}

@@ -1,3 +1,7 @@
+import {
+  TelemetryProvider
+} from "./chunk-J5AHUFP2.mjs";
+
 // src/transport.ts
 var Transport = class {
   constructor(options) {
@@ -356,6 +360,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 {
@@ -441,6 +446,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 import("./telemetry-CXHOTW3Y.mjs");
+    return traceFn(name, operation, tags);
+  }
   /**
    * Internal method to capture an error
    */
@@ -652,66 +681,81 @@ var StatlyClient = class {
 // 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: sanitizeHeaders(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: sanitizeHeaders(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: sanitizeHeaders(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: sanitizeHeaders(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;
 }
@@ -750,20 +794,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 sanitizeHeaders(headers) {
@@ -976,6 +1024,20 @@ async function close() {
 function getClient() {
   return client;
 }
+async function trace(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,
@@ -986,7 +1048,10 @@ var Statly = {
   addBreadcrumb,
   flush,
   close,
-  getClient
+  getClient,
+  trace,
+  startSpan,
+  captureSpan
 };
 
 // src/integrations/express.ts
@@ -1110,5 +1175,8 @@ export {
   flush,
   close,
   getClient,
+  trace,
+  startSpan,
+  captureSpan,
   Statly
 };

package/dist/chunk-J5AHUFP2.mjs

@@ -0,0 +1,135 @@
+// src/span.ts
+var 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
+    };
+  }
+};
+var TraceContext = class {
+  static getActiveSpan() {
+    return this.currentSpan;
+  }
+  static setActiveSpan(span) {
+    this.currentSpan = span;
+  }
+};
+TraceContext.currentSpan = null;
+
+// src/telemetry.ts
+var TelemetryProvider = class _TelemetryProvider {
+  constructor() {
+    this.client = null;
+  }
+  static getInstance() {
+    if (!_TelemetryProvider.instance) {
+      _TelemetryProvider.instance = new _TelemetryProvider();
+    }
+    return _TelemetryProvider.instance;
+  }
+  setClient(client) {
+    this.client = client;
+  }
+  /**
+   * 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);
+  }
+};
+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);
+  }
+}
+
+export {
+  TelemetryProvider,
+  trace
+};

package/dist/index.d.mts

@@ -2,6 +2,55 @@ export { expressErrorHandler, requestHandler } from './integrations/express.mjs'
 export { captureNextJsError, withStatly, withStatlyGetServerSideProps, withStatlyGetStaticProps, withStatlyPagesApi, withStatlyServerAction } from './integrations/nextjs.mjs';
 export { createRequestCapture, statlyFastifyPlugin, statlyPlugin } from './integrations/fastify.mjs';
 
+/**
+ * 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 };