# lymen: documentación completa > Fuente: https://lymen.app/docs/ # Documentación de Lymen Lymen te muestra, en un solo lugar, si tus sistemas funcionan, te avisa cuando algo falla y te ayuda a entender por qué. Esta guía está pensada para quien administra sistemas o gestiona una organización: frases cortas, sin jerga innecesaria. Cada pantalla se explica con **para qué sirve**, **cuándo usarla**, **paso a paso**, **una tabla de campos con el impacto de cada uno** y **problemas comunes**. Si es tu primera vez, empezá por [Primeros pasos](https://lymen.app/docs/instalacion/primeros-pasos/). Si una palabra no te suena, mirá el [Glosario](https://lymen.app/docs/glosario/). ## Cómo está organizada | Grupo | Para qué | Carpeta | |---|---|---| | **Instalación** | Conectar tus servidores, redes y aplicaciones a Lymen. | `instalacion/` | | **Datos** | Mirar y entender lo que Lymen recibe, y decidir qué guardar. | `datos/` | | **Operación** | Que Lymen te avise a tiempo, a la persona correcta, por el medio correcto. | `operacion/` | ## 1. Instalación Cómo hacer que Lymen empiece a recibir datos. - [Primeros pasos](https://lymen.app/docs/instalacion/primeros-pasos/) - [Agregar datos](https://lymen.app/docs/instalacion/agregar-datos/) - [Servidores e Infraestructura](https://lymen.app/docs/instalacion/servidores-infraestructura/) - [Gateways](https://lymen.app/docs/instalacion/gateways/) - [Grupos de servidores y actualización del agente](https://lymen.app/docs/instalacion/grupos-y-actualizacion/) - [Agente en Linux](https://lymen.app/docs/instalacion/agente-linux/) y [Agente en Windows](https://lymen.app/docs/instalacion/agente-windows/) - [Kubernetes](https://lymen.app/docs/instalacion/kubernetes/) - [Instrumentación de aplicaciones](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/) - [Equipos de red](https://lymen.app/docs/instalacion/equipos-de-red/) - [Aplicaciones (sitios web y apps móviles)](https://lymen.app/docs/instalacion/aplicaciones/) - SDK: [web](https://lymen.app/docs/instalacion/sdk-web/), [Android](https://lymen.app/docs/instalacion/sdk-android/), [iOS](https://lymen.app/docs/instalacion/sdk-ios/), [React Native](https://lymen.app/docs/instalacion/sdk-react-native/) - [Desinstalar](https://lymen.app/docs/instalacion/desinstalar/) ## 2. Datos Las pantallas para observar y entender lo que pasa, y para decidir qué datos se guardan. - [Resumen](https://lymen.app/docs/datos/resumen/) y [Dashboards](https://lymen.app/docs/datos/dashboards/) - [Servicios](https://lymen.app/docs/datos/servicios/), [Topología](https://lymen.app/docs/datos/topologia/), [Infraestructura](https://lymen.app/docs/datos/infraestructura/), [Equipos de red](https://lymen.app/docs/datos/equipos-red/), [Trazas](https://lymen.app/docs/datos/trazas/) y [experiencia de usuarios](https://lymen.app/docs/datos/experiencia-usuarios/) - [Explorar](https://lymen.app/docs/datos/explorar/) y [el lenguaje de consultas](https://lymen.app/docs/datos/lql/) - Configuración de datos: [Procesamiento](https://lymen.app/docs/datos/procesamiento/), [Muestreo](https://lymen.app/docs/datos/muestreo/), [Almacenamiento](https://lymen.app/docs/datos/almacenamiento/), [Reglas de captura](https://lymen.app/docs/datos/captura/), [Privacidad](https://lymen.app/docs/datos/privacidad/) y [Etiquetas](https://lymen.app/docs/datos/etiquetas/) ## 3. Operación Todo lo que pasa cuando algo falla: detectarlo, avisar, automatizar y ayudar. | Tema | Qué resuelve | |---|---| | [Incidentes](https://lymen.app/docs/operacion/incidentes/) | Ver qué está roto, a quién afecta, a quién se avisó; cerrarlo y dejar notas. | | [Reglas de alerta](https://lymen.app/docs/operacion/reglas-de-alerta/) | "Avisame si los errores pasan de X durante Y minutos". | | [Anomalías](https://lymen.app/docs/operacion/anomalias/) | Que Lymen aprenda lo normal y avise cuando algo se sale. | | [Perfiles de alerta](https://lymen.app/docs/operacion/perfiles-de-alerta/) | Qué incidentes le importan a cada persona, cuándo y por dónde. | | [Contactos](https://lymen.app/docs/operacion/contactos/) | La agenda de personas a las que se avisa. | | [Mantenimiento](https://lymen.app/docs/operacion/mantenimiento/) | Silenciar avisos mientras trabajás en un servicio. | | [Objetivos (SLO)](https://lymen.app/docs/operacion/objetivos-slo/) | Promesas medibles y presupuesto de error. | | [Chequeos sintéticos e internos](https://lymen.app/docs/operacion/chequeos-sinteticos/) | Visitas automáticas a tu sitio o a tu red para saber si responden. | | [Automatizaciones](https://lymen.app/docs/operacion/automatizaciones/) | Plantillas listas: chequeos, reporte semanal, pedidos de soporte. | | [Flujos](https://lymen.app/docs/operacion/flujos/) | Cadenas de pasos a tu medida: consultar, decidir, esperar, avisar. | | [Integraciones](https://lymen.app/docs/operacion/integraciones/) | Email, Telegram, Slack, Teams, webhook y Jira. | | [Llavero](https://lymen.app/docs/operacion/llavero/) | Dónde se guardan, cifradas, claves y tokens. | | [Usuarios y roles](https://lymen.app/docs/operacion/usuarios-y-roles/) | Qué ve y qué puede hacer cada rol. | | [Soporte](https://lymen.app/docs/operacion/soporte/) | Cómo pedir ayuda desde el portal. | ### Un recorrido típico de operación 1. Cargá a las personas en [Contactos](https://lymen.app/docs/operacion/contactos/). 2. Conectá por dónde querés enterarte en [Integraciones](https://lymen.app/docs/operacion/integraciones/) (guardando los secretos en el [Llavero](https://lymen.app/docs/operacion/llavero/)). 3. Armá [Perfiles de alerta](https://lymen.app/docs/operacion/perfiles-de-alerta/): quién recibe qué. 4. Definí qué vigilar con [Reglas](https://lymen.app/docs/operacion/reglas-de-alerta/) y [Anomalías](https://lymen.app/docs/operacion/anomalias/). 5. Anotá tus promesas en [Objetivos (SLO)](https://lymen.app/docs/operacion/objetivos-slo/). 6. Antes de un trabajo planificado, usá [Mantenimiento](https://lymen.app/docs/operacion/mantenimiento/). 7. Cuando algo falla, entrá a [Incidentes](https://lymen.app/docs/operacion/incidentes/). ## Un aviso sobre las integraciones Las integraciones de avisos (Telegram, Slack, Teams, webhook, Jira) están construidas según la documentación de cada servicio, pero todavía no se probaron con cuentas reales de cada proveedor. Probalas siempre con el botón **Probar** antes de depender de ellas. ## Roles Lymen tiene tres roles: **Administración**, **Sistemas** y **Negocio**. Cada pantalla indica quién puede qué. El detalle completo está en [Usuarios y roles](https://lymen.app/docs/operacion/usuarios-y-roles/). --- # Primeros pasos ## Para qué sirve Lymen te muestra, en un solo portal, cómo andan tus sistemas: los servidores, las aplicaciones, los sitios web y apps que usan tus pacientes o clientes, y los equipos de red (switches, routers, firewalls). Cuando algo se rompe o se pone lento, lo ves ahí, con el contexto para entender por qué. No hace falta un equipo de especialistas para ponerlo en marcha. Alcanza con instalar un programa chico (el **agente**) en tus servidores y pegar un código en tus sitios y apps. ## Cuándo usar esta sección Usala si es tu primer día con Lymen o si vas a sumar algo nuevo para medir: un servidor, un sitio, una app o un switch. Cada tema tiene su página con el paso a paso. ## Las direcciones de tu cuenta Cuando contratás Lymen te pasamos el nombre de tu cuenta (por ejemplo `clinica-x`). Con ese nombre se arman las dos direcciones que vas a usar: | Para qué | Dirección | Ejemplo | |---|---|---| | Entrar al portal | `https://.lymen.app` | `https://clinica-x.lymen.app` | | Mandar datos (agente, SDK, gateways) | `-ingesta.lymen.app` | `clinica-x-ingesta.lymen.app` | En esta documentación, donde dice `` poné el nombre de la tuya. Los comandos que arma el portal ya vienen con tus direcciones. Los paquetes del agente se publican en `https://paquetes.lymen.app/agente/`; el instalador los baja solo. ## Qué datos junta Lymen | Qué querés mirar | Cómo se conecta | Dónde se ve | |---|---|---| | Servidores (Linux o Windows) | Instalás el agente con una línea | Infraestructura | | Aplicaciones que corren en esos servidores | Se activa desde el portal, sin tocar su código | Servicios, Trazas, Topología | | Sitios web y apps móviles | Pegás un código (SDK) en el sitio o la app | Aplicaciones | | Switches, routers, firewalls y puntos de acceso | Un servidor de tu red los consulta (gateway) | Equipos de red | | Servidores sin salida a internet | Salen a través de otro servidor de tu red (gateway) | Infraestructura | ## Un recorrido por el portal El menú lateral tiene estos grupos: - **Resumen, Dashboards e Incidentes**: lo primero que ve cualquier persona al entrar. - **Observar**: Servicios, Topología (el mapa de cómo se conecta todo), Aplicaciones (sitios y apps), Infraestructura (servidores), Equipos de red y Explorar (consultas libres y trazas). - **Cumplimiento**: Objetivos (SLO) y Negocio. - **Alertas**: Reglas, A quién avisar y Mantenimiento. - **Automatizar**: Flujos. - **Configuración**: - *Datos*: Procesamiento, Muestreo, Almacenamiento, Reglas de captura, Privacidad y Etiquetas. - *Conexiones*: **Agregar datos**, Integraciones y Llavero. La pantalla que más vas a usar al principio es **Configuración › Conexiones › Agregar datos**: desde ahí das de alta servidores, gateways, equipos de red y grupos. Los sitios y apps tienen su propio paso a paso en **Aplicaciones**. ## Qué ve cada rol | Rol | Qué puede hacer | |---|---| | **Administración** | Todo. Es el único rol que da de alta servidores, gateways, equipos de red y aplicaciones, cambia la política de actualización y entra a la sección Configuración. | | **Sistemas** | Mira todo lo técnico (Servicios, Topología, Aplicaciones, Infraestructura, Equipos de red, Explorar, Reglas, A quién avisar, Mantenimiento). Puede ver el detalle de un servidor, pero no cambiarlo. No ve Configuración ni Flujos. | | **Negocio** | Ve Resumen, Dashboards, Incidentes y Objetivos (SLO). No ve las pantallas técnicas ni la configuración. | > Si la persona que instala no es administradora, pedile a quien administre tu cuenta que genere el comando de instalación. ## Por dónde empezar Seguí este orden. Cada paso se habilita cuando terminó el anterior (el portal te lo va marcando en un aviso arriba de Agregar datos): 1. **Instalá el agente en tu primer servidor.** Es una sola línea en la consola. Mirá [Agregar datos](https://lymen.app/docs/instalacion/agregar-datos/) y después [Linux](https://lymen.app/docs/instalacion/agente-linux/) o [Windows](https://lymen.app/docs/instalacion/agente-windows/). 2. **Revisá que aparezca en Infraestructura.** En uno o dos minutos el servidor figura como *Conectado*. Más en [Servidores e Infraestructura](https://lymen.app/docs/instalacion/servidores-infraestructura/). 3. **Si tenés servidores sin salida a internet o equipos de red, creá un [gateway](https://lymen.app/docs/instalacion/gateways/).** Es uno de tus servidores que reenvía los datos de los demás. 4. **Sumá tus [equipos de red](https://lymen.app/docs/instalacion/equipos-de-red/)**, uno por uno o buscándolos en un rango. 5. **Medí tus sitios y apps** desde [Aplicaciones](https://lymen.app/docs/instalacion/aplicaciones/), con el SDK que corresponda: [web](https://lymen.app/docs/instalacion/sdk-web/), [Android](https://lymen.app/docs/instalacion/sdk-android/), [iOS](https://lymen.app/docs/instalacion/sdk-ios/) o [React Native](https://lymen.app/docs/instalacion/sdk-react-native/). 6. **Activá el monitoreo en detalle de tus aplicaciones** (opcional): [Instrumentación de aplicaciones](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/). 7. Si tenés muchos servidores, armá [grupos](https://lymen.app/docs/instalacion/grupos-y-actualizacion/) para actualizarlos ordenadamente. ## Qué pasa con tus datos al empezar - **Se guarda todo al principio.** Un cliente nuevo arranca guardando el 100 % de las trazas (los recorridos de cada pedido por tus sistemas). Si más adelante querés guardar menos para gastar menos, lo cambiás en Muestreo. - **La privacidad está activa desde el inicio.** Las reglas de Privacidad se aplican en el servidor o en el dispositivo antes de que el dato salga, y otra vez al recibirlo. Nunca se captura lo que las personas escriben en formularios y no se graban sesiones. - **Las claves no viajan en claro.** El token de cada servidor queda en un archivo que solo puede leer el administrador del equipo. ## Problemas comunes | Síntoma | Qué revisar | |---|---| | No veo "Agregar datos" en el menú | Esa pantalla es solo para el rol Administración. | | Instalé el agente y no aparece | Esperá 1-2 minutos. Si sigue sin aparecer, mirá [Linux](https://lymen.app/docs/instalacion/agente-linux/#problemas-comunes) o [Windows](https://lymen.app/docs/instalacion/agente-windows/#problemas-comunes). | | No sé qué servidor es cuál | Usá el nombre del servidor (es el que informa el propio equipo) y los [grupos](https://lymen.app/docs/instalacion/grupos-y-actualizacion/) para ordenarlos. | --- # Agregar datos ## Para qué sirve **Configuración › Conexiones › Agregar datos** es el punto de partida para conectar tu infraestructura a Lymen. Reúne en tarjetas los pasos para dar de alta servidores, gateways, equipos de red y grupos. Es una pantalla solo para el rol Administración. Mirar y administrar lo que ya conectaste se hace en **Infraestructura** y en **Equipos de red**; esta pantalla es para el alta. ## Cuándo usarla - Vas a conectar un servidor nuevo. - Necesitás un comando de instalación nuevo (los códigos vencen). - Querés crear un grupo, revisar tus gateways o ver qué rangos de red aprobaste. ## Cómo se usa Arriba aparece un aviso con **lo que conviene hacer ahora**, según lo que ya tengas: | Si todavía no tenés... | El aviso dice | |---|---| | Servidores | "Empezá por instalar el agente en tu primer servidor" | | Gateways | "Para sumar switches y routers, creá un gateway" | | Equipos de red | "Todo listo para sumar equipos de red" | Después hay cuatro tarjetas: ### Paso 1: Servidores Máquinas físicas o virtuales donde corre el agente. El estado muestra cuántos están *conectados*. 1. Tocá **Agregar servidor**. 2. (Opcional) Elegí gateways y un grupo. Mirá la tabla de campos más abajo. 3. Tocá **Generar comando**. 4. Copiá el comando de la pestaña **Linux** o **Windows** con el botón **Copiar**. 5. Pegalo en una consola del servidor con permisos de administrador. Los detalles están en [Linux](https://lymen.app/docs/instalacion/agente-linux/) y [Windows](https://lymen.app/docs/instalacion/agente-windows/). 6. Dejá abierta la ventana: cuando el servidor se conecta, aparece "Servidor conectado: nombre". El código del comando **vale una sola vez, vence a las 24 horas y no se vuelve a mostrar**. Si lo perdés, generá otro. Si generaste comandos que nadie usó, aparece el botón **N códigos sin usar**. Ahí ves quién lo generó y cuándo vence, y podés **Anular** cada uno. Anulá los que ya no necesites: un código vigente es una llave para dar de alta un servidor. ### Paso 2: Gateways Un gateway es un servidor de tu red, con salida a internet, que reenvía los datos de los demás. Se habilita cuando ya tenés al menos un servidor. Para crear uno, abrí el servidor en Infraestructura y activá **Gateway de la red** (ver [Gateways](https://lymen.app/docs/instalacion/gateways/)). Esta tarjeta solo los lista: dirección, si está *Conectado*, si el enlace está cifrado y si tiene *Sin salida directa*. ### Paso 3: Equipos de red Switches, routers, firewalls y puntos de acceso, consultados por un gateway. Está bloqueada hasta que existe un gateway. Tiene tres acciones: **Agregar equipo**, **Buscar en un rango** y **Qué aprobaste** (los rangos que el gateway permite). Ver [Equipos de red](https://lymen.app/docs/instalacion/equipos-de-red/). ### Opcional: Grupos de servidores Reúnen servidores con la misma política de actualización. Cada servidor está en un solo grupo. Ver [Grupos y actualización](https://lymen.app/docs/instalacion/grupos-y-actualizacion/). ### Aparte: Sitios web y apps Se miden desde **Aplicaciones**, con su propio paso a paso. Ver [Aplicaciones](https://lymen.app/docs/instalacion/aplicaciones/). ## Campos del diálogo "Agregar servidor" | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | **Gateways (opcional)** | Lista ordenada de gateways por donde sale este servidor. | Vacía: el servidor sale directo a Lymen. | Hasta 5, solo gateways ya existentes. El primero es el preferido; los demás, de repuesto. | Con gateways, el servidor **no necesita salida a internet**: instala y manda todo por el primero que responda. Si ponés uno que se apaga seguido, el servidor queda dependiendo de los otros. Un servidor que solo llega por gateways no puede quedarse sin el último. | | **Sin cifrar (no recomendado)** | Habla con los gateways por http en vez de https. | Apagado (todo va cifrado, con el certificado de cada gateway fijado). | Encendido / apagado. Solo aparece si elegiste gateways. | **Seguridad.** Encendido, la clave del servidor y sus datos viajan en claro por tu red hasta el gateway. Usalo solo si el gateway no puede tener certificado. Queda un aviso en el servidor y hay que reinstalar para cifrar. | | **Grupo (opcional)** | Asigna el servidor a un grupo al instalarlo. Queda en el comando como `--grupo`. | Sin grupo. | Un grupo existente, "Sin grupo" o "Grupo nuevo…". | El grupo decide la política de actualización y sirve de etiqueta `grupo` en filtros, reglas y Dashboards. Un grupo equivocado se corrige después desde el detalle del servidor. | | **Nombre del grupo nuevo** | Crea el grupo en el momento. | — | Hasta 60 caracteres, sin comas, comillas, barra invertida, `$` ni acento grave. | Mismo impacto que el grupo. El tope es de 100 grupos. | Si elegís un gateway que todavía no publicó su certificado, el botón **Generar comando** queda deshabilitado: el certificado se publica solo, un minuto después de que el gateway arranca. Podés esperar o tildar *Sin cifrar* (no recomendado). ## Ejemplo El comando que genera el portal para Linux tiene esta forma (el código y la dirección son de ejemplo): ```sh curl -fsSL https://-ingesta.lymen.app/agente/instalar.sh \ | sudo LYMEN_ENROLAR= LYMEN_INGESTA=-ingesta.lymen.app sh -s -- --grupo produccion ``` ## Problemas comunes | Síntoma | Causa probable | Qué hacer | |---|---|---| | "El código no es válido, ya se usó o venció" | Pasaron más de 24 horas, o el código ya se usó en otro servidor. | Generá un código nuevo. | | El servidor no se conecta | El código se gastó pero algo falló después (descarga, permisos). | Quitá ese servidor en Infraestructura y generá un código nuevo. | | "Demasiados intentos" | Se probó muchas veces seguidas. | Esperá un minuto. | | Un gateway no deja generar el comando | Todavía no publicó su certificado. | Esperá un minuto después de que arranque el gateway. | | La tarjeta de Equipos de red dice "Bloqueado" | No hay ningún gateway. | Creá uno primero ([Gateways](https://lymen.app/docs/instalacion/gateways/)). | --- # Instalar el agente en Linux ## Para qué sirve El agente es un programa chico que corre en tu servidor y le manda a Lymen sus métricas (uso de CPU, memoria, disco y red), los logs del sistema y los datos de las aplicaciones. Lo ves en **Infraestructura**. Se instala con una sola línea. ## Requisitos - Linux con **systemd**, arquitectura amd64 (x86_64) o arm64 (aarch64). - Pensado para Ubuntu 22.04 y 24.04, Debian 12 y RHEL 9. - Permisos de administrador (`sudo`). - Los comandos `curl`, `tar`, `sha256sum`, `mktemp`, `sed`, `uname` y `useradd`. - Salida a internet hacia Lymen **o** un [gateway](https://lymen.app/docs/instalacion/gateways/) de tu red que sí la tenga. - El paquete de monitoreo en detalle de aplicaciones es solo para sistemas con **glibc**: en Alpine (musl) no se instala. > El instalador de Linux se probó en un contenedor con un `systemctl` simulado. No se probó todavía en un servidor real: hacé la primera instalación en un equipo no crítico. ## Cuándo usarlo Cada vez que quieras sumar un servidor Linux a Lymen. Para Windows, mirá [Instalar el agente en Windows](https://lymen.app/docs/instalacion/agente-windows/). ## Paso a paso 1. En el portal, andá a **Agregar datos › Agregar servidor** (ver [Agregar datos](https://lymen.app/docs/instalacion/agregar-datos/)). 2. Elegí, si corresponde, gateways y grupo, y tocá **Generar comando**. 3. Copiá el comando de la pestaña **Linux**. 4. (Recomendado) Antes de instalar, agregale `--verificar` para comprobar el servidor y las opciones sin registrar nada. No hace falta ser root. 5. Pegalo en una consola del servidor. Tarda un minuto. 6. Mirá **Infraestructura**: en 1-2 minutos el servidor aparece como *Conectado*. ### Verificar sin instalar ```sh curl -fsSL https://-ingesta.lymen.app/agente/instalar.sh \ | LYMEN_INGESTA=-ingesta.lymen.app sh -s -- --verificar --gateway 10.0.0.5:4390 ``` Muestra el servidor, la arquitectura, el tipo de librería de C, el grupo y los gateways, y termina diciendo "no se registró ni se instaló nada". No gasta el código de un solo uso. ## Opciones del instalador Cada opción se puede pasar como argumento o como variable de entorno. El portal arma el comando completo: normalmente no las escribís a mano. | Opción | Variable de entorno | Para qué sirve | Por defecto | Valores válidos | Impacto | |---|---|---|---|---|---| | `--codigo X` | `LYMEN_ENROLAR` | Código de un solo uso que da de alta el servidor. | — (obligatorio, salvo con `--verificar`) | Letras, números, `_` y `-`. | Vence a las 24 horas y se gasta al usarlo. No lo compartas ni lo dejes en un historial de comandos compartido. | | `--ingesta X` | `LYMEN_INGESTA` | Dirección de Lymen a la que se conecta el servidor. | — (obligatorio) | Host o host:puerto, por ejemplo `-ingesta.lymen.app`. | Si está mal, el servidor no se registra. | | `--gateway X` | `LYMEN_GATEWAY` | Gateway por donde sale el servidor. Se repite para armar una lista en orden (por entorno, separados por coma). | Ninguno: sale directo. | Hasta 5, sin repetidos. Solo letras, números, `.`, `:`, `[`, `]` y `-`. | Con gateways, el servidor puede no tener salida a internet: instala y manda todo por el primero que responda y, si cae, pasa al siguiente. Si todos fallan, la instalación termina con error. | | `--gateway-huella G=H` | `LYMEN_GATEWAY_HUELLA` | Huella del certificado propio de un gateway (`gateway=sha256//`). Se repite. La reparte el portal en el comando. | Sin huella: se verifica con las autoridades de confianza del sistema. | `sha256//` + 44 caracteres base64, o 64 caracteres hexadecimales. | **Seguridad.** Con huella, el servidor solo acepta *ese* certificado: protege contra que alguien se haga pasar por el gateway. Copiá siempre el comando completo del portal. | | `--gateway-tls` | — | Habla con los gateways por https. | Activo. | — | Es el comportamiento normal. | | `--gateway-sin-tls` | `LYMEN_GATEWAY_SIN_TLS=si` | Habla con los gateways por http, **sin cifrar**. | Apagado. | `si`, `true` o `1` por entorno. | **Seguridad.** El token y los datos viajan en claro por tu red. Un aviso lo marca en el instalador y en el portal. Solo si el gateway no puede tener certificado. | | `--grupo X` | `LYMEN_GRUPO` | Grupo de servidores. | Sin grupo. | Un solo valor, hasta 60 caracteres, sin comas, comillas, barra invertida, `$` ni acento grave. | Si el grupo no existe, se crea. Define la política de actualización y la etiqueta `grupo` de filtros y reglas. | | `--verificar` | — | Revisa el servidor y las opciones y termina. | Apagado. | — | No registra ni instala nada; no gasta el código. | | — | `LYMEN_INSTRUMENTAR=si` | Además del agente, instala el paquete de monitoreo en detalle de aplicaciones. | `no` | `si` | Solo deja el programa instalado: **no toca ninguna aplicación** hasta que lo actives desde el portal. Ver [Instrumentación](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/). Si falla, el agente queda instalado igual. | Si pasás una opción que no existe, el instalador se detiene con "opción desconocida". ## Qué hace el instalador 1. **Revisa todo antes de gastar el código**: que seas root, los comandos necesarios, systemd, la arquitectura y las opciones. 2. **Registra el servidor**: canjea el código por una credencial propia de este servidor. Prueba primero llegar directo a Lymen; si no puede, usa el primer gateway de la lista que responda. 3. **Baja el paquete** de la versión publicada y comprueba su suma de verificación (SHA-256) antes de usarlo. Si no coincide, se corta. 4. **Escribe la configuración** en `/etc/lymen-agent`. El archivo con el token (`entorno`) queda legible solo por root. 5. **Crea el usuario** `lymen-agent` (sin shell ni carpeta personal) y el servicio `lymen-agent`. 6. **Arranca el servicio** y activa el actualizador automático y el inventario del servidor (procesos, servicios y conexiones). 7. Si el servidor es un gateway (tiene capa de gateway), crea la lista de chequeos internos permitidos y el archivo de equipos de red permitidos, vacíos. Ver [Gateways](https://lymen.app/docs/instalacion/gateways/) y [Equipos de red](https://lymen.app/docs/instalacion/equipos-de-red/). ### Dónde queda cada cosa | Qué | Dónde | |---|---| | Programa y versiones | `/opt/lymen-agent` (la versión vigente está en `actual`) | | Configuración | `/etc/lymen-agent` | | Cola de datos, claves del gateway y estado | `/var/lib/lymen-agent` | | Servicio | `lymen-agent` (unidad systemd) | ### Qué permisos tiene el servicio El agente corre como el usuario `lymen-agent`, con dos permisos extra de solo lectura para ver los dueños de los sockets y las métricas de procesos de otros usuarios. Tiene un tope de 512 MB de memoria. Puede leer el diario del sistema (se suma al grupo `systemd-journal` si existe). Si el servidor tiene nginx con la página `/nginx_status` en la propia máquina, el instalador lo detecta y activa sus métricas. ## Ejemplos Servidor común, directo a Lymen, en el grupo producción: ```sh curl -fsSL https://-ingesta.lymen.app/agente/instalar.sh \ | sudo LYMEN_ENROLAR= LYMEN_INGESTA=-ingesta.lymen.app sh -s -- --grupo produccion ``` Servidor sin salida a internet, que usa dos gateways en orden (el portal agrega las huellas): ```sh curl -fsSL https://-ingesta.lymen.app/agente/instalar.sh \ | sudo LYMEN_ENROLAR= LYMEN_INGESTA=-ingesta.lymen.app sh -s -- \ --gateway 10.0.0.5:4390 --gateway 10.0.1.5:4390 \ --gateway-huella 10.0.0.5:4390=sha256// --gateway-huella 10.0.1.5:4390=sha256// ``` Con monitoreo en detalle de aplicaciones: ```sh curl -fsSL https://-ingesta.lymen.app/agente/instalar.sh \ | sudo LYMEN_ENROLAR= LYMEN_INGESTA=-ingesta.lymen.app LYMEN_INSTRUMENTAR=si sh -s -- ``` ## Problemas comunes | Síntoma | Qué hacer | |---|---| | "hay que correrlo como root (sudo)" | Corré el comando con `sudo`. | | "este servidor no usa systemd" | El instalador solo soporta systemd. Pedí soporte para tu sistema. | | "falta el comando ..." | Instalá `curl`, `tar`, `sha256sum` y `useradd` (paquete `coreutils`/`shadow-utils`). | | "no se pudo llegar a Lymen" | El servidor no tiene salida a internet. Usá `--gateway` con un gateway de tu red. | | "no se pudo llegar a Lymen ni a ningún gateway" | Revisá que algún gateway esté encendido y alcanzable por su puerto desde este servidor. | | "el código no es válido, ya se usó o venció" | Generá un código nuevo en el portal. | | "el paquete bajado no coincide con el publicado" | La descarga se cortó o fue alterada. Quitá el servidor en el portal y reinstalá con un código nuevo. | | Instalado, pero no aparece en el portal | Esperá 2 minutos. Después mirá `systemctl status lymen-agent` y `journalctl -u lymen-agent`. | | El servidor figura con otro nombre | El nombre es el que informa el propio equipo (`uname -n`). Cambialo en el sistema y reinstalá. | Para sacar el agente, mirá [Desinstalar](https://lymen.app/docs/instalacion/desinstalar/). --- # Instalar el agente en Windows ## Para qué sirve Hace lo mismo que en Linux: el agente corre como un servicio de Windows y le manda a Lymen las métricas del servidor (CPU, memoria, disco, red), el registro de eventos de Windows y los datos de tus aplicaciones. Lo ves en **Infraestructura**. > **Importante:** el instalador de Windows se probó solo hasta la lectura de opciones, la revisión previa y el registro del servidor. La parte que **crea el servicio no se probó todavía en un Windows real**. Hacé la primera instalación en un servidor de prueba y avisanos cómo te fue. ## Requisitos - Windows de 64 bits (amd64). Pensado para Windows Server 2022. - **PowerShell abierto como administrador.** - Salida a internet hacia Lymen **o** un [gateway](https://lymen.app/docs/instalacion/gateways/) de tu red que sí la tenga. ## Paso a paso 1. En el portal, andá a **Agregar datos › Agregar servidor** y generá el comando (ver [Agregar datos](https://lymen.app/docs/instalacion/agregar-datos/)). 2. Elegí la pestaña **Windows** y copialo. 3. Abrí **PowerShell como administrador** en el servidor y pegalo. 4. En 1-2 minutos el servidor aparece *Conectado* en **Infraestructura**. El comando tiene esta forma (el código y la dirección son de ejemplo): ```powershell $env:LYMEN_ENROLAR=''; $env:LYMEN_INGESTA='-ingesta.lymen.app'; & ([scriptblock]::Create((iwr -useb https://-ingesta.lymen.app/agente/instalar.ps1).Content)) --grupo produccion ``` Para comprobar el servidor y las opciones sin instalar nada, agregá `--verificar` al final. No gasta el código. ## Opciones del instalador Son las mismas que en Linux, con las mismas validaciones. La única diferencia es el formato de la huella del gateway. | Opción | Variable de entorno | Para qué sirve | Por defecto | Valores válidos | Impacto | |---|---|---|---|---|---| | `--codigo X` | `LYMEN_ENROLAR` | Código de un solo uso. | — (obligatorio, salvo `--verificar`) | Letras, números, `_` y `-`. | Vence a las 24 horas y se gasta al usarlo. | | `--ingesta X` | `LYMEN_INGESTA` | Dirección de Lymen. | — (obligatorio) | Host o host:puerto. | Si está mal, no se registra. | | `--gateway X` | `LYMEN_GATEWAY` | Gateway por donde sale. Repetible y en orden (por entorno, separados por coma). | Ninguno: sale directo. | Hasta 5, sin repetidos. | Permite instalar un servidor sin salida a internet; si un gateway cae, usa el siguiente. | | `--gateway-huella G=H` | `LYMEN_GATEWAY_HUELLA` | Huella del certificado de un gateway. Repetible. La reparte el portal. | Sin huella: se valida con las autoridades de confianza de Windows. | `gateway=` + **64 caracteres hexadecimales** (SHA-256 del certificado). | **Seguridad.** Con huella solo se acepta ese certificado. En Windows se usa la huella del certificado, no la de la clave pública: copiá el comando de la pestaña Windows. | | `--gateway-tls` | — | Habla con los gateways por https. | Activo. | — | Comportamiento normal. | | `--gateway-sin-tls` | `LYMEN_GATEWAY_SIN_TLS=si` | Habla con los gateways por http, **sin cifrar**. | Apagado. | `si`, `true` o `1` por entorno. | **Seguridad.** El token y los datos viajan en claro por tu red. | | `--grupo X` | `LYMEN_GRUPO` | Grupo de servidores. | Sin grupo. | Hasta 60 caracteres, sin comas, comillas, barra invertida, `$` ni acento grave. | Define la política de actualización y la etiqueta `grupo`. Si no existe, se crea. | | `--verificar` | — | Revisa y termina. | Apagado. | — | No registra ni instala. | | — | `LYMEN_INSTRUMENTAR=si` | Instala además el paquete de monitoreo en detalle de aplicaciones. | `no` | `si` | No toca ninguna aplicación hasta que lo actives en el portal. Ver [Instrumentación](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/). | ## Qué hace el instalador 1. Revisa el servidor y las opciones (y que PowerShell esté como administrador). 2. Registra el servidor con el código. Prueba directo a Lymen y, si no hay salida, por el primer gateway que responda. 3. Baja el paquete de la versión publicada y comprueba su suma de verificación (SHA-256). 4. Deja el programa en `C:\Program Files\lymen-agent` y la configuración y los datos en `C:\ProgramData\lymen-agent`. Esa carpeta de datos la pueden leer solo SYSTEM y los Administradores. 5. Guarda el token en las variables del **servicio** (no de la máquina), así ningún otro proceso lo hereda. 6. Crea el servicio **Agente de Lymen** (`lymen-agent`), de inicio automático, que corre como SYSTEM. Si se cae, Windows lo reinicia a los 5 segundos, a los 5 y a los 60. 7. Crea una tarea programada (`lymen-agent-actualizar`) que cada hora pregunta si le toca actualizarse. Ver [Grupos y actualización](https://lymen.app/docs/instalacion/grupos-y-actualizacion/). 8. Si el servidor es gateway, crea en `C:\ProgramData\lymen-agent\permitidos` la lista de chequeos internos permitidos, vacía. Solo los Administradores pueden modificarla. Ver [Gateways](https://lymen.app/docs/instalacion/gateways/). ## Lo que el instalador de Windows no incluye - **Monitoreo de equipos de red** (SNMP, trampas, syslog, ping): hoy lo instala solo el instalador de Linux. Para monitorear [equipos de red](https://lymen.app/docs/instalacion/equipos-de-red/) necesitás un gateway en Linux. - El inventario de procesos, servicios y conexiones del servidor, que sí se instala en Linux. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | "abri PowerShell como administrador" | Cerrá la consola y abrila con clic derecho › Ejecutar como administrador. | | El comando falla al bajar el script | Revisá la salida a internet o usá `--gateway`. El instalador fuerza TLS 1.2. | | "el código no es válido, ya se usó o venció" | Generá un código nuevo en el portal. | | "huella no válida" | Pegaste una huella con formato de Linux. Generá el comando de la pestaña Windows. | | Instalado, pero no aparece | Esperá 2 minutos y revisá en `services.msc` que **Agente de Lymen** esté *En ejecución*. | Para sacar el agente, mirá [Desinstalar](https://lymen.app/docs/instalacion/desinstalar/). --- # Servidores e Infraestructura ## Para qué sirve **Observar › Infraestructura** es la lista de todos tus servidores: cuáles están conectados, cómo andan de CPU, memoria y disco, y qué versión del agente tienen. Al abrir uno ves su detalle y lo administrás: gateway, grupo, actualización y reinicio del agente. ## Cuándo usarlo - Después de instalar el agente, para confirmar que el servidor se conectó. - Para saber qué servidor está al límite de recursos. - Para activar un servidor como gateway, cambiarle el grupo o la política de actualización, o quitarlo. ## La lista Cada servidor muestra el estado de su agente y su salud: | Estado del agente | Qué significa | |---|---| | **Esperando conexión** | Se generó el alta pero el agente todavía no se conectó. | | **Conectado** | El agente está reportando. | | **Sin conexión** | Estuvo conectado, pero hoy no reporta (apagado, sin red o con el servicio detenido). | | **Quitado** | Alguien lo quitó desde el portal. | La salud usa el uso de recursos (CPU, memoria, disco): | Salud | Cuándo | |---|---| | **Funciona bien** | Hasta 75 % de uso. | | **Cerca del límite** | Más de 75 %. | | **Al límite** | Más de 90 %. | | **Sin datos** | El servidor dejó de mandar datos; se muestra desde cuándo. | La lista de agentes tiene estas columnas: **Servidor**, **Estado**, **Agente** (versión), **Último contacto**, **Rol** (si es gateway, o a qué gateway usa) y **Actualización**. Si hay una versión anticipada con política estable, aparece una marca roja. Si tu cuenta usa Kubernetes, hay una pestaña extra (ver [Kubernetes](https://lymen.app/docs/instalacion/kubernetes/)). ## El detalle de un servidor Se abre tocando el servidor. Tiene estas secciones: | Sección | Qué muestra o permite | |---|---| | **Datos** | Sistema, versión del agente, último contacto, fecha de alta y versión del sistema operativo. | | **Actualización del agente** | Cómo va la actualización y la política. Ver [Grupos y actualización](https://lymen.app/docs/instalacion/grupos-y-actualizacion/). | | **Agente** | El **Grupo** del servidor y el botón **Reiniciar el agente**. | | **Gateway de la red** | Interruptor para que este servidor sea gateway. Ver [Gateways](https://lymen.app/docs/instalacion/gateways/). | | **Gateways que usa** | La lista ordenada por donde sale y **Por dónde sale** (el gateway que está usando ahora). | | **Inventario** | Procesos, servicios y conexiones del servidor. La línea de comando de cada proceso se enmascara para no mostrar claves. Tiene topes: 150 grupos de procesos, 150 servicios y 300 conexiones agregadas. | | **Monitoreo en detalle de aplicaciones** | Aplicaciones del servidor que podés medir por dentro. Ver [Instrumentación](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/). | | **Qué se captura de los pedidos** | Cabeceras, parámetros y cuerpos que se guardan. Ver [Instrumentación](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/). | | **Historial** | Quién cambió qué y cuándo: alta, gateway, grupo, política, actualizaciones, reinicios. | Solo el rol Administración puede cambiar algo; Sistemas lo ve en modo lectura. ### Reiniciar el agente El botón **Reiniciar el agente** reinicia solo el agente del servidor; el servidor y sus aplicaciones no se tocan. No se pierden datos: lo que no pudo mandar, lo reintenta. Si no está disponible, el portal explica por qué al lado del botón. Cuando ya lo pediste, dice **Reinicio pedido** y el agente lo toma en unos segundos. ### Quitar un servidor **Quitar servidor** revoca la identidad del agente: deja de poder mandar datos y **no se puede deshacer**. Para volver a conectarlo hay que reinstalar el agente con un código nuevo. Si otros servidores lo usan como gateway, el portal te avisa y los saca de su lista. Esto no desinstala el programa del equipo: para eso mirá [Desinstalar](https://lymen.app/docs/instalacion/desinstalar/). ## Campos que se guardan con la barra de la pantalla La barra inferior muestra la leyenda de lo que falta, **Cancelar** y **Guardar**. Guardar queda deshabilitado mientras haya un campo inválido. | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | **Este servidor es gateway** | Convierte al servidor en gateway de otros. | Apagado | Encendido / apagado | Los servidores que lo usen dependen de él: si se apaga, pierden su salida. No se puede apagar mientras otros lo usan. | | **Dirección dentro de tu red** | Dirección que usan los otros servidores para llegar a este gateway. | — | `host` o `host:puerto`, hasta 260 caracteres. Sin puerto, se usa el 4390. | Si está mal, los servidores no lo alcanzan. | | **Gateways que usa** | Lista ordenada de gateways de este servidor. | Vacía: sale directo | Hasta 5 | Cambia por dónde salen sus datos. Un servidor sin salida directa no puede quedarse sin el último. | | **Grupo** | Grupo del servidor. | Sin grupo | Un grupo existente | Cambia la política de actualización que hereda y la etiqueta `grupo` de filtros y reglas. | | Política de actualización | Ver [Grupos y actualización](https://lymen.app/docs/instalacion/grupos-y-actualizacion/). | Hereda | — | Cambia cuándo y a qué versión se actualiza. | ## Problemas comunes | Síntoma | Qué hacer | |---|---| | Un servidor figura *Sin conexión* | Revisá que el servicio del agente esté corriendo y que el servidor tenga salida (o su gateway esté encendido). | | "Todavía no confirmó que esté enviando por el gateway" | El servidor está apagado o tiene una versión vieja del agente. Esperá unos minutos o actualizalo. | | "Lo usa N servidores: cambiales el gateway primero" | Antes de apagar un gateway, sacalo de la lista de los servidores que lo usan. | | "Solo puede ser gateway un servidor conectado y con salida a Lymen" | El servidor tiene que estar *Conectado* y llegar directo a Lymen. | | "Una cadena de gateways puede tener hasta 5 saltos" / ciclo de gateways | Rearmá las listas para que no formen un círculo ni pasen de 5 gateways encadenados. | --- # Gateways ## Para qué sirve Un **gateway** es un servidor de tu red, con salida a internet, que recibe los datos de otros servidores y los reenvía a Lymen. No hace falta comprar nada: cualquier servidor que ya tenga el agente instalado y llegue a Lymen puede cumplir ese rol. Un gateway sirve para tres cosas: 1. **Servidores sin salida a internet.** Se instalan, se administran y mandan sus datos a través del gateway. 2. **Equipos de red.** Los switches, routers y firewalls los consulta un gateway desde adentro de tu red. Ver [Equipos de red](https://lymen.app/docs/instalacion/equipos-de-red/). 3. **Chequeos internos.** Pruebas a servicios que solo se ven desde tu red (una página de intranet, un puerto de base de datos). ## Cuándo usarlo | Situación | ¿Gateway? | |---|---| | Todos tus servidores tienen salida a internet y no tenés equipos de red | No hace falta. | | Hay servidores en una red aislada (sin internet) | Sí. | | Querés monitorear switches, routers o firewalls | Sí, hace falta al menos uno. | | Querés reducir las conexiones que salen de tu red | Opcional: salen solo desde el gateway. | | Querés credenciales (de un switch, por ejemplo) que Lymen no pueda leer | Sí: se sellan para ese gateway. | ## Cómo se crea uno 1. Instalá el agente en un servidor que llegue a Lymen ([Linux](https://lymen.app/docs/instalacion/agente-linux/) o [Windows](https://lymen.app/docs/instalacion/agente-windows/)). 2. En **Infraestructura**, abrí ese servidor. 3. En la sección **Gateway de la red**, activá **Este servidor es gateway**. 4. Escribí la **dirección dentro de tu red** que van a usar los otros servidores, por ejemplo `10.0.0.5:4390`. Si no ponés puerto, se usa el **4390**. 5. Tocá **Guardar**. 6. Abrí el puerto en el firewall del gateway, desde los servidores que lo van a usar. 7. Esperá un minuto: el gateway publica su certificado y pasa a mostrarse como **Enlace cifrado** en Agregar datos. Solo puede ser gateway un servidor *Conectado* y con salida directa a Lymen. Para dejar de serlo, antes tenés que sacarlo de la lista de cada servidor que lo usa. ### Estado de un gateway En **Agregar datos › Gateways** cada gateway muestra: | Etiqueta | Significado | |---|---| | **Conectado / Sin conexión** | Si hoy responde. | | **Enlace cifrado** | Ya publicó su certificado: se puede generar un comando cifrado. | | **Sin certificado todavía** | Se publica solo, un minuto después de que el gateway arranca. | | **Sin salida directa** | Este gateway, a su vez, llega a Lymen a través de otro gateway. | ## Listas de gateways Cada servidor puede tener una **lista ordenada** de hasta **5 gateways**: - El primero es el **preferido**. Los demás son de repuesto. - Si uno no responde, el servidor pasa al siguiente. Cuando el preferido vuelve, regresa a él. - Podés **Subir**, **Bajar**, **Sacar** y **Agregar un gateway** desde el detalle del servidor. - Los gateways se pueden **encadenar** (un gateway que sale por otro), hasta 5 saltos y sin ciclos. Sirve para redes segmentadas. - La sección **Por dónde sale** muestra por cuál gateway salen los datos ahora, si alguno no responde y cuántas veces cambió. - Un servidor **sin salida directa** a Lymen no puede quedarse sin su último gateway. Para quitarlos todos hay que reinstalar el agente desde una red con salida. El muestreo de trazas (cuántas guardás) lo ejecuta el **último gateway de la cadena**: si usás gateways, ahí se decide qué se descarta. Se configura en Muestreo. ## Cifrado (TLS) entre servidores y gateways Por defecto, el servidor habla con sus gateways por **https** y acepta **solo el certificado propio de cada gateway** (queda "fijado" con una huella). Eso evita que alguien en tu red se haga pasar por el gateway y vea el token o los datos. - El gateway genera su certificado la primera vez y lo renueva con la misma clave, así los servidores que lo tienen fijado no quedan afuera. - El portal pone la huella en el comando de instalación; por eso **conviene copiar siempre el comando completo**. - En Linux la huella es de la clave pública (`sha256//…`); en Windows, el SHA-256 del certificado. | Opción | Impacto | |---|---| | Cifrado (por defecto) | Lo recomendado. El gateway tiene que haber publicado su certificado antes de generar el comando. | | **Sin cifrar (no recomendado)** | El token del servidor y sus datos viajan en claro por tu red. Pensado solo para casos donde el gateway no puede tener certificado. El portal lo señala en el servidor, y para cifrar hay que reinstalar sin esa opción. | ## Lista permitida de chequeos internos Lymen puede pedirle a un gateway que pruebe un servicio de tu red (una URL o un puerto). Para que **nadie, ni siquiera Lymen, pueda mandar al gateway a probar cualquier cosa**, esa lista la definís vos en un archivo del propio gateway. Todo lo que no figura se rechaza. | Sistema | Archivo | |---|---| | Linux | `/etc/lymen-agent/gateway-permitidos.yaml` (dueño root) | | Windows | `C:\ProgramData\lymen-agent\permitidos\gateway-permitidos.yaml` (solo Administradores pueden modificarlo) | El archivo se lee en cada chequeo: **no hace falta reiniciar** nada. Si no existe, está vacío o tiene un error de formato (por ejemplo, un campo que no existe), **se rechaza todo**. ### Campos de cada entrada de `chequeos` | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto | |---|---|---|---|---| | `tipo` | Tipo de chequeo. | — (obligatorio) | `http` o `tcp` | Define qué otros campos se usan. | | `url` | (http) Dirección permitida. | — | `http://` o `https://`, sin usuario ni fragmento. Exacta, o con `*` al final para permitir cualquier ruta que empiece así. | Con `*` abrís todo un tramo del servidor: poné la ruta más específica posible. | | `metodos` | (http) Métodos permitidos. | `[GET]` | `GET`, `HEAD` | Solo se ejecutan GET y HEAD. Nunca se envía un cuerpo. | | `tls_inseguro` | (https) Acepta certificados propios o vencidos. | `false` | `true` / `false` | **Seguridad.** En `true` el chequeo no verifica con quién habla. Usalo solo para un servicio interno con certificado propio. | | `consulta` | (http) Permite que la URL lleve parámetros (`?a=b`). | `false` | `true` / `false` | Sin esto, una URL con parámetros se rechaza. | | `credenciales` | (http) Ids de credenciales del Llavero (alcance "Solo en tu red") que se pueden usar contra *esta* dirección. | Ninguna | Lista de ids | **Seguridad.** Sin la lista, no se usa ninguna credencial. Una credencial solo viaja a las direcciones que le habilitaste. | | `destino` | (tcp) Servidor y puerto a probar. | — | `host:puerto` | Solo comprueba que se pueda abrir la conexión; no manda datos. | Reglas fijas: tiempo máximo de 30 segundos por chequeo (10 si no se indica), no se siguen redirecciones y **nunca se devuelve el cuerpo de la respuesta**: Lymen solo recibe si anduvo, el código, cuánto tardó y los días que le quedan al certificado. ### Ejemplo ```yaml chequeos: - tipo: http url: http://intranet.local:8080/salud metodos: [GET] - tipo: http url: https://agenda.clinica.local/api/* tls_inseguro: true # certificado propio - tipo: tcp destino: 10.0.0.5:5432 ``` ## Problemas comunes | Síntoma | Qué hacer | |---|---| | Un chequeo vuelve "no está en la lista permitida de este gateway" | Agregá esa URL o ese destino al archivo. Revisá puerto y esquema (`http` y `https` son distintos). | | "este gateway no tiene lista permitida" | El archivo no existe o tiene un error de formato. Revisá la sangría y que los campos existan. | | Los servidores no llegan al gateway | Abrí el puerto (4390 por defecto) en el firewall del gateway y probá la dirección desde el servidor. | | "todavía no publicó su certificado" | Esperá un minuto desde que el gateway arrancó. | | "esa credencial no está permitida para esta dirección" | Agregá el id de la credencial en `credenciales` de esa entrada. | --- # Grupos de servidores y actualización del agente ## Para qué sirve El agente se **actualiza solo**, para que no tengas que entrar servidor por servidor. Esta página explica cómo controlar ese proceso y cómo usar **grupos** para tratar distinto a los servidores de producción, de pruebas o de cada sucursal. Un **grupo** reúne servidores con la misma política de actualización. Además funciona como la etiqueta `grupo` en filtros, reglas y Dashboards. ## Cuándo usarlo - Querés que producción se actualice de madrugada y pruebas apenas salga una versión nueva. - Querés frenar un servidor crítico en una versión que ya validaste. - Querés actualizar a mano, ahora, todo un conjunto de servidores. - Querés filtrar reglas o dashboards por sucursal o ambiente. ## Grupos Cada servidor está en **un solo grupo** (o en ninguno). Se asigna al instalar con `--grupo` o después, desde el detalle del servidor, en la sección **Agente › Grupo**. Los grupos se ven y administran en **Agregar datos › Grupos de servidores**. Cada fila muestra el nombre, la descripción, el resumen de su política y cuántos servidores tiene (cuántos *al día*, *por actualizar*, *actualizando* y *con problemas*). ### Campos de un grupo | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | **Nombre** | Identifica el grupo; también es el valor de la etiqueta `grupo`. | — (obligatorio) | Hasta 60 caracteres, sin comas, comillas, barra invertida, `$` ni acento grave. | Cambiarlo cambia la etiqueta que usan tus filtros y reglas: revisalos. Hasta 100 grupos. | | **Descripción (opcional)** | Para reconocerlo. | Vacía | Hasta 200 caracteres. | Ninguno. | | **Actualización de sus servidores** | La política del grupo. Ver más abajo. | Sin política propia: usa la de Lymen (se actualiza solo, canal estable). | — | Afecta a **todos** los servidores del grupo que no fijen su propia política. | Al **borrar** un grupo, sus servidores quedan sin grupo (pierden la etiqueta `grupo`) y conservan su política propia. No se actualiza ni se quita ningún servidor. ## La política de actualización Se define en el grupo o en un servidor puntual. Cada campo puede quedar en **"Igual que el grupo"** (o "Igual que Lymen", si es la política de un grupo). Se hereda campo por campo: servidor, después grupo, después la base de Lymen. | Campo | Para qué sirve | Por defecto (base de Lymen) | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | **Actualizar el agente solo** | Si el agente se actualiza sin que hagas nada. | Sí | *Igual que…*, *Sí, se actualiza solo*, *No, lo actualizo yo* | En *No*, el servidor se queda en su versión hasta que lo actualices a mano. Un agente viejo puede perder correcciones de seguridad y funciones nuevas. | | **Canal** | Qué versiones recibe. | Estable | *Estable*, *Anticipado* | *Estable* recibe versiones ya probadas. *Anticipado* recibe las nuevas antes: más novedades, más riesgo. Si un servidor tiene versión anticipada y su política es *estable*, el sistema le va a pedir que vuelva a la estable; el portal lo avisa. | | **Ventana de actualización** | Horario en el que se permite actualizar. | Todos los días de 01:00 a 05:00, en la hora de tu zona | *Igual que…* o *Una ventana propia*: **Desde**, **Hasta** (HH:MM) y **Días** | Fuera de la ventana, la actualización espera. La ventana no puede empezar y terminar a la misma hora y tiene que tener al menos un día. Si cruza medianoche (por ejemplo 22:00 a 04:00), funciona igual. | | **Versión fija** | Congela el agente en una versión. | Ninguna: sigue al canal | *Ninguna* o una versión disponible | El agente se queda (o vuelve) en esa versión y **no sigue al canal**. Útil para validar antes de actualizar; riesgoso si te olvidás de soltarla. | La política queda guardada recién cuando tocás **Guardar** en la barra de la pantalla. ### Cómo se actualiza: tandas y vuelta atrás Lymen no actualiza todo junto: 1. **Primera tanda chica**: el 10 % de los servidores, con un mínimo de 1 y un máximo de 5. Van primero los servidores que menos afectan si algo falla (los que no son gateway ni dependen de uno). 2. Si la primera tanda **vuelve sana**, sigue el resto. 3. Los **gateways se actualizan de a uno**, y antes que los servidores que dependen de ellos. 4. Si un agente **no vuelve sano en unos 10 minutos**, vuelve solo a la versión anterior y se **frena la versión**: no se instala sola en los demás hasta que haya una nueva. ### Estados que vas a ver | Estado | Qué significa | |---|---| | **Al día** | Tiene la última versión de su canal. | | **Versión fija** | Se queda en la versión que fijaste. | | **Actualización pendiente** | Le toca actualizarse; el motivo de la espera aparece abajo (esperando la ventana, otro gateway, etc.). | | **Espera su turno** | Espera a que la primera tanda salga bien. | | **Actualizando…** | En curso. Si no vuelve sano en unos minutos, vuelve solo. | | **Volvió a la versión anterior** | La nueva no funcionó en este servidor. No se reintenta sola. | | **Versión frenada** | La versión se frenó porque falló en otro servidor. | | **Sin versión para este sistema** | No hay un paquete publicado para ese sistema. | | **Actualización apagada** | La política tiene *No, lo actualizo yo*. | ## Acciones manuales | Acción | Dónde | Qué hace | Cuidado | |---|---|---|---| | **Actualizar ahora** | Detalle del servidor | Actualiza ya, sin esperar la ventana. Podés elegir la versión. | Saltea tu ventana: elegila con cuidado en servidores críticos. Si no vuelve sano, vuelve solo a la anterior. | | **Cancelar la actualización** | Detalle del servidor | Cancela una actualización pendiente o en espera. | Solo vale antes de que se entregue al servidor. | | **Volver a la versión X** | Detalle del servidor | Regresa a la versión anterior y **la deja fija**. | Para que vuelva a seguir al canal, sacá la versión fija. | | **Actualizar grupo** | Agregar datos › Grupos | Actualiza los servidores conectados y atrasados del grupo, por tandas. | Respeta el orden de gateways y se frena si algo falla. | ## Ejemplos - **Producción prudente**: grupo `produccion`, canal *Estable*, ventana propia domingos de 02:00 a 05:00. - **Pruebas adelantadas**: grupo `pruebas`, canal *Anticipado*, ventana todos los días. Si algo sale mal, pasa ahí primero. - **Servidor validado**: en el servidor, *Versión fija* en la versión que probaste. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | "Versión anticipada con política estable" | El servidor tiene una versión anticipada pero su política es estable. Pasalo al canal anticipado o fijá la versión para que se quede. | | La actualización no arranca | Mirá la línea de estado: puede estar esperando la ventana (el portal muestra cuándo abre) o a otro gateway. | | "Ya hay una actualización en curso" | Esperá a que termine o cancelala si todavía no se entregó. | | "La versión X se frenó" | Falló en otro servidor; esperá una versión nueva o actualizá a mano uno de prueba. | | El botón "Actualizar ahora" no aparece | El servidor ya tiene la versión que le toca, o hay una actualización en marcha. | --- # Kubernetes ## Para qué sirve Si tus aplicaciones corren en Kubernetes, no se usa el instalador de una línea de los servidores: se instala un **chart de Helm** que pone un agente en cada nodo del cluster. El agente junta las métricas del nodo, los logs de los contenedores y recibe los datos de tus aplicaciones. También puede activar el monitoreo en detalle de aplicaciones con una anotación en el pod, sin tocar su código. En **Infraestructura** aparece una pestaña **Kubernetes** con cada cluster: cantidad de nodos, pods en marcha y reinicios. ## Cuándo usarlo Solo si tenés un cluster de Kubernetes. Si tus aplicaciones corren en servidores comunes, usá [Linux](https://lymen.app/docs/instalacion/agente-linux/) o [Windows](https://lymen.app/docs/instalacion/agente-windows/). > **Qué se probó.** El chart se probó en un cluster de un solo nodo creado con kind, con una ingesta de prueba. **No se probó en un cluster de producción ni en servicios gestionados** (EKS, AKS, GKE). Hacé la primera instalación en un cluster de pruebas. ## Qué mide hoy (y qué no) | Sí | No (todavía) | |---|---| | Métricas del nodo (CPU, memoria, disco, red) | Métricas por pod o por contenedor | | Logs de los contenedores | Eventos del cluster (reinicios, desalojos) | | Datos de las aplicaciones que mandan al agente de su nodo | Reglas de Privacidad configurables desde el portal para el agente del nodo | | Monitoreo en detalle por anotación (Java, Node.js, Python, .NET) | | Los datos del pod (nombre, namespace, cluster) salen del nombre del archivo de log y de la instrumentación automática. ## Requisitos - Helm y acceso al cluster con `kubectl`. - Un **token** de tu cuenta de Lymen, guardado como Secret de Kubernetes con la clave `token`. - La dirección de ingesta de tu cuenta (`https://-ingesta.lymen.app`). - Un namespace con política de seguridad **`privileged`**, porque el agente lee el disco del nodo (logs y métricas del host). ## Paso a paso ```sh kubectl create ns lymen kubectl label ns lymen pod-security.kubernetes.io/enforce=privileged kubectl -n lymen create secret generic lymen-token --from-literal=token= helm dependency build chart/lymen helm install lymen chart/lymen -n lymen --wait \ --set ingesta.url=https://-ingesta.lymen.app \ --set ingesta.existingSecret=lymen-token \ --set cluster.nombre=produccion ``` El chart lo entrega Lymen. Para medir una aplicación en detalle, anotá su pod y reinicialo. Con `` igual a `java`, `nodejs`, `python` o `dotnet`: ```yaml metadata: annotations: instrumentation.opentelemetry.io/inject-: "lymen/lymen" ``` (La anotación es el estándar del operador que usa el chart: el valor es `namespace/nombre`.) ## Valores del chart | Valor | Para qué sirve | Por defecto | Impacto de cambiarlo | |---|---|---|---| | `ingesta.url` | Dirección de ingesta de tu cuenta. | — (obligatorio) | Si es incorrecta, no llega nada. | | `ingesta.existingSecret` | Secret ya existente con la clave `token`. | — | **Seguridad.** Es lo recomendado. | | `ingesta.token` | Token directo; el chart crea el Secret. | — | **Seguridad.** Queda guardado en el historial de Helm: preferí `existingSecret`. | | `cluster.nombre` | Nombre del cluster en el portal. | — | Es lo que ves en la pestaña Kubernetes y en los filtros. | | `cluster.entorno` | Entorno de los datos. | `produccion` | Etiqueta tus datos. | | `agente.resources` | Recursos por nodo. | Pide 50m de CPU y 128Mi; tope 500m y 384Mi | Bajar el tope puede cortar el agente en nodos con mucho log. | | `agente.limiteMemoriaMiB` | Límite blando de memoria del agente. | 256 | Tiene que ser menor que el tope del contenedor. | | `agente.tolerations` | En qué nodos corre. | Todos | Restringirlo deja nodos sin medir. | | `agente.recibirAplicaciones.servicioLocal` | Cada app entrega al agente de **su propio nodo**. | Sí | — | | `agente.recibirAplicaciones.hostPort` | Además abre el puerto en el nodo. | No | Pide una política de seguridad menos estricta. | | `agente.metricasNodo.enabled` / `.intervalo` | Métricas del nodo y cada cuánto. | Sí / 30 s | Un intervalo más corto guarda más datos (costo). | | `agente.logs.enabled` | Lee los logs de los contenedores. | Sí | **Privacidad y costo.** Apagarlo evita guardar logs; encenderlo puede traer datos personales a los logs de las apps. | | `agente.logs.excluirNamespaces` | Namespaces que no se leen. | `kube-system`, `kube-public`, `kube-node-lease` | Sacar uno de la lista suma ruido; sumar los que no te interesen reduce costo. | | `operador.enabled` | Instala el operador que instrumenta aplicaciones. | Sí | Apagado, la anotación no hace nada. | | `instrumentacion.muestreo` | Qué parte de las trazas de la instrumentación automática se guarda. | `"1"` (todo) | Menos trazas = menos costo, pero menos visibilidad. | | `gateway.administracion.enabled` | Enlace de administración con el portal. | Sí | Apagado, el portal no ve el estado de los agentes del cluster. | ## Cómo se actualiza y se desinstala Con `helm upgrade lymen chart/lymen -n lymen …` (los certificados del operador se conservan entre actualizaciones). Con `helm uninstall lymen -n lymen`. Algunos recursos del operador se van recién al quitar sus definiciones del cluster. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | Los pods del agente no arrancan | Revisá que el namespace tenga la política `privileged`. | | No veo métricas por pod | Hoy no existen. Solo hay métricas del nodo. | | Instalé y no llega nada | Revisá `ingesta.url`, que el Secret tenga la clave `token` y que los nodos lleguen a esa dirección. | | La anotación no instrumenta | Reiniciá el pod después de anotarlo y confirmá que el operador esté instalado. | --- # 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 la 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. | > **Qué se probó.** En Linux las pruebas se hicieron en contenedores. En Windows se probó el mecanismo en una PC con Windows 11 y el módulo de IIS contra el motor de ASP.NET real alojado en un proceso de prueba. **No se probó todavía en un Windows Server real, ni con un IIS real, ni con el registro de ensamblados del sistema (GAC)**. No lo trates como garantizado: probalo primero en una aplicación de prueba. ## Cómo se instala y se activa ### 1. Instalar el paquete Se instala junto con el agente agregando `LYMEN_INSTRUMENTAR=si` al comando de instalación (ver [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. En Linux funciona con glibc (no con Alpine/musl). Un servicio propio baja las instrucciones del portal y sube el estado cada 30 segundos. ### 2. Activar una aplicación 1. Abrí el servidor en **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. ### 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** 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 (nada se descarga en caliente). En Linux hay además una forma sin portal ni red: crear el archivo `/etc/lymen-agent/instrumentacion/PAUSA`. ## Métodos extra de Java Solo para aplicaciones Java. 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; 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** 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 vos 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** | 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. | — | Método (`GET`, `POST`, `PUT`, `PATCH`, `DELETE` o `*`), 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 `*` amplia 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. - Se puede desactivar por completo con la variable `LYMEN_IIS_DESACTIVAR=1` en el entorno del grupo de aplicaciones (ahí hace falta reciclar). > **No probado en un IIS real.** El módulo se probó contra el motor de ASP.NET real en un proceso de prueba, con .NET Framework 4.8, pero no con `w3wp`, el pipeline integrado ni el GAC. Probalo primero en un sitio de pruebas y avisanos el resultado. ## Kubernetes En Kubernetes la instrumentación no se activa desde este panel, sino con una anotación en el pod. 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). Un proceso suelto compatible se cuenta como "Procesos que ve el agente", pero no se monitorea solo: hay que instalarlo 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). | --- # Equipos de red ## Para qué sirve Con **Equipos de red** ves el estado de tus switches, routers, firewalls y puntos de acceso: si responden, cuánto usan de CPU y memoria, qué interfaces están caídas o saturadas, la temperatura y con qué equipos vecinos se conectan. Los consulta un [gateway](https://lymen.app/docs/instalacion/gateways/) desde adentro de tu red; los equipos nunca necesitan salir a internet. Conceptos que vas a ver: - **SNMP v3**: el protocolo estándar con el que casi todos los equipos de red informan su estado. La versión 3 usa usuario y claves; es la única que usa Lymen. - **Trampas (traps)**: avisos que el equipo manda por su cuenta cuando pasa algo (por ejemplo, una interfaz se cae). - **Syslog**: los mensajes de registro que el equipo manda a un servidor. - **Ping**: la prueba más simple, para saber si el equipo contesta. - **Perfil**: un conjunto de datos propios de un fabricante (Cisco, MikroTik…) que se suman a lo estándar. ## Cuándo usarlo - Querés saber cuándo se cae un switch o un enlace antes de que llamen de la sala. - Querés ver qué interfaces están saturadas. - Querés recibir las trampas y el syslog de tus equipos en un solo lugar. ## El principio de seguridad: vos aprobás, el gateway obedece Lymen **solo consulta lo que aprobaste en el archivo `red-permitidos.yaml` del propio gateway**. Lo que no figura ahí se rechaza, aunque se lo pidas desde el portal. Es un archivo del servidor, de root, que el programa lee pero no puede cambiar. Un archivo ausente, roto o con campos desconocidos significa "todo denegado". Además, las credenciales SNMP v3 se cargan en el **Llavero** con el alcance **Solo en tu red** y quedan **selladas para ese gateway**: ni Lymen puede leerlas. ## Requisitos 1. Un [gateway](https://lymen.app/docs/instalacion/gateways/) activo **en Linux**. El instalador de Windows hoy no incluye el monitoreo de equipos de red. 2. Una **credencial SNMPv3** en el Llavero, con alcance *Solo en tu red*, sellada para ese gateway. Sin credencial, solo podés usar ping. 3. Los equipos con SNMP v3 habilitado y con el usuario creado. 4. El archivo `red-permitidos.yaml` con las direcciones de los equipos. ## Paso a paso ### 1. Aprobar los equipos en el gateway Editá `/etc/lymen-agent/red-permitidos.yaml` en el servidor gateway (como root): ```yaml version: 1 monitorear: [10.20.0.15, 192.168.5.0/24] descubrir: [10.20.0.0/24] escuchar: trampas: "0.0.0.0:162" syslog: "0.0.0.0:514" ``` El instalador lo crea con `version: 1` y las listas vacías. Los cambios en `monitorear` y `descubrir` se toman solos (el archivo se vuelve a leer cuando cambia); si cambiás `escuchar`, **reiniciá el servicio** `lymen-red`. En el portal vas a ver lo aprobado dentro de un minuto. ### 2. Dar de alta el equipo 1. **Agregar datos › Equipos de red › Agregar equipo** (o **Equipos de red › Agregar equipos**). 2. Completá el formulario (campos en la tabla de abajo). 3. Si la dirección todavía no está aprobada en el gateway, el portal te lo avisa: se guarda igual, pero **no se consulta** hasta que la agregues a `monitorear`. 4. Tocá **Agregar**. ### 3. O buscarlos en un rango **Buscar en un rango** pregunta por SNMP v3 a cada dirección de un rango y te muestra los equipos que respondieron, para que elijas cuáles dar de alta. 1. Elegí el **gateway que busca** (el portal muestra los rangos aprobados para buscar). 2. Escribí el **rango**, por ejemplo `10.20.0.0/24`. Tiene que estar completo dentro de uno aprobado en `descubrir`. 3. Marcá hasta **3 credenciales SNMPv3** para probar. 4. Tocá **Buscar**. Puede tardar unos minutos según el tamaño del rango. 5. Marcá los equipos que quieras y tocá **Agregar N equipos**. Cada uno toma el nombre que él mismo informa y la credencial con la que respondió. Si pedís un rango no aprobado, el gateway lo rechaza **sin mandar un solo paquete** y el portal te explica por qué. Límites de la búsqueda: rangos IPv4 de `/22` a `/30` (hasta 1.024 direcciones), hasta 200 equipos encontrados, 100 pedidos por segundo en total y 16 en paralelo, para no molestar a tu red. Solo un descubrimiento a la vez por gateway. ## Campos del equipo | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | **Nombre** | Cómo lo ves en el portal. | — | Letras, números, punto, guion y guion bajo; empieza con letra o número; hasta 63. **No se cambia después.** | Es único por cuenta. | | **Dirección IP** | A qué dirección consulta el gateway. | — | IPv4 o IPv6; **no se admiten nombres** (no se resuelve DNS). No sirven `0.x`, `127.x`, `169.254.x` ni multicast. | Tiene que estar aprobada en `monitorear`. Una por gateway. | | **Puerto SNMP** | Puerto del equipo. | 161 | 1 a 65535 | Si no coincide con el equipo, no responde. | | **Gateway que lo consulta** | Qué gateway hace las consultas. | El primero de la lista | Un gateway activo | Cambiarlo requiere credencial sellada para el nuevo gateway. Un gateway monitorea hasta **300 equipos**. | | **Consultar por SNMP v3** | Prende las consultas SNMP. | Encendido | Encendido / apagado | Apagado, solo se hace ping y no se ven CPU, memoria ni interfaces. | | **Credencial SNMPv3** | Usuario y claves con las que se consulta. | — | Una credencial del Llavero sellada para ese gateway | Si el equipo la rechaza, el estado dice *Credencial rechazada*. | | **Perfil del fabricante** | Qué datos propios leer. | Detectar solo | *Detectar solo*, Cisco, MikroTik, Fortinet, Ubiquiti, HP / Aruba, Genérico (MIB-II) | Un perfil equivocado puede mostrar datos vacíos. *Detectar solo* es lo más seguro. | | **Cada cuánto se consulta** | Frecuencia de las consultas. | 1 minuto | 30 segundos, 1, 2 o 5 minutos | Menos tiempo = detecta antes, pero carga más al equipo y a la red, y guarda más datos (costo). | | **Ping** | Prueba si responde. | Encendido | Encendido / apagado | Tiene que estar encendido SNMP o ping. Algunos equipos bloquean el ping. | | **Trampas SNMP v3** | Recibe los avisos que manda el equipo. | Apagado | Encendido / apagado (requiere SNMP) | Hace falta que el gateway tenga aprobado `escuchar.trampas`. Solo se aceptan de equipos dados de alta. | | **Syslog** | Recibe los mensajes de registro del equipo. | Apagado | Encendido / apagado | Hace falta `escuchar.syslog` aprobado. El volumen puede ser alto: afecta almacenamiento y costo. | En el equipo, además, tenés que apuntar las trampas y el syslog a la dirección del gateway. ## El archivo `red-permitidos.yaml` Está en `/etc/lymen-agent/red-permitidos.yaml`, es de root, y se lee sin reiniciar (salvo `escuchar`). Máximo 64 KB y 200 entradas entre `monitorear` y `descubrir`. | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | `version` | Versión del formato. | `1` | `1` (también se acepta omitirla) | Otro valor deja todo denegado. | | `monitorear` | Equipos que se pueden monitorear (SNMP v3 y ping). | `[]` (nada) | Direcciones o rangos CIDR **privados**; rangos IPv4 hasta `/16` (65.536 direcciones). Para IPv6 hasta `/112`. | Cuanto más amplio el rango, más equipos pueden llegar a consultarse. Aprobá lo mínimo. | | `descubrir` | Rangos donde se pueden **buscar** equipos nuevos. Lo descubierto también se puede monitorear. | `[]` | Rangos IPv4 privados hasta `/22` (1.024 direcciones). En IPv6, solo direcciones sueltas. | Habilita barridos de red desde el gateway. | | `escuchar.trampas` | Dónde escucha las trampas SNMP v3. | Vacío: no escucha | `dirección:puerto`, por ejemplo `"0.0.0.0:162"` | Abre un puerto en el gateway (162 es privilegiado; el servicio ya tiene el permiso). Limitá la red desde el firewall. | | `escuchar.syslog` | Dónde escucha el syslog (UDP y TCP). | Vacío: no escucha | `dirección:puerto`, por ejemplo `"0.0.0.0:514"` | Ídem. Solo se aceptan mensajes de equipos dados de alta. | Solo se aceptan **redes privadas**: `10.x`, `172.16` a `172.31`, `192.168.x`, `100.64` a `100.127` e IPv6 `fc00::/7`. Una dirección pública, de loopback, de enlace local (`169.254.x`) o multicast **no se acepta ni escrita a mano**. Los rangos tienen que estar bien escritos (`10.20.0.0/24`, no `10.20.0.5/24`). ## Perfiles de fabricante Todos los equipos se leen con lo estándar (interfaces, tráfico, errores, descartes, vecinos por LLDP o CDP, CPU y memoria cuando el equipo los publica). Los perfiles suman datos propios de cada marca: | Perfil | Marca | |---|---| | Detectar solo | Elige el perfil según lo que el equipo informa de sí mismo. | | Cisco | Cisco IOS, IOS-XE y NX-OS: CPU, memoria y sensores. | | MikroTik | RouterOS: temperatura (CPU y memoria salen de lo estándar). | | Fortinet | FortiGate: CPU y memoria. | | Ubiquiti | UniFi, EdgeOS y airMAX: reconoce el equipo; CPU y memoria por lo estándar. | | HP / Aruba | HP ProCurve, HPE y Aruba: CPU y memoria. | | Genérico (MIB-II) | Respaldo para cualquier equipo con SNMP. | > **Importante.** Los perfiles se probaron con un agente SNMP de prueba, **no con equipos reales de cada marca**. Si un dato propio no aparece, el resto igual se muestra. Contanos qué ves en tus equipos. ## Qué ves de cada equipo En **Equipos de red** hay una lista con resumen y buscador (por nombre, dirección, fabricante o etiqueta), con los equipos con problemas primero. El detalle muestra: fabricante y perfil, modelo, gateway, credencial, frecuencia, último dato, estado de SNMP y de ping (con milisegundos), CPU, memoria, temperatura, qué más escucha, **Interfaces** (estado, tráfico de entrada y salida, uso del enlace, errores y descartes por hora) y **Vecinos**. Podés **Editar** y **Eliminar** el equipo, y ponerle etiquetas. Los equipos también aparecen en Topología, con el interruptor **Red**. Estados de un equipo: **Responde**, **Caído**, **Sin datos** y **Sin permiso del gateway** (la dirección no está aprobada en `red-permitidos.yaml`). ## Ejemplo completo ```yaml # /etc/lymen-agent/red-permitidos.yaml version: 1 monitorear: - 10.20.0.1 # router del edificio - 10.20.0.10 # switch core - 192.168.5.0/24 # puntos de acceso Wi-Fi descubrir: - 10.20.0.0/24 # para buscar equipos nuevos en la red de sistemas escuchar: trampas: "0.0.0.0:162" syslog: "0.0.0.0:514" ``` ## Problemas comunes | Síntoma | Qué hacer | |---|---| | "Sin permiso del gateway" | Agregá la dirección (o su rango) a `monitorear` y esperá un minuto. | | "El archivo tiene un error" (en el formulario) | El YAML tiene un campo desconocido, un rango público o demasiado grande, o bits de más. Corregilo: mientras tenga error, **todo queda denegado**. | | "Credencial rechazada" | Revisá usuario, protocolo y claves en el Llavero y en el equipo. | | "Credencial no disponible en el gateway" | La credencial no está sellada para ese gateway. Cargala de nuevo con alcance *Solo en tu red* para ese gateway. | | "No responde" con SNMP, pero el ping anda | El equipo no tiene SNMP v3 habilitado, el puerto es otro o un firewall bloquea el 161 desde el gateway. | | Ping "No disponible en el gateway" | El gateway no pudo abrir el socket de ping. El servicio necesita el permiso de red crudo. | | "Ese gateway ya monitorea el máximo de equipos (300)" | Repartí los equipos entre dos gateways. | | No llegan trampas ni syslog | Verificá `escuchar`, reiniciá `lymen-red`, abrí el puerto en el firewall y apuntá el equipo a la dirección del gateway. | | "Ese servidor no es un gateway activo" | Activá el rol de gateway en el servidor ([Gateways](https://lymen.app/docs/instalacion/gateways/)). | --- # Aplicaciones: sitios web y apps móviles ## Para qué sirve **Observar › Aplicaciones** mide la experiencia de las personas que usan tu sitio web o tu app móvil: cuánto tarda en abrir cada pantalla, qué errores ven, qué pedidos al servidor fallan o se demoran, si la app se cierra sola y qué hacen (turnos reservados, pagos, etc.). Se conoce como *experiencia de usuarios reales*. Para medirlo se instala un **SDK** (una librería chica) en el sitio o la app. Esta página explica el alta en el portal; la instalación del SDK está en una página por plataforma: | Plataforma | Página | |---|---| | Web | [SDK web](https://lymen.app/docs/instalacion/sdk-web/) | | Android | [SDK Android](https://lymen.app/docs/instalacion/sdk-android/) | | iOS | [SDK iOS](https://lymen.app/docs/instalacion/sdk-ios/) | | React Native | [SDK React Native](https://lymen.app/docs/instalacion/sdk-react-native/) | ## Cuándo usarlo - Querés saber si tu sitio de turnos o tu app anda lento para tus pacientes o clientes. - Querés ver errores del navegador o cierres de la app antes de que te los reporten. - Querés unir un pedido lento del navegador o del celular con la traza de tu servidor (ver [Instrumentación](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/)). ## Alta paso a paso Tocá **Aplicaciones › Agregar aplicación** (o entrá desde **Agregar datos › Sitios web y apps**). Son tres pasos. ### Paso 1: ¿Qué querés medir? 1. Elegí el tipo: **Web**, **Android**, **iOS** o **React Native**. 2. Escribí el **Nombre** y la **dirección o paquete** (tabla de campos más abajo). 3. Tocá **Crear y seguir**. ### Paso 2: Instalá Lymen El portal arma el código listo para copiar, con tu clave. Copialo y seguí las instrucciones de la plataforma: pegarlo en el `` del sitio, o sumar el SDK al proyecto de la app e iniciarlo. Después publicá o reiniciá la aplicación, y abrila una vez. Tocá **Ya lo instalé**. ### Paso 3: Verificamos que llegue información El portal espera el primer dato (suele tardar menos de un minuto). Abrí el sitio en el navegador, o la app en un teléfono, y navegá una pantalla. Cuando llega, ves **¡Llegó el primer dato!**. ## Campos del alta | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | **Tipo / Plataforma** | Qué se mide. | Web | Web, Android, iOS, React Native | No se cambia después de crearlo: el código y los datos dependen de la plataforma. | | **Nombre** | Cómo lo ves en la lista. | — | Hasta 80 caracteres, sin `<`, `>`, `{`, `}`, `$` ni `\`. | Ninguno. | | **Dirección del sitio** (solo Web) | Desde dónde se abre. Lymen **solo acepta datos que vengan de estas direcciones**. | — | Hasta 20, repetidas no; con `https://` y sin ruta ni barra final (`https://turnos.clinicax.com`). `http` solo para pruebas en tu propia máquina. | **Seguridad.** Una dirección de más permite que otro sitio mande datos con tu clave pública. Una de menos hace que se rechacen los datos de ese sitio. | | **Paquete de la app** (Android, iOS) | El identificador de la app en la tienda (`applicationId` o *bundle id*). | — | Hasta 150 caracteres. | Sirve para reconocer la app. | | **Paquete Android** y **Bundle iOS** (React Native) | Los dos identificadores, ambos opcionales. | Vacíos | Hasta 150 caracteres. | Una sola app React Native recibe de Android y de iOS con la **misma clave**. | ## Editar una aplicación En la lista, cada aplicación tiene un diálogo de edición con estos campos: | Campo | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | **Nombre del servicio** | Cómo aparece en Servicios y en Trazas. | — | Letras, números, punto, guion y guion bajo, hasta 100 (por ejemplo `web-turnos`). | Cambia cómo la encontrás en otras pantallas. Evitá cambiarlo si ya armaste reglas o dashboards con ese nombre. | | **Qué parte de las visitas se mide** | Muestreo: porcentaje de sesiones que se miden. | 100 % | De 1 a 100 % | **Costo y visibilidad.** Con 100 % se mide cada visita. Con mucho tráfico, 25 % alcanza para ver tendencias y baja el costo; pero un error poco frecuente puede no aparecer. La decisión se toma al empezar cada sesión: una sesión entra completa o no entra. Lo que pongas acá **manda sobre lo que escribas en el SDK**. | | **Unir con lo que pasa en tu servidor** | Direcciones de tus APIs a las que se les manda la marca que une el pedido del navegador o la app con la traza del servidor. | Vacío | Hasta 20, con el mismo formato que las direcciones del sitio. | Solo a estas direcciones se les agrega la marca. Tus APIs tienen que aceptarla (CORS en web). Se suma a lo que pongas en el SDK. | | **Registrar los clics** | Guarda qué botón o enlace se tocó. | Apagado | Encendido / apagado | **Privacidad.** Se guarda un identificador del elemento (nunca el texto ni lo escrito). Ayuda a entender qué hizo la persona antes de un error. | | **Recibir datos** | Pausa o activa la aplicación. | Encendido | Encendido / apagado | Pausada, Lymen **no acepta datos** de esta aplicación aunque tenga el código puesto. | | **Eliminar** | Borra la aplicación. | — | — | Deja de aceptar datos con su clave; lo ya guardado vence solo. Si la volvés a agregar, tiene **una clave nueva**: hay que actualizar el SDK. | La **clave pública** (`ly_pub_…`) se genera en Lymen, no se puede cambiar, y **no es un secreto**: va dentro del sitio o la app. Por eso Lymen controla el origen (web) y podés pausar o eliminar la aplicación si hace falta. ## Qué datos recibir En el detalle de una aplicación, la tabla **Qué datos recibimos** tiene un interruptor **Recibir** por tipo de dato. Lo que está apagado **no sale del navegador ni del celular**. | Tipo de dato | Qué incluye | Por defecto | |---|---|---| | **Visitas a páginas** (en móvil: *Pantallas vistas*) | Cada vez que alguien abre una pantalla. | Encendido | | **Tiempos de carga** (móvil: *Tiempos de inicio*) | Qué tan rápido abre cada página o la app. | Encendido | | **Errores de la página** (móvil: *Errores y cierres de la app*) | Cuando algo se rompe. | Encendido | | **Pedidos al servidor** | Las consultas que hace la página o la app al sistema. Con esto apagado tampoco se agrega la marca de unión con el servidor. | Encendido | | **Clics y acciones** | Botones tocados (también requiere *Registrar los clics*). | Encendido | | **Sesiones** | Cuántas personas usan el sitio y por cuánto tiempo. | Encendido | | **Mensajes de la app (logs)** | Textos que la app escribe para diagnosticar. | **Apagado** | Apagar un tipo reduce el volumen (costo) y la exposición de datos; encender los mensajes puede traer texto con datos personales, aunque pasen por las reglas de Privacidad. Los eventos de negocio (por ejemplo `turno.reservado`) siempre se mandan. Estados de una aplicación en la lista: **Recibiendo datos**, **Con errores** y **Sin datos todavía**. ## Privacidad - Las reglas de Privacidad se aplican **en el dispositivo y otra vez al recibir**. - Nunca se captura lo que la gente escribe en formularios y no se graban sesiones. - El identificador de usuario que mandes sale **hasheado** (SHA-256), nunca en claro. - Si el SDK no logra bajar las reglas, usa reglas de respaldo: DNI, email, tarjetas (solo si el número es válido) y CUIT/CUIL. Las reglas se editan en **Configuración › Privacidad**. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | Quedó "Esperando el primer dato" | ¿Publicaste o reiniciaste? ¿Abriste el sitio o la app? Revisá que la clave sea la correcta y que la aplicación esté con **Recibir datos** encendido. | | En web, no llegan datos y en la consola del navegador hay errores de origen | El sitio se abre desde una dirección que no está en la lista. Agregala (con `https://` y sin barra final). | | No se unen las trazas del navegador con las del servidor | Agregá la dirección de tu API en **Unir con lo que pasa en tu servidor** y permití la marca en el CORS de tu API. | | Veo menos visitas que en otra herramienta | Revisá el muestreo: 100 % mide todo. | | Cambié la clave y dejó de andar | Al eliminar y volver a crear la aplicación, la clave cambia. Actualizala en el SDK. | --- # SDK web ## Para qué sirve El SDK web mide la experiencia real de quienes usan tu sitio: cuánto tarda en cargar cada pantalla, qué errores ven, qué pedidos al servidor fallan o tardan y qué hacen (eventos de negocio). Manda los datos a tu punto de entrada de Lymen y une cada pedido del navegador con la traza de tu servidor. - Pesa unos **34 KB comprimido** (el bundle para pegar con ` ``` El script se inicia solo con los atributos `data-*` y deja la API en `window.lymen`. Si necesitás llamar a la API antes de que termine de cargar, encolá las llamadas: ```html ``` ### Con npm ```sh npm install lymen-sdk-web ``` ```ts import { iniciar } from 'lymen-sdk-web'; iniciar({ sitio: 'ly_pub_XXXXXXXXXXXXXXXXXXXXXXXX', endpoint: 'https://-ingesta.lymen.app', version: '1.4.0', propagarA: ['https://api.tu-empresa.com'], }); ``` Trae ESM, CommonJS y tipos de TypeScript. Llamarlo del lado del servidor (SSR) no hace nada. ## Opciones La tabla muestra el nombre en `iniciar()` y, cuando existe, el atributo del script. | Opción (atributo) | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | `sitio` (`data-sitio`) | Clave pública del sitio. | — (obligatoria) | `ly_pub_…` | Sin ella, el SDK no arranca y avisa en la consola. No es un secreto. | | `version` (`data-version`) | Versión de tu aplicación. | — (obligatoria en npm) | Texto | Permite comparar errores y rendimiento entre versiones de tu sitio. | | `endpoint` (`data-endpoint`) | Punto de entrada de Lymen. | Con el script: el origen de donde se bajó. Con npm: indicalo siempre. | URL `https://-ingesta.lymen.app` | Si es incorrecto, no llega nada. | | `servicio` (`data-servicio`) | Nombre del servicio. | La clave del sitio | Texto | El servidor lo reemplaza por el nombre de servicio del sitio que cargaste en el portal. | | `entorno` (`data-entorno`) | Entorno. | `produccion` | Texto | Permite separar producción de pruebas en los filtros. | | `propagarA` (`data-propagar-a`) | Orígenes de tus APIs a los que se les agrega `traceparent`, la marca que une el pedido del navegador con la traza del servidor. | Vacío | Lista (en el atributo, separada por comas). Acepta comodín: `https://*.tu-empresa.com`. | Solo a esos orígenes (ni siquiera al mismo origen si no está). Tu API tiene que aceptar `traceparent` en CORS, o el navegador bloquea el pedido. Se suma a lo configurado en el portal. | | `muestreo` (`data-muestreo`) | Qué parte de las sesiones se mide. | `1` (todas) | De 0 a 1 | **Costo.** Menos sesiones, menos datos. **Manda el valor del portal si existe.** Se decide al empezar cada sesión. | | `consentimiento` (`data-consentimiento`) | Estado inicial del consentimiento. | Lo último que eligió la persona; si nunca eligió, `concedido` | `pendiente`, `concedido`, `denegado` | **Legal y privacidad.** Con `pendiente` se guarda en memoria y no se manda nada; con `denegado`, no se mide ni se manda nada. Si tu sitio pide consentimiento (cookies), iniciá en `pendiente`. | | `capturarClics` (`data-capturar-clics`) | Registra los clics. | `false` | `true` / `false` | **Privacidad.** Guarda qué se tocó (el atributo `data-lymen-clic`, el id o un selector corto), nunca el texto. El portal puede mandar sobre este valor. | | `capturarConsola` (`data-capturar-consola`) | Manda `console.warn` y `console.error` como mensajes. | `false` | `true` / `false` | **Privacidad.** Los mensajes pueden traer datos personales (pasan por Privacidad). Solo llegan si el portal recibe *Mensajes de la app*, que viene apagado. | | `rutas` (`data-rutas`) | Patrones de las rutas de tu sitio para nombrar las vistas. | — | Por ejemplo `['/turnos/:id', '/medicos/:slug']` | Sin patrones, los ids se reemplazan solos por `:id`. Con patrones tus vistas se agrupan como querés. | | `normalizarRuta` | Función propia para nombrar las vistas. | — | Función | Solo con npm. | | `vistasAutomaticas` | Detecta los cambios de pantalla. | `true` | `true` / `false` | En `false`, usá `vista()` a mano. | | `red` | Mide los pedidos `fetch`/`XMLHttpRequest`. | `true` | `true` / `false` | En `false` no hay datos de pedidos ni `traceparent`. | | `depurar` | Avisos del SDK en la consola. | `false` | `true` / `false` | Solo para desarrollo. | El portal tiene la última palabra sobre el muestreo, los clics y a qué orígenes se propaga `traceparent` (se suma). Un cambio en el portal llega solo, sin publicar una versión nueva del sitio. ## API ```ts usuario(id | null) // se hashea con SHA-256 antes de salir del navegador evento('turno.reservado', { monto: 15000, especialidad: 'clinica' }) error(err, { 'turno.paso': 'confirmar' }) // error que ya manejaste vista('Detalle del turno') // vista manual consentimiento('concedido' | 'denegado') log('warn', 'No se pudo cargar la agenda', { 'turno.id': 9 }) // debug | info | warn | error ``` - **Nombre de los eventos de negocio**: `entidad.accion`, en minúsculas, números y `_` (por ejemplo `turno.reservado`). - **`log`**: el mensaje se corta a 4096 caracteres y pasa por Privacidad. Solo llega si en el portal está encendido *Mensajes de la app*. ### Eventos de negocio: desde un solo lado Mandá un mismo evento (por ejemplo `turno.reservado`) **desde la app o desde el backend, nunca desde los dos**: Lymen junta los dos orígenes y se contaría doble. Mandalo desde donde se confirma de verdad (normalmente el backend). Desde el sitio quedan los eventos que solo existen ahí (`carrito.abierto`, `filtro.aplicado`). ## Qué mide | Dato | Detalle | |---|---| | **Sesión** | Id al azar, compartido entre pestañas. Se renueva a los 30 minutos sin actividad o a las 4 horas. | | **Vistas** | Cada cambio de ruta (history o `#/`), con la vista anterior y cuánto estuvo la persona. Las rutas se normalizan (`/turnos/123` pasa a `/turnos/:id`). | | **Qué tan rápido carga** | LCP, INP, CLS, FCP y TTFB, calificados como bueno, mejorable o malo, y los tiempos de carga de la página. | | **Errores** | Los no manejados y las promesas rechazadas, más los que mandes con `error()`. Cada uno trae una huella para agruparlo aunque cambie el mensaje o el archivo en cada versión. | | **Pedidos al servidor** | Método, URL, estado y duración. | | **Tareas largas** | Momentos en que la página se trabó. | | **Clics** | Solo si los activás. | | **Eventos de negocio** y **mensajes** | Los que mandes con `evento()` y `log()`. | Los datos se envían en lotes cada 5 segundos o cada 50 elementos, y lo pendiente sale al ocultarse o cerrarse la página. ## Privacidad - Las reglas vienen de **Privacidad** en el portal. El SDK las pide al iniciar y cada 10 minutos, y guarda la última copia para arrancar sin red. - Se aplican a URLs, mensajes de error, textos y atributos: enmascaran (`***`), borran o hashean. - Si el SDK nunca pudo bajar las reglas, usa unas de respaldo: DNI, email, tarjetas (solo si el número es válido) y CUIT/CUIL. - La plataforma vuelve a aplicar Privacidad al recibir: el navegador es la primera barrera, no la única. - No se leen los valores de formularios y el id de usuario sale hasheado. ## Ejemplos ### React ```tsx // main.tsx import { iniciar, usuario, evento, error } from 'lymen-sdk-web'; iniciar({ sitio: import.meta.env.VITE_LYMEN_SITIO, endpoint: 'https://-ingesta.lymen.app', version: import.meta.env.VITE_VERSION, propagarA: ['https://api.tu-empresa.com'], rutas: ['/turnos/:id'], }); usuario(sesion.idPaciente); // después del login async function confirmar() { try { await api.reservar(datos); } catch (e) { error(e, { 'turno.paso': 'confirmar' }); } } ``` React Router usa `history`, así que las vistas se detectan solas. ### Angular ```ts // main.ts import { iniciar } from 'lymen-sdk-web'; iniciar({ sitio: environment.lymenSitio, endpoint: 'https://-ingesta.lymen.app', version: environment.version, propagarA: [environment.apiUrl], rutas: ['/turnos/:id', '/medicos/:slug'], }); bootstrapApplication(AppComponent, appConfig); ``` Para los errores que Angular atrapa antes que el navegador, implementá un `ErrorHandler` que llame a `error(e, { origen: 'angular' })`. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | No llega nada | Revisá `sitio` y `endpoint`; en la consola, activá `depurar: true`. Confirmá que el sitio esté en **Recibir datos** y que su dirección esté en la lista de direcciones del alta. | | Aparece "iniciar necesita sitio y version" | Falta una de las dos opciones obligatorias. | | El navegador bloquea pedidos a mi API | Tu API tiene que aceptar el encabezado `traceparent` en CORS, o quitá esa API de `propagarA`. | | Veo eventos de negocio duplicados | Los estás mandando desde el sitio y desde el backend. Elegí un solo lado. | | No veo mensajes (`log`) | En el portal, el tipo *Mensajes de la app* viene apagado. | | Las vistas tienen ids en el nombre | Usá la opción `rutas` con los patrones de tu router. | --- # SDK Android ## Para qué sirve El SDK de Android mide la experiencia real de quienes usan tu app: sesiones, pantallas, tiempo de arranque, errores, cierres inesperados (*crashes*), apps trabadas (*ANR*), pedidos de red y eventos de negocio. Lo ves en **Aplicaciones**. - Kotlin, `minSdk` 24. La app tiene que compilar con `compileSdk` 37. - Versión actual: **0.2.1** (artefacto de unos 190 KB). ## Cuándo usarlo Cuando tenés una app Android propia. Antes, dala de alta en [Aplicaciones](https://lymen.app/docs/instalacion/aplicaciones/) (tipo *Android*): ahí obtenés la clave (`ly_pub_…`) y el código listo para copiar. Si tu app es React Native, mirá [SDK React Native](https://lymen.app/docs/instalacion/sdk-react-native/). ## Instalación ```kotlin // settings.gradle.kts dependencyResolutionManagement { repositories { google() mavenCentral() // más el repositorio donde tengas el SDK } } // app/build.gradle.kts android { compileOptions { // Hace falta si minSdk < 26. isCoreLibraryDesugaringEnabled = true } } dependencies { implementation("app.lymen:lymen-sdk-android:0.2.1") coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") } ``` No hace falta configurar R8/ProGuard: el SDK trae sus propias reglas. ## Iniciar Una sola vez, en `Application.onCreate()`: ```kotlin class MiApp : Application() { override fun onCreate() { super.onCreate() LymenSdk.iniciar( this, Opciones( sitio = "ly_pub_XXXXXXXXXXXXXXXXXXXXXXXX", // clave pública (no es secreta) endpoint = "https://-ingesta.lymen.app", propagarA = listOf("api.tu-empresa.com"), ), ) } } ``` `iniciar` vuelve enseguida: solo instala lo necesario para medir el arranque y la primera pantalla; el resto se arma en segundo plano. Lo que mandes mientras tanto (`evento`, `usuario`, `error`) se guarda y sale después, con su hora original. ## Opciones | Opción | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | `sitio` | Clave pública de la app. | — (obligatoria) | `ly_pub_…` | Sin ella no se mide. | | `endpoint` | Punto de entrada de Lymen. | Un valor de ejemplo que **no es el de tu cuenta** | `https://-ingesta.lymen.app` | **Indicalo siempre.** Si no, los datos no llegan a tu cuenta. El SDK le agrega las rutas necesarias. | | `servicio` | Nombre del servicio. | El paquete de la app | Texto | El servidor lo reemplaza por el nombre de servicio del alta. | | `version` | Versión de la app. | `versionName` | Texto | Permite comparar versiones. | | `entorno` | Entorno. | `produccion` | Texto | Separa producción de pruebas. | | `propagarA` | Orígenes que reciben `traceparent` (la marca que une el pedido del celular con la traza del servidor). | Vacía | `api.x.com`, `api.x.com:8443`, `*.x.com` o `https://api.x.com` | Solo a esos orígenes. Se suma a lo configurado en el portal. | | `muestreo` | Porción de sesiones que se mandan. | `1.0` | De 0 a 1 | **Costo.** Se decide al empezar cada sesión. Si el portal define un muestreo, **manda el del portal**. | | `consentimiento` | Valor inicial. | `CONCEDIDO` (o lo último que eligió el usuario) | `PENDIENTE`, `CONCEDIDO`, `DENEGADO` | **Legal y privacidad.** `PENDIENTE` junta en memoria sin mandar; `DENEGADO` no manda nada y borra lo pendiente y la cola en disco. Si pedís permiso en tu app, iniciá en `PENDIENTE`. | | `capturarClics` | Registra los toques. | `false` | `true` / `false` | **Privacidad.** Guarda el id del recurso tocado, nunca el texto. El portal puede mandar sobre este valor. | | `vistasAutomaticas` | Detecta las pantallas (Activity y Fragment). | `true` | `true` / `false` | En `false`, marcá las pantallas a mano. | | `depuracion` | Escribe en logcat con la etiqueta `lymen`. | `false` | `true` / `false` | Solo desarrollo. | ## API ```kotlin LymenSdk.usuario("id-del-usuario") // se manda el hash SHA-256; null lo borra LymenSdk.evento("turno.reservado", mapOf("monto" to 15000, "moneda" to "ARS")) LymenSdk.error(excepcion, mapOf("pantalla.accion" to "pagar")) // error manejado LymenSdk.vista("Pago") // pantalla manual LymenSdk.consentimiento(Consentimiento.DENEGADO) LymenSdk.log(NivelLog.WARN, "reintento del pago") // apagado salvo que el portal prenda los mensajes LymenSdk.sesionActual() // id de sesión, para mandarlo a tu backend LymenSdk.enviarAhora() ``` Los eventos de negocio se llaman `entidad.accion` (minúsculas, números y `_`); si no, se ignoran. Mandá un mismo evento **desde la app o desde el backend, nunca desde los dos**, o se cuenta doble. ### Pantallas - **Activity y Fragment**: automáticas. Si una Activity solo aloja fragments, cuenta el Fragment. - **Jetpack Compose**: poné `VistaLymen("Nombre")` al principio de cada pantalla y marcá la Activity con `@SinVistaAutomatica` para que no cuente doble. - **Manual**: `LymenSdk.vista("Nombre")`. ### Red (OkHttp) ```kotlin val cliente = OkHttpClient.Builder() .addInterceptor(LymenOkHttp.interceptor()) .build() ``` Cada pedido es un span con los atributos HTTP estándar. `traceparent` se agrega **solo** a los orígenes de `propagarA`. ## Qué mide | Dato | Detalle | |---|---| | **Sesión** | Se renueva a los 30 minutos sin actividad o a las 4 horas. Sigue si la app se reinicia antes. Registra el origen: directo, enlace (*deep link*) o notificación. | | **Inicio de la app** | En frío (desde que arranca el proceso), tibio (proceso vivo, Activity nueva) y caliente (vuelve a primer plano), hasta el primer cuadro. | | **Errores** | Los que mandes con `error()`: tipo, mensaje, stack (hasta 8 KB) y huella para agrupar. | | **Crashes** | Se guardan en disco antes de que la app se cierre y salen en el próximo arranque. | | **ANR** | Cuando el hilo principal no responde por 5 segundos o más. Si el sistema cierra la app, sale en el próximo arranque. | | **Pedidos de red** | Con el interceptor de OkHttp. | | **Clics** | Solo si los activás. | ## Envío y reintentos - Datos comprimidos, en lotes de hasta 50 elementos, cada 5 segundos o al juntar 50, y al pasar a segundo plano. - **Cola en disco** con tope de 5 MB: si se llena, se descartan los lotes más viejos. - Ante errores de red o del servidor se reintenta con espera creciente (5 s, 10 s, 20 s… hasta 5 minutos). Si la clave es inválida o la aplicación está pausada en el portal, se frenan los envíos 10 minutos. ## Privacidad - Las reglas de **Privacidad** bajan del servidor (al iniciar y cada 10 minutos) y se aplican en el celular antes de mandar. El servidor las vuelve a aplicar. - Sin reglas descargadas, se usan las de respaldo: DNI, email, tarjetas y CUIT/CUIL. - No se captura el valor de ningún campo de texto y no se graban sesiones. `user.id` sale siempre hasheado. - Desde el portal podés **apagar** tipos de dato (vistas, tiempos, errores, red, clics, sesiones, logs): lo apagado no sale del celular. Los logs vienen apagados. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | No llegan datos | Revisá `sitio` y `endpoint`; activá `depuracion = true` y mirá logcat con la etiqueta `lymen`. Confirmá que la app esté con **Recibir datos** en el portal. | | Error de compilación por `compileSdk` | La app tiene que compilar con `compileSdk` 37. | | La app compila con `minSdk` menor que 26 y falla | Activá el *desugaring* (`isCoreLibraryDesugaringEnabled = true`) y la dependencia `coreLibraryDesugaring`. | | No veo los crashes enseguida | Se envían en el siguiente arranque de la app. | | Se cuentan doble los eventos | Mandalos solo desde un lado: la app o el backend. | --- # SDK iOS ## Para qué sirve El SDK de iOS mide la experiencia real de quienes usan tu app: sesiones, pantallas, inicio de la app, pedidos de red, errores, crashes y los eventos de negocio que quieras contar. Lo ves en **Aplicaciones**. - Swift, **iOS 13 o superior**. Paquete `lymen-sdk-ios`, módulo `LymenSdk`. Versión actual: **0.2.1**. > **Qué se probó.** El paquete se compiló y probó en Linux (con un contenedor de Swift) y en integración continua; no se probó en un iPhone físico en esta documentación. Hacé una prueba en tu entorno antes de publicar la app. ## Cuándo usarlo Cuando tenés una app iOS propia. Antes, dala de alta en [Aplicaciones](https://lymen.app/docs/instalacion/aplicaciones/) (tipo *iOS*) para obtener la clave. Si tu app es React Native, mirá [SDK React Native](https://lymen.app/docs/instalacion/sdk-react-native/). ## Instalación (Swift Package Manager) En Xcode: **File › Add Package Dependencies…**, pegá la dirección del repositorio y elegí el producto **LymenSdk**. O en un `Package.swift`: ```swift dependencies: [ .package(url: "https:///lymen-sdk-ios.git", exact: "0.2.1"), ], targets: [ .target(name: "MiApp", dependencies: [.product(name: "LymenSdk", package: "lymen-sdk-ios")]), ] ``` ## Iniciar Llamá a `LymenSdk.iniciar` **una sola vez**, lo antes posible y desde el hilo principal. SwiftUI: ```swift import LymenSdk import SwiftUI @main struct TurnosApp: App { init() { LymenSdk.iniciar(Opciones( sitio: "ly_pub_XXXXXXXXXXXXXXXXXXXXXXXX", // clave pública (no es secreta) endpoint: URL(string: "https://-ingesta.lymen.app")!, version: "1.4.0", entorno: "produccion", propagarA: ["https://api.tu-empresa.com"] )) } var body: some Scene { WindowGroup { InicioView() } } } ``` UIKit: se llama igual desde `application(_:didFinishLaunchingWithOptions:)`, con `vistasAutomaticas: true` si querés pantallas automáticas. ## Opciones | Opción | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | `sitio` | Clave pública de la app. | — (obligatoria) | `ly_pub_…` | Sin ella no se mide. | | `endpoint` | Base de la ingesta. | Un valor de desarrollo que **no sirve** para tu cuenta | `URL(string: "https://-ingesta.lymen.app")` | **Indicalo siempre**, o no llega nada. | | `servicio` | Nombre del servicio. | El *bundle id* | Texto | El servidor lo reemplaza por el nombre del alta. | | `version` | Versión de tu app. | — (obligatoria) | Texto | Permite comparar versiones. | | `entorno` | Entorno. | `produccion` | Texto | Separa producción de pruebas. | | `propagarA` | Orígenes que reciben `traceparent` (une el pedido del celular con la traza del servidor). | `[]` | `https://api.x.com`, `api.x.com` o `*.x.com` | Solo a esos. Se suma a lo del portal. | | `muestreo` | Fracción de sesiones que se mandan. | `1` | De 0 a 1 | **Costo.** Se decide al empezar cada sesión. **Manda el del portal** si lo hay. | | `consentimiento` | Valor inicial. | `nil`: lo último que eligió el usuario, o `concedido` si nunca eligió | `.pendiente`, `.concedido`, `.denegado` | **Legal y privacidad.** `.pendiente` junta sin mandar; `.denegado` no manda nada y borra lo pendiente, la cola y cualquier crash guardado. | | `capturarClics` | Registra los toques en controles. | `false` | `true` / `false` | **Privacidad.** Guarda el `accessibilityIdentifier` o la clase, nunca el texto. | | `vistasAutomaticas` | Pantallas de UIKit automáticas. | `false` | `true` / `false` | Usa una técnica que intercepta `viewDidAppear`. En SwiftUI marcá las pantallas con `LymenSdk.vista`. | | `capturarRed` | Mide los pedidos de URLSession. | `true` | `true` / `false` | Apagado, no hay datos de red ni `traceparent`. | | `capturarCrashes` | Captura los crashes. | `true` | `true` / `false` | Ver "Crashes" más abajo. | | `depuracion` | Mensajes `[lymen]` en la consola. | `false` | `true` / `false` | Solo desarrollo; nunca muestra datos del usuario. | ## API ```swift LymenSdk.usuario("paciente-123") // se manda como SHA-256; nil lo borra LymenSdk.evento("turno.reservado", ["especialidad": "clinica", "monto": 15000, "moneda": "ARS"]) LymenSdk.error(error, ["pantalla": "medicos"]) // error manejado LymenSdk.vista("Confirmar turno") LymenSdk.consentimiento(.concedido) // .pendiente | .concedido | .denegado LymenSdk.log(.warn, "Reintento del pago") // apagado salvo que el portal lo prenda LymenSdk.origenSesion(.push) // la sesión se abrió desde una notificación (o .link) LymenSdk.enviarAhora() // manda ya lo juntado ``` Los eventos de negocio se llaman `entidad.accion` en minúsculas. Un nombre inválido se ignora. Mandá un mismo evento **desde la app o desde el backend, nunca desde los dos**. ## Qué mide - **Sesión**: se renueva a los 30 minutos sin actividad o a las 4 horas; se guarda en disco, así reabrir la app enseguida sigue en la misma sesión. - **Inicio de la app**: en frío, tibio y caliente. - **Pantallas, pedidos de red, errores manejados y crashes.** - **Clics**: solo si los activás. ## Crashes Al crashear, el SDK guarda un reporte en disco y lo manda **en el próximo arranque**, atribuido a la sesión, la pantalla y el usuario del momento. Limitaciones que conviene conocer: - Captura señales (SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP) y excepciones de Objective-C sin atrapar. Los errores de Swift (`fatalError`, índice fuera de rango, `!` sobre `nil`) llegan **sin el mensaje**. - **No** captura cierres por SIGKILL: el sistema que cierra la app por tardar demasiado o por falta de memoria, ni cuando el usuario la cierra desde el selector de apps. - El stack **no está simbolizado** (no se suben dSYM). - Es esfuerzo razonable, no garantizado. Si usás otro capturador de crashes, pueden pisarse: usá uno solo. - Con el depurador de Xcode conectado no se captura: probá desde el simulador o dispositivo sin depurador. ## Envío y reintentos - Cola en disco con tope de **5 MB** (si se llena, se descartan los envíos más viejos). - Sin red, se reintenta con espera creciente (2 s, 4 s, 8 s… hasta 5 minutos). - Al pasar a segundo plano, el SDK pide unos segundos al sistema para guardar y probar un envío. ## Privacidad - Las reglas de **Privacidad** bajan del servidor y se aplican en el celular; el servidor las vuelve a aplicar. - Sin reglas descargadas se usan las de respaldo (DNI, email, tarjetas y CUIT/CUIL). - No se captura el valor de campos de texto y no se graban sesiones. `user.id` sale siempre hasheado. - Desde el portal podés apagar tipos de dato; lo apagado no sale del teléfono. Los logs vienen apagados. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | No llegan datos | Revisá `sitio` y que `endpoint` apunte a tu cuenta. Activá `depuracion: true`. | | No hay crashes | Probá sin depurador conectado; se envían al siguiente arranque. | | No hay pantallas | En UIKit, `vistasAutomaticas: true`; en SwiftUI, usá `LymenSdk.vista(...)`. | | Doble conteo de eventos | Mandalos solo desde la app o solo desde el backend. | --- # SDK React Native ## Para qué sirve Mide sesiones, pantallas, errores de JavaScript y nativos, crashes, pedidos de red y eventos de negocio de tu app React Native. No reimplementa nada: es una capa fina sobre los SDK nativos de Lymen ([Android](https://lymen.app/docs/instalacion/sdk-android/) e [iOS](https://lymen.app/docs/instalacion/sdk-ios/)). El SDK nativo maneja la sesión, la cola en disco, el consentimiento, la privacidad, los crashes, el inicio de la app y la red; JavaScript suma lo que el nativo no ve: errores de JS, promesas rechazadas y pantallas de `react-navigation`. Con **una sola alta** y **una sola clave** recibís de Android y de iOS. En el detalle de la aplicación filtrás por sistema (Todas, Android, iOS). > **Qué se probó.** La versión 0.2.1 compila en Android y se probó en un emulador contra una ingesta de prueba. En iOS se compila en integración continua, pero no se probó en un teléfono. ## Requisitos | Requisito | Detalle | |---|---| | React Native | 0.76 o posterior (arquitectura nueva o vieja) | | JavaScript | Hermes (por defecto), necesario para capturar promesas rechazadas | | Android | `minSdk` 24, `compileSdk` 37 y **Kotlin 2.3 o posterior** en la app | | iOS | iOS 13.4 | | Expo | Solo con *development build* (`npx expo prebuild` o EAS Build). **No funciona en Expo Go**. | ## Instalación Primero dá de alta la app en [Aplicaciones](https://lymen.app/docs/instalacion/aplicaciones/) con tipo **React Native** (podés cargar el paquete Android y el *bundle id* de iOS). ```sh npm install lymen-sdk-react-native@0.2.1 cd ios && pod install ``` ### Android En `android/build.gradle` de la app, la versión de compilación y la de Kotlin que exige el SDK: ```groovy buildscript { ext { compileSdkVersion = 37 minSdkVersion = 24 kotlinVersion = "2.4.21" } dependencies { classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion") } } ``` El paquete le agrega el seguimiento de pedidos al cliente de red de React Native. Si `minSdkVersion` es menor que 26, la app necesita *desugaring* (ver [SDK Android](https://lymen.app/docs/instalacion/sdk-android/)). ### iOS El `pod install` suma el SDK nativo de iOS como paquete de Swift (React Native 0.75 o más nuevo). ### Expo Con un *development build* no hace falta un plugin propio. Para Android, configurá `compileSdkVersion: 37` y `minSdkVersion: 24` con `expo-build-properties`. ## Iniciar Lo antes posible, en `index.js`, antes de `AppRegistry.registerComponent`: ```js import lymen from 'lymen-sdk-react-native'; lymen.iniciar({ sitio: 'ly_pub_TU_CLAVE', // la misma para Android e iOS endpoint: 'https://-ingesta.lymen.app', version: '1.4.0', propagarA: ['api.tu-empresa.com'], }); ``` ### Iniciar también desde el código nativo (opcional) Iniciar desde JavaScript es lo más simple, pero JavaScript arranca cuando la app ya abrió: el **inicio de la app en frío** y un crash en los primeros segundos no se miden. Para medirlos, iniciá también el SDK nativo al abrir la app (`MainApplication.onCreate()` en Android, `AppDelegate` en iOS). Después, el `iniciar` de JS se ignora en el nativo (gana el primero) y solo engancha lo de JS. En Android, usá `vistasAutomaticas = false`: las pantallas las marca JS. ## Opciones | Opción | Para qué sirve | Por defecto | Valores válidos | Impacto de cambiarlo | |---|---|---|---|---| | `sitio` | Clave pública de la app. | — (obligatoria) | `ly_pub_…` | Es la misma para Android y iOS. | | `endpoint` | Punto de entrada de Lymen. | El del SDK nativo (no es el de tu cuenta) | `https://-ingesta.lymen.app` | **Indicalo siempre.** | | `servicio` | Nombre del servicio. | El paquete de la app | Texto | El servidor lo reemplaza por el del alta. | | `version` | Versión de la app. | La del paquete | Texto | Para comparar versiones. | | `entorno` | Entorno. | `produccion` | Texto | Separa producción de pruebas. | | `propagarA` | Destinos que reciben `traceparent` (une el pedido del celular con la traza del servidor). | Vacía | `api.x.com`, `api.x.com:8443`, `*.x.com` o `https://api.x.com` | Se suma a lo que baje del portal. | | `muestreo` | Porción de sesiones que se mandan. | `1` | De 0 a 1 | **Costo.** Si el portal define uno, manda el del portal. | | `consentimiento` | Valor inicial. | `concedido` (o lo último que eligió el usuario) | `pendiente`, `concedido`, `denegado` | **Legal y privacidad.** `pendiente` junta sin mandar; `denegado` no manda nada. | | `capturarClics` | Registra los toques. | `false` | `true` / `false` | **Privacidad.** Nunca el texto. | | `capturarErrores` | Errores de JavaScript no atrapados. | `true` | `true` / `false` | Apagado, no verás los errores de JS. | | `capturarPromesas` | Promesas rechazadas sin `catch` (Hermes). | `true` | `true` / `false` | Apagado, perdés esos errores. | | `depuracion` | Mensajes del SDK en consola y en el log nativo. | `false` | `true` / `false` | Solo desarrollo. | ## API ```js lymen.usuario('paciente-123'); // se manda el hash SHA-256; null lo borra lymen.evento('turno.reservado', { especialidad: 'clinica', monto: 15000 }); lymen.error(err, { 'pantalla.accion': 'pagar' }); // error manejado lymen.vista('Pago'); // pantalla manual lymen.consentimiento('denegado'); lymen.log('warn', 'reintento del pago'); // apagado salvo que el portal lo prenda lymen.enviarAhora(); await lymen.sesionActual(); // id de sesión o null ``` Los eventos de negocio se llaman `entidad.accion` (minúsculas, números y `_`). Mandalos **desde la app o desde el backend, nunca desde los dos**. Ninguna función lanza excepciones. `probarCierreNativo()` existe solo para comprobar la instalación: **cierra la app** con un error nativo, no la uses en producción. ### Pantallas con react-navigation ```jsx import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native'; import { useVistasLymen } from 'lymen-sdk-react-native'; export default function App() { const navigationRef = useNavigationContainerRef(); useVistasLymen(navigationRef); // cada cambio de pantalla es una vista return {/* ... */}; } ``` El nombre de la vista es el nombre de la ruta, **nunca sus parámetros** (pueden tener datos personales). Para cambiarlo: `useVistasLymen(navigationRef, { nombrar: (ruta) => ruta.name })`. ### Errores de JavaScript `iniciar` engancha el manejador global de errores **encadenándolo** al que había: la pantalla roja en desarrollo y el cierre de la app ante un error fatal siguen igual. Cada error trae el tipo, el mensaje, el stack (hasta 8 KB) y una huella para agruparlos. Tope: **100 errores por ejecución y 10 por huella**. Un error fatal en la versión de producción cierra la app: llega el error de JS y, en el próximo arranque, el crash nativo. ### Red El `fetch` y el `XMLHttpRequest` de React Native viajan por la red nativa, así que **la red la mide el SDK nativo** y cada pedido tiene un solo span. Solo si el nativo no mide la red (por ejemplo, en Android si la app arma su propio cliente HTTP) se usa `instrumentarFetch()`, que es seguro de llamar siempre: si el nativo ya mide, no hace nada. ## Privacidad Las reglas de Privacidad bajan del portal y las aplica el SDK nativo antes de mandar; el servidor las vuelve a aplicar. JavaScript no captura textos ingresados ni parámetros de navegación, y `user.id` sale siempre hasheado. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | Error de compilación de Kotlin al armar Android | Subí Kotlin a 2.3 o posterior en `android/build.gradle`. | | No funciona en Expo Go | Usá un *development build*. | | No se mide el inicio en frío | Iniciá también desde el código nativo. | | Los errores de promesas no llegan | Necesitás Hermes y `capturarPromesas` encendido. | | Veo todo mezclado | En el detalle de la aplicación filtrá por sistema: Todas, Android o iOS. | --- # Desinstalar ## Para qué sirve Para sacar Lymen de un servidor que ya no querés medir, o para dejarlo limpio antes de reinstalar. Son **dos cosas distintas** y conviene hacer las dos: 1. **Desinstalar el programa** del servidor (lo que explica esta página). 2. **Quitar el servidor del portal** (**Infraestructura › detalle del servidor › Quitar servidor**). Eso revoca su credencial: el agente deja de poder mandar datos. Desinstalar el programa **no lo quita del portal**: el servidor sigue figurando hasta que lo quiten desde ahí. El desinstalador **no toca las aplicaciones** del servidor. ## Linux ```sh sudo /opt/lymen-agent/actual/lymen-desinstalar ``` | Opción | Qué hace | |---|---| | `--si` | No pregunta antes de seguir. | | `--conservar-datos` | Deja `/var/lib/lymen-agent` (la cola de datos y las claves del gateway). Útil si vas a reinstalar el mismo servidor. | Sin `--conservar-datos`, también se borran las claves del gateway: si el servidor era gateway y lo reinstalás, las credenciales selladas para él quedan ilegibles y hay que volver a cargarlas en el Llavero. Saca, en este orden: el monitoreo en detalle de aplicaciones (si estaba), el actualizador, el servicio del agente, el inventario del servidor, el monitoreo de equipos de red (si había), las unidades de systemd, la configuración y el entorno (con el token), los datos y los archivos del programa. También borra el usuario `lymen-agent`. ## Windows Abrí PowerShell **como administrador**: ```powershell & "$env:ProgramFiles\lymen-agent\actual\lymen-desinstalar.ps1" [-Si] [-ConservarDatos] ``` | Opción | Qué hace | |---|---| | `-Si` | No pregunta antes de seguir. | | `-ConservarDatos` | Deja `C:\ProgramData\lymen-agent` (la cola de datos y las claves del gateway). | Saca el monitoreo en detalle de aplicaciones (si estaba), la tarea del actualizador, el servicio **Agente de Lymen**, la carpeta del programa y la de datos. > El desinstalador de Windows no se probó todavía en un Windows real con el servicio instalado. ## Sacar solo el monitoreo en detalle de aplicaciones Sin desinstalar el agente: - Desde el portal: **Desactivar** cada aplicación (queda sin medirse cuando se reinicie) o **Pausar el monitoreo en detalle en este servidor** como medida de emergencia. Ver [Instrumentación](https://lymen.app/docs/instalacion/instrumentacion-aplicaciones/). - En Linux, completo: `sudo /opt/lymen-agent/instrumentacion/bin/lymen-instrumentacion desinstalar`. Una aplicación que ya estaba medida **sigue cargada hasta que se reinicie**: ningún agente se descarga en caliente. ## Kubernetes ```sh helm uninstall lymen -n lymen ``` Algunos recursos del operador se van recién cuando se quitan sus definiciones (CRD) del cluster. Quitá también la anotación de los pods que habías instrumentado y reinicialos. Ver [Kubernetes](https://lymen.app/docs/instalacion/kubernetes/). ## SDK de sitios y apps Para dejar de medir un sitio o una app: 1. Sacá el SDK del código (el `