# Instrumentación de aplicaciones (monitoreo en detalle)

## Para qué sirve

El agente puede mirar por dentro las aplicaciones de un servidor, **sin cambiar su código**: cada pedido que reciben, las consultas que hacen a bases de datos y las llamadas a otros servicios. Con eso Lymen arma las **trazas** (el recorrido de un pedido a través de tus sistemas) y te dice dónde se demora o falla algo. Se activa **aplicación por aplicación**, desde el detalle del servidor en **Observar › Infraestructura**, sección **Monitoreo en detalle de aplicaciones**.

## Cuándo usarlo

- Tenés una aplicación propia o de un tercero (Java, Node.js, .NET, Python) y querés saber por qué tarda.
- Querés unir lo que ve el navegador o la app móvil con lo que pasa en tu servidor (ver [Aplicaciones](https://lymen.app/docs/instalacion/aplicaciones/)).

No hace falta para medir el servidor en sí (CPU, memoria, disco): eso ya lo hace el agente.

## Qué se puede medir

| Tecnología | Linux | Windows | Requisito mínimo |
|---|---|---|---|
| Java | Sí | Sí | — |
| Node.js | Sí | Sí | — |
| .NET (Core / 5 en adelante) | Sí | Sí | .NET 8 o más nuevo |
| .NET Framework (clásico, con IIS) | — | Sí | .NET Framework 4.6.2 o más nuevo |
| Python | Sí | No | — |
| Otras tecnologías | No | No | — |

Si una aplicación no se puede medir, el portal te dice por qué:

| Motivo | Qué significa |
|---|---|
| Esta tecnología todavía no se puede monitorear en detalle | No está en la lista de arriba. |
| La versión es demasiado vieja | .NET anterior a 8 (o .NET Framework anterior a 4.6.2). |
| Ya la monitorea otra herramienta y no conviene pisarla | Se detectó otro agente de monitoreo. Solo puede haber uno por aplicación. |
| El agente no tiene permiso para modificarla | Falta un permiso del sistema operativo. |
| El servicio ya no está en el servidor | Se borró o cambió. |
| No se pudo aplicar el cambio | Error al configurar. Reintentá y revisá el historial. |

## Cómo se instala y se activa

### 1. Instalar el paquete

Se instala junto con el agente: en **Configuración › Conexiones › Agregar datos › Agregar servidor**, tildá **Instalar también el monitoreo en detalle** antes de **Generar comando** (ver [Agregar datos](https://lymen.app/docs/instalacion/agregar-datos/), [Linux](https://lymen.app/docs/instalacion/agente-linux/) y [Windows](https://lymen.app/docs/instalacion/agente-windows/)). Esto **no toca ninguna aplicación**: deja instalado un servicio que espera las instrucciones del portal. Si falla, el agente queda instalado igual.

Para un servidor que **ya está conectado**, generá el comando con la casilla tildada, con los mismos gateways y grupo, y corrélo de nuevo en ese servidor: se reinstala sobre el mismo servidor y conserva su grupo, su política y su historial. Mientras no esté instalado, la sección del servidor dice que todavía no informó sus aplicaciones y te recuerda cómo instalarlo.

En Linux funciona con glibc (no con Alpine/musl). El paquete consulta el portal y le informa el estado cada 30 segundos: todo lo demás se maneja desde el portal.

### 2. Activar una aplicación

1. Abrí el servidor en **Observar › Infraestructura**.
2. En **Monitoreo en detalle de aplicaciones** vas a ver las aplicaciones y servicios que el agente encontró.
3. Tocá **Activar monitoreo en detalle** en la que quieras.
4. Elegí:
   - **Activar y reiniciar ahora**: la aplicación se reinicia y **queda sin servicio unos segundos**.
   - **Activar, reiniciar después**: se activa en el próximo reinicio de la aplicación (el estado dice *Falta reiniciar*).

La aplicación **necesita reiniciarse** para empezar o para dejar de medirse. Elegí un horario de poco uso.

Para dejar de medir una aplicación, tocá **Desactivar** y confirmá con **Sí, desactivar**: deja de medirse cuando se reinicie; hasta entonces sigue como está.

### Estados de una aplicación

| Estado | Significa |
|---|---|
| **Se puede monitorear en detalle** | Compatible y todavía sin activar. |
| **Falta reiniciar** | Activada, pero todavía corre sin el monitoreo (o al revés, al desactivar). Botón **Reiniciar ahora**. |
| **Monitoreada en detalle** | Funcionando. |
| **Pausada** | El monitoreo está pausado en el servidor. |
| **No compatible** | Ver los motivos más arriba. |
| **Con error** | No se pudo aplicar el cambio. |

### Pausar y reanudar

**Pausar el monitoreo en detalle en este servidor** (pide confirmación con **Sí, pausar**) es el interruptor de emergencia: las aplicaciones que arranquen o se reinicien a partir de ahora lo hacen sin monitoreo, enseguida y sin reiniciar el servidor, y se apaga la captura de cuerpos. **Límite:** una aplicación que ya está corriendo sigue medida hasta que se reinicie. Para volver, tocá **Reanudar el monitoreo en detalle**.

## Métodos extra de Java

Solo para aplicaciones Java ya activadas. Además de lo que se ve solo (pedidos, bases de datos, llamadas a otros servicios), podés pedir que se mida el tiempo de métodos puntuales: botón **Métodos extra** en la aplicación, **Agregar una clase** y **Guardar**. Se aplican cuando la aplicación se reinicia.

| Campo | Para qué sirve | Por defecto | Valores válidos | Impacto |
|---|---|---|---|---|
| **Clase (con su paquete)** | La clase a medir. | — | Nombre completo, por ejemplo `com.empresa.turnos.Reserva`. Hasta 30 clases, sin repetir. | Cada clase agrega trabajo a la aplicación; medí solo lo que necesites. |
| **Métodos** | Qué métodos de esa clase. | — | Solo letras, números, `_` y `$` (sin paréntesis ni comas). Hasta 20 por clase y al menos uno. | Un método llamado muchísimas veces por segundo genera muchos datos (y costo). |

## Qué se captura de los pedidos

La sección **Qué se captura de los pedidos**, en el mismo detalle del servidor, controla el detalle que se guarda de cada pedido HTTP. **Siempre** se guarda: el método, la ruta, el estado de la respuesta y cuánto tardó. Lo demás lo elegís con **Editar** (solo Administración; Sistemas puede **Ver detalle**).

### Campos

| Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo |
|---|---|---|---|---|
| **Cabeceras del pedido** | Cabeceras HTTP del pedido que se guardan. Solo se guardan las de esta lista. | `user-agent`, `x-request-id`, `content-type` | Hasta 20, en minúsculas. | Cada cabecera extra puede traer datos personales. Las que pueden llevar credenciales (`authorization`, `cookie`, `set-cookie`, `x-api-key`, las que contienen `token`, `secret`, `password`, `clave`, `apikey`, `session`…) **no se pueden agregar nunca**. |
| **Cabeceras de la respuesta** | Ídem, para la respuesta. | `content-type` | Hasta 20. | Ídem. |
| **Parámetros a enmascarar** | Parámetros de la dirección (`?dni=…`) cuyo valor se reemplaza por `***` antes de guardarse. | `token`, `access_token`, `id_token`, `refresh_token`, `password`, `passwd`, `pwd`, `secret`, `apikey`, `api_key`, `authorization`, `signature` (el núcleo, que no se puede sacar), más `clave`, `key`, `auth`, `sig`, `dni`, `cuil`, `email`, `code` | Hasta 50 nombres; letras, números, `_ . - [ ]`, hasta 60 caracteres. | **Privacidad.** Sacar un parámetro hace que su valor se guarde en claro. Sumá los que tengan datos de pacientes o clientes. |
| **Capturar cuerpos de las rutas elegidas** | Guarda el cuerpo de pedidos y respuestas en las rutas que elijas. | **Apagado** | Encendido / apagado | **Privacidad y costo.** Un cuerpo puede traer datos médicos o financieros. Encendelo solo en las rutas necesarias, para depurar. |
| **Rutas** (con cuerpos) | Qué rutas capturar (**Agregar una ruta**). | — | Método (`GET`, `POST`, `PUT`, `PATCH`, `DELETE` o cualquiera), ruta que empieza con `/` y puede terminar en `*` (por ejemplo `/api/pagos/*`), hasta 100 caracteres; y si capturar la solicitud, la respuesta o las dos. Hasta 20 rutas, sin repetir. | Una ruta con `*` amplía muy rápido lo capturado. Hace falta al menos una ruta con cuerpos encendidos. |
| **Tope por cuerpo** | Tamaño máximo guardado de cada cuerpo. | 2048 bytes | De 256 a 8192 | Más tope, más datos guardados y más costo. El resto se corta. |
| **Retención pedida** | Cuánto tiempo se pide conservar los cuerpos. | 24 horas | De 1 a 72 horas | El valor queda marcado en cada registro, pero el borrado lo hace el nivel de retención corta (hoy hasta 72 horas). |
| **Elementos XML a tapar** | Nombres de elementos XML cuyo contenido se reemplaza por `***`. | Vacío (además de los de siempre) | Hasta 50. Formas: `Nombre`, `prefijo:Nombre` o `{espacio-de-nombres}Nombre`. Sin comodines. | Tapar un elemento oculta también todo lo que tiene adentro. |
| **Atributos XML a tapar** | Ídem, para atributos. | Vacío | Hasta 50. | Ídem. |

Cosas a tener en cuenta:

- **Solo texto.** Los cuerpos binarios no se guardan.
- **Privacidad manda.** Lo que una regla de Privacidad ya enmascara sigue enmascarado: acá solo podés sumar nombres.
- **XML y SOAP.** Se entienden `application/xml`, `text/xml`, `application/soap+xml` y todo lo que termine en `+xml`. Si es SOAP, la operación aparece en el detalle de la traza, también con WS-Security. Siempre se tapan elementos como `Password`, `BinarySecurityToken`, `Nonce`, `SignatureValue`, `Assertion`, `SAMLRequest`, `SAMLResponse` y los que contienen cosas como `pass`, `clave`, `token`, `secret`, `dni`, `cuil`, `cuit`, `tarjeta`, `cvv`, `signature`. Un XML cortado por el tope o mal formado se tapa igual por nombre.
- **Cuándo rige cada cambio.** Los cuerpos rigen en segundos, sin reiniciar. Las cabeceras y los métodos extra de Java se aplican cuando la aplicación se reinicia.

### En qué lenguajes se pueden capturar cuerpos

| Lenguaje | Cuerpos | XML y SOAP | Detalle |
|---|---|---|---|
| Node.js | Sí | Sí | |
| Python | Sí | Sí | Flask, Django, FastAPI y Starlette |
| Java | Sí | Sí | Servlets y el servidor HTTP del JDK |
| .NET | Sí | Sí | ASP.NET Core 8 o más nuevo |
| .NET Framework | Sí | Sí | IIS clásico (ver abajo) |

No se capturan cuerpos con Netty, Reactor, Undertow, Vert.x, gRPC ni WebSockets.

## .NET Framework clásico e IIS

Para aplicaciones .NET Framework 4.6.2 o más nuevo que corren en IIS (WebForms, MVC 5, Web API 2, WCF y ASMX), Lymen usa un módulo propio **sin editar el `web.config`** de tu aplicación.

- Se activa igual que las demás: **Activar monitoreo en detalle** y reiniciar. En IIS ese reinicio puede requerir reciclar el grupo de aplicaciones o hacer un `iisreset`: planificalo en un horario tranquilo.
- Solo se copia lo que la aplicación **ya leyó en memoria**. Una lectura sin buffer (subidas grandes, streaming) no se copia: es un límite conocido.
- Solo hay un "profiler" de .NET por proceso. Si ya hay otra herramienta de monitoreo, Lymen no la pisa y marca la aplicación como no compatible.
- Para sacarlo, usá **Desactivar** en la aplicación y reciclá el grupo de aplicaciones.

## Kubernetes

En Kubernetes la instrumentación no se activa desde esta sección, sino con una anotación en el pod de tu aplicación. Ver [Kubernetes](https://lymen.app/docs/instalacion/kubernetes/).

## Problemas comunes

| Síntoma | Qué hacer |
|---|---|
| No veo mi aplicación en la lista | Tiene que correr como **servicio** (systemd o servicio de Windows). Debajo de la lista, "Procesos que ve el agente" avisa si hay procesos de una tecnología compatible que no corren como servicio: esos no se monitorean solos, hay que instalarlos como servicio. |
| Dice *Falta reiniciar* | Reiniciá la aplicación (**Reiniciar ahora**) en un horario tranquilo. |
| *No compatible: ya la monitorea otra herramienta* | Desactivá la otra herramienta en esa aplicación o dejala como está. |
| No llegan trazas después de activar | Confirmá que la aplicación se reinició y que el estado dice *Monitoreada en detalle*. |
| "El monitoreo en detalle está pausado" | Reanudalo con **Reanudar el monitoreo en detalle**. |
| Solo veo un cuerpo cortado | Subí el **Tope por cuerpo** (hasta 8192 bytes). |