@ajaltech/monitrace/README.md

Librería de monitoreo de errores frontend creada por Ajal Technology

# Monitrace

**Monitrace** es una librería agnóstica para el registro, seguimiento y visualización de errores en aplicaciones web frontend.

Captura errores globales y de red (`axios`, `fetch`, `xhr`) y los envía a un backend centralizado para su análisis y visualización, con soporte de fallback offline (almacenamiento local en caso de desconexión).

---

## 🧠 ¿Qué es Monitrace?

Monitrace es parte de la solución de trazabilidad de errores frontend desarrollada por **Ajal Technology**, que incluye:

- Un SDK ligero multiplataforma (compatible con Angular, Vue, React y Vanilla JS).
- Un backend REST para almacenar errores.
- Un **portal administrativo** para visualizar errores por aplicación, ruta, tipo, fecha y usuario.

Esta herramienta permite detectar rápidamente errores en producción y mejorar la experiencia del usuario con análisis visuales.

---

## 🚀 Instalación

```bash
npm install @ajaltech/monitrace
```

## 🛠️ Uso básico

```javascript
import { initMonitrace } from "@ajaltech/monitrace";

initMonitrace({
  client: "axios", // o 'fetch' o 'xhr'
  endpoint: "https://api.midominio.com/errores",
  appName: "mi-app-frontend",
  localFallback: true,
  userContext: () => ({
    userId: getUserId(),
    sessionId: getSessionId(),
  }),
});
```

## 🔍 Visualización de errores

El backend de Monitrace incluye un portal de administración que permite:

- Consultar errores del día.
- Ver rutas más problemáticas.
- Filtrar por usuario, tipo de error o componente.
- Exportar logs o integrarlos con otras herramientas.

> **Nota:** El backend está incluido como parte de la solución Monitrace y puede ser desplegado en un entorno privado o en la nube.

---

## ⚙️ Tecnologías utilizadas

Monitrace utiliza las siguientes tecnologías:

- **TypeScript**
- **tsup** (compilador)
- **Axios / Fetch interceptors**
- **localStorage / IndexedDB** (soporte offline)
- **MongoDB backend** (parte de la solución completa)

---

## 🛠️ Uso con Angular (HttpClient)

Monitrace no intercepta directamente las llamadas realizadas con `HttpClient` de Angular, ya que este no utiliza `fetch` ni `axios`. Para capturar errores HTTP en Angular, es necesario instalar un interceptor dentro del proyecto Angular que envíe los errores a Monitrace.

### 🔧 Paso 1: Crear un interceptor en tu proyecto Angular

```typescript
// monitrace-http.interceptor.ts
import { Injectable } from "@angular/core";
import {
  HttpInterceptor,
  HttpRequest,
  HttpHandler,
  HttpEvent,
  HttpErrorResponse,
} from "@angular/common/http";
import { Observable, throwError } from "rxjs";
import { catchError } from "rxjs/operators";
import { sendError } from "@ajaltech/monitrace";

@Injectable()
export class MonitraceHttpInterceptor implements HttpInterceptor {
  intercept(
    req: HttpRequest<any>,
    next: HttpHandler
  ): Observable<HttpEvent<any>> {
    return next.handle(req).pipe(
      catchError((err: HttpErrorResponse) => {
        sendError(
          {
            message: err.message,
            stack: "", // Angular no expone stack, puede dejarse vacío
            route: window.location.href,
            type: "http",
          },
          {
            endpoint: "https://TU_BACKEND/errores",
            appName: "MiAngularApp",
          }
        );
        return throwError(() => err);
      })
    );
  }
}
```

> Reemplaza `endpoint` y `appName` con los datos reales de tu proyecto.

---

### 🧩 Paso 2: Registrar el interceptor en `AppModule`

```typescript
import { HTTP_INTERCEPTORS } from "@angular/common/http";
import { MonitraceHttpInterceptor } from "./monitrace-http.interceptor";

@NgModule({
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MonitraceHttpInterceptor,
      multi: true,
    },
  ],
})
export class AppModule {}
```

> 💡 Este paso es opcional si tu proyecto Angular utiliza `axios` o `fetch`, ya que Monitrace puede interceptarlos automáticamente desde la librería.

## 🏷️ Licencia y atribución

Monitrace es una herramienta desarrollada y mantenida por **Ajal Technology**. Su uso está permitido bajo términos privados o de distribución empresarial.

Para más información, visita [https://ajaltechnology.com](https://ajaltechnology.com).
Su uso está permitido bajo términos privados o de distribución empresarial.
Para más información, visita https://ajaltechnology.com