feat(perf): Add performance measuring api

README.md

@@ -24,7 +24,7 @@ Then import `@hawk.so/javascript` module to your code.
 
 ```js
 import HawkCatcher from '@hawk.so/javascript';
-````
+```
 
 ### Load from CDN
 
@@ -151,7 +151,6 @@ const hawk = new HawkCatcher({
 
 or pass it any moment after Hawk Catcher was instantiated:
 
-
 ```js
 import Vue from 'vue';
 
@@ -161,3 +160,151 @@ const hawk = new HawkCatcher({
 
 hawk.connectVue(Vue)
 ```
+
+## Performance Monitoring
+
+Hawk JavaScript Catcher also provides performance monitoring capabilities. You can track transactions and spans to measure the performance of your application.
+
+### Basic Usage
+
+```javascript
+const hawk = new Catcher('your-integration-token');
+
+// Start a transaction
+const transaction = hawk.startTransaction('page-load', {
+  route: '/dashboard',
+  method: 'GET'
+});
+
+// Create a span for measuring API call
+const apiSpan = hawk.startSpan(transaction.id, 'api-request', {
+  url: '/api/users',
+  method: 'GET'
+});
+
+// Do some API work...
+
+// Finish the span when API call is done
+hawk.finishSpan(apiSpan.id);
+
+// Create another span for data processing
+const processSpan = hawk.startSpan(transaction.id, 'process-data');
+
+// Do processing work...
+
+// Finish the processing span
+hawk.finishSpan(processSpan.id);
+
+// Finish the transaction
+hawk.finishTransaction(transaction.id);
+```
+
+### API Reference
+
+#### startTransaction(name: string, tags?: Record<string, string>): Transaction
+
+Starts a new transaction. A transaction represents a high-level operation like a page load or an API request.
+
+- `name`: Name of the transaction
+- `tags`: Optional key-value pairs for additional transaction data
+
+#### startSpan(transactionId: string, name: string, metadata?: Record<string, any>): Span
+
+Creates a new span within a transaction. Spans represent smaller units of work within a transaction.
+
+- `transactionId`: ID of the parent transaction
+- `name`: Name of the span
+- `metadata`: Optional metadata for the span
+
+#### finishSpan(spanId: string): void
+
+Finishes a span and calculates its duration.
+
+- `spanId`: ID of the span to finish
+
+#### finishTransaction(transactionId: string): void
+
+Finishes a transaction, calculates its duration, and sends the performance data to Hawk.
+
+- `transactionId`: ID of the transaction to finish
+
+### Data Model
+
+#### Transaction
+```typescript
+interface Transaction {
+  id: string;
+  traceId: string;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  tags: Record<string, string>;
+  spans: Span[];
+}
+```
+
+#### Span
+```typescript
+interface Span {
+  id: string;
+  transactionId: string;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  metadata?: Record<string, any>;
+}
+```
+
+### Examples
+
+#### Measuring Route Changes in Vue.js
+```javascript
+import { Catcher } from '@hawk.so/javascript';
+import Vue from 'vue';
+import Router from 'vue-router';
+
+const hawk = new Catcher('your-integration-token');
+
+router.beforeEach((to, from, next) => {
+  const transaction = hawk.startTransaction('route-change', {
+    from: from.path,
+    to: to.path
+  });
+
+  next();
+
+  // After route change is complete
+  Vue.nextTick(() => {
+    hawk.finishTransaction(transaction.id);
+  });
+});
+```
+
+#### Measuring API Calls
+```javascript
+async function fetchUsers() {
+  const transaction = hawk.startTransaction('fetch-users');
+
+  const apiSpan = hawk.startSpan(transaction.id, 'api-call', {
+    url: '/api/users',
+    method: 'GET'
+  });
+
+  try {
+    const response = await fetch('/api/users');
+    const data = await response.json();
+
+    hawk.finishSpan(apiSpan.id);
+
+    const processSpan = hawk.startSpan(transaction.id, 'process-data');
+    // Process data...
+    hawk.finishSpan(processSpan.id);
+
+    return data;
+  } finally {
+    hawk.finishTransaction(transaction.id);
+  }
+}
+```

example/index.html

@@ -84,6 +84,60 @@
             font-size: 15px;
             color:inherit;
         }
+
+        .performance-demo {
+            border-radius: 4px;
+        }
+
+        .performance-demo button {
+            padding: 8px 16px;
+            padding-right: 32px;
+            background: #4979E4;
+            color: white;
+            border: none;
+            border-radius: 4px;
+            cursor: pointer;
+            position: relative;
+            min-width: 200px;
+            text-align: left;
+        }
+
+        .performance-demo button:hover {
+            background: #4869d2;
+        }
+
+        .performance-demo button[disabled] {
+            background: #4979E4;
+            opacity: 0.7;
+            cursor: not-allowed;
+        }
+
+        .performance-demo button .spinner {
+            display: none;
+            width: 10px;
+            height: 10px;
+            border: 2px solid #fff;
+            border-bottom-color: transparent;
+            border-radius: 50%;
+            animation: rotation 1s linear infinite;
+            position: absolute;
+            right: 10px;
+            top: 50%;
+            margin-top: -5px;
+        }
+
+        .performance-demo button[disabled] .spinner {
+            display: block;
+        }
+
+        @keyframes rotation {
+            from {
+                transform: rotate(0deg);
+            }
+            to {
+                transform: rotate(360deg);
+            }
+        }
     </style>
 </head>
 <body>
@@ -152,7 +206,17 @@ <h2>Test console catcher</h2>
     <br><br>
     <button id="btn-console-test">Make</button>
 </section>
-<script src="https://unpkg.com/vue@2"></script>
+<section>
+    <h2>Performance Monitoring Demo</h2>
+    <div class="performance-demo">
+        <button id="simulateComplexOperation">
+            Simulate Complex Operation
+            <span class="spinner"></span>
+        </button>
+    </div>
+</section>
+<!-- <script src="https://unpkg.com/vue@2"></script> -->
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vue.js"></script>
 <section>
     <h2>Test Vue integration: $root</h2>
     <div id="vue-app-1">
@@ -196,7 +260,7 @@ <h2>Test Vue integration: &lt;test-component&gt;</h2>
             el: tag,
             instance: new Editor(),
             classProto: Editor,
-            longText: 'Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.',
+            longText: 'Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.Upvoting this, given it\'s simplicity. In my use case I need to check all the attributes in an object for dodgy values-NaNs, nulls, undefined (they were points on a graph and these values prevented the graph from drawing). To get the value instead of the name, in the loop you would just do obj[someVariable]. Perhaps the reason it was downvoted so much is because it is not recursive. So this would not be an adequate solution if you have a highly structured object.',
           }
         },
         props: {
@@ -236,5 +300,31 @@ <h2>Test Vue integration: &lt;test-component&gt;</h2>
     },
   })
 </script>
+<script>
+  // Simulate complex operation with nested spans
+  document.getElementById('simulateComplexOperation').addEventListener('click', () => {
+    const button = document.getElementById('simulateComplexOperation');
+    button.disabled = true;
+
+    const transaction = window.hawk.startTransaction('complex-operation', {
+      type: 'background'
+    });
+
+    const step1 = window.hawk.startSpan(transaction.id, 'step-1');
+    setTimeout(() => {
+      window.hawk.finishSpan(step1.id);
+
+      const step2 = window.hawk.startSpan(transaction.id, 'step-2');
+      // Simulate unfinished span
+
+      const step3 = window.hawk.startSpan(transaction.id, 'step-3');
+      setTimeout(() => {
+        window.hawk.finishSpan(step3.id);
+        window.hawk.finishTransaction(transaction.id);
+        button.disabled = false;
+      }, 300);
+    }, 400);
+  });
+</script>
 </body>
 </html>

src/catcher.ts

@@ -16,12 +16,16 @@
 import { EventRejectedError } from './errors';
 import type { HawkJavaScriptEvent } from './types';
 import { isErrorProcessed, markErrorAsProcessed } from './utils/event';
+import PerformanceMonitoring from './modules/performance';
+import type { Transaction } from './types/transaction';
+import type { Span } from './types/span';
 
 /**
  * Allow to use global VERSION, that will be overwritten by Webpack
  */
 declare const VERSION: string;
 
+
 /**
  * Hawk JavaScript Catcher
  * Module for errors and exceptions tracking
@@ -91,6 +95,12 @@
    */
   private readonly disableVueErrorHandler: boolean = false;
 
+
+  /**
+   * Performance monitoring instance
+   */
+  private readonly performance: PerformanceMonitoring;
+
   /**
    * Catcher constructor
    *
@@ -145,6 +155,16 @@
     if (settings.vue) {
       this.connectVue(settings.vue);
     }
+
+    /**
+     * Init performance monitoring
+     */
+    this.performance = new PerformanceMonitoring(
+      this.transport,
+      this.token,
+      this.version,
+      this.debug
+    );
   }
 
   /**
@@ -542,4 +562,50 @@
   private appendIntegrationAddons(errorFormatted: CatcherMessage, integrationAddons: JavaScriptCatcherIntegrations): void {
     Object.assign(errorFormatted.payload.addons, integrationAddons);
   }
+
+  /**
+   * Starts a new transaction
+   *
+   * @param name - Name of the transaction (e.g., 'page-load', 'api-request')
+   * @param tags - Key-value pairs for additional transaction data
+   */
+  public startTransaction(name: string, tags: Record<string, string> = {}): Transaction {
+    return this.performance.startTransaction(name, tags);
+  }
+
+  /**
+   * Starts a new span within a transaction
+   *
+   * @param transactionId - ID of the parent transaction this span belongs to
+   * @param name - Name of the span (e.g., 'db-query', 'http-request')
+   * @param metadata - Additional context data for the span
+   */
+  public startSpan(transactionId: string, name: string, metadata?: Record<string, any>): Span {
+    return this.performance.startSpan(transactionId, name, metadata);
+  }
+
+  /**
+   * Finishes a span
+   *
+   * @param spanId - ID of the span to finish
+   */
+  public finishSpan(spanId: string): void {
+    this.performance.finishSpan(spanId);
+  }
+
+  /**
+   * Finishes a transaction
+   *
+   * @param transactionId - ID of the transaction to finish
+   */
+  public finishTransaction(transactionId: string): void {
+    this.performance.finishTransaction(transactionId);
+  }
+
+  /**
+   * Clean up resources
+   */
+  public destroy(): void {
+    this.performance.destroy();
+  }
 }