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
 
@@ -74,6 +74,7 @@ Initialization settings:
 | `disableGlobalErrorsHandling` | boolean | optional | Do not initialize global errors handling |
 | `disableVueErrorHandler` | boolean | optional | Do not initialize Vue errors handling |
 | `beforeSend` | function(event) => event | optional | This Method allows you to filter any data you don't want sending to Hawk |
+| `performance` | boolean\|object | optional | Performance monitoring settings. When object, accepts: <br> - `sampleRate`: Sample rate (0.0 to 1.0, default: 1.0) <br> - `batchInterval`: Batch send interval in ms (default: 3000) |
 
 Other available [initial settings](types/hawk-initial-settings.d.ts) are described at the type definition.
 
@@ -151,7 +152,6 @@ const hawk = new HawkCatcher({
 
 or pass it any moment after Hawk Catcher was instantiated:
 
-
 ```js
 import Vue from 'vue';
 
@@ -161,3 +161,176 @@ const hawk = new HawkCatcher({
 
 hawk.connectVue(Vue)
 ```
+
+## Performance Monitoring
+
+The SDK can monitor performance of your application by tracking transactions and spans.
+
+### Transaction Batching
+
+By default, transactions are collected and sent in batches every 3 seconds to reduce network overhead.
+You can configure the batch interval using the `batchInterval` option:
+
+```js
+const hawk = new HawkCatcher({
+  token: 'INTEGRATION_TOKEN',
+  performance: {
+    batchInterval: 5000 // Send batches every 5 seconds
+  }
+});
+```
+
+Transactions are automatically batched and sent:
+- Every `batchInterval` milliseconds
+- When the page is unloaded (in browser)
+- When the process exits (in Node.js)
+
+### Sampling
+
+You can configure what percentage of transactions should be sent to Hawk using the `sampleRate` option:
+
+```typescript
+const hawk = new HawkCatcher({
+  token: 'INTEGRATION_TOKEN',
+  performance: {
+    sampleRate: 0.2
+  }
+});
+```
+
+Features:
+- Track transactions and spans with timing data
+- Automatic span completion when transaction ends
+- Support for both browser and Node.js environments
+- Debug mode for development
+- Throttled data sending to prevent server overload
+- Graceful cleanup on page unload/process exit
+
+> Note: If performance monitoring is not enabled, `startTransaction()` will return undefined and log an error to the console.
+
+### 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 call.
+
+- `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;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  tags: Record<string, string>;
+  spans: Span[];
+  startSpan(name: string, metadata?: Record<string, any>): Span;
+  finish(): void;
+}
+```
+
+#### Span
+```typescript
+interface Span {
+  id: string;
+  transactionId: string;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  metadata?: Record<string, any>;
+  finish(): void;
+}
+```
+
+### 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(() => {
+    transaction.finish();
+  });
+});
+```
+
+#### Measuring API Calls
+```javascript
+async function fetchUsers() {
+  const transaction = hawk.startTransaction('fetch-users');
+
+  const apiSpan = transaction.startSpan('GET /api/user', {
+    url: '/api/users',
+    method: 'GET'
+  });
+
+  try {
+    const response = await fetch('/api/users');
+    const data = await response.json();
+
+    apiSpan.finish();
+
+    const processSpan = transaction.startSpan('process-data');
+    // Process data...
+    processSpan.finish();
+
+    return data;
+  } finally {
+    transaction.finish();
+  }
+}
+```
+
+### Configuration
+
+- `token`: Your project's Integration Token
+- `release`: Unique identifier of the release. Used for source map consuming
+- `user`: Current authenticated user
+- `context`: Any data you want to pass with every message. Has limitation of length.
+- `vue`: Pass Vue constructor to set up the [Vue integration](#integrate-to-vue-application)
+- `disableGlobalErrorsHandling`: Do not initialize global errors handling
+- `disableVueErrorHandler`: Do not initialize Vue errors handling
+- `beforeSend`: This Method allows you to filter any data you don't want sending to Hawk
+- `performance`: Enable/disable performance monitoring
+  - `true`: Enable with 100% sampling
+  - `{sampleRate: number}`: Enable with custom sampling rate (0.0 to 1.0)
+  - `false` or `undefined`: Disable performance monitoring