npm package: @labana-vividh32/react-apm
Description: Lightweight APM tool for capturing page load time, network metrics, and errors
Author: Vividh Labana
Latest version: 0.2.0

# @labana-vividh32/react-apm

A lightweight Application Performance Monitoring (APM) tool for capturing page load time, network metrics, resource usage, and errors in web applications.

## Features

- 📊 Page load performance metrics
- 🌐 Network request monitoring (fetch and XMLHttpRequest)
- ⚠️ Error tracking (runtime errors and unhandled promises)
- 🔄 Session tracking
- 📈 Custom event timing
- 🪶 Lightweight with zero dependencies

## Installation

```bash
npm install @labana-vividh32/react-apm
```

## Quick Start

```javascript
import { initAPM } from '@labana-vividh32/react-apm';

// Initialize at the entry point of your application
initAPM({
  endpoint: 'https://your-apm-backend.com/metrics',
  appName: 'my-awesome-app'
});
```

## Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `endpoint` | String | URL where metrics will be sent (required) |
| `appName` | String | Name of your application (default: 'unknown-app') |

## Metrics Collected

### Page Load Metrics
Automatically captures page load timing information when your application initializes.

### Network Metrics
Monitors all fetch and XMLHttpRequest calls, capturing:
- URL
- Method
- Status code
- Duration
- Error information (if applicable)

### Error Metrics
Automatically captures:
- Unhandled JavaScript exceptions
- Unhandled Promise rejections

### Custom Event Metrics
Track custom operations with timing information.

## Usage Examples

### Custom Event Tracking

Track custom events and measure their duration:

```javascript
import { startEvent, endEvent } from '@labana-vividh32/react-apm';

// Start tracking an event
function loadUserProfile() {
  // Start the event
  startEvent('userProfileLoad');
  
  fetchUserData()
    .then(data => {
      // Process data
      endEvent('userProfileLoad');
    })
    .catch(error => {
      // Handle error
      endEvent('userProfileLoad');
    });
}
```

## Session Tracking

Each page session gets a unique identifier that's included with all metrics. This allows you to correlate metrics from the same user session.

## Server-Side Integration

The APM client sends data to your specified endpoint in the following format:

```json
{
  "app": "your-app-name",
  "sessionId": "unique-session-identifier",
  "metrics": {
    "type": "page_load|network_request|error|custom_event",
    "timestamp": 1634567890123,
    // Additional metrics specific to the type
  }
}
```

### Metric Types and Their Properties

#### Page Load Metrics
```json
{
  "type": "page_load",
  "timestamp": 1634567890123,
  "timetaken": 1250 // Time in milliseconds
}
```

#### Network Request Metrics
```json
{
  "type": "network_request",
  "timestamp": 1634567890123,
  "method": "GET",
  "url": "https://api.example.com/data",
  "status": 200,
  "duration": 350 // Time in milliseconds
}
```

#### Error Metrics
```json
{
  "type": "error",
  "timestamp": 1634567890123,
  "subtype": "runtime_error|unhandled_promise",
  "message": "TypeError: Cannot read property 'x' of undefined",
  "stack": "Error at line..."
}
```

#### Custom Event Metrics
```json
{
  "type": "custom_event",
  "timestamp": 1634567890123,
  "name": "userProfileLoad",
  "duration": 450 // Time in milliseconds
}
```

## Browser Compatibility

Compatible with all modern browsers that support:
- Fetch API
- Performance API
- ES6 features

## License

MIT