Elixir
El paquete collector reporta los errores de tu aplicación Elixir o Phoenix. Esta página describe la versión 0.5.4.
Instalación
Agrega la dependencia en mix.exs:
def deps do
[
{:collector, ">= 0.5.4"}
]
end
Dale a la aplicación desplegada el DSN del proyecto (está en su Puesta en marcha) en la variable de entorno COLLECTOR_DSN. O, para tomarlo de otro lado, en config/runtime.exs:
config :collector, dsn: System.get_env("MI_COLLECTOR_DSN")
Eso es todo. Desde ahora los errores se reportan solos: controladores, LiveViews, GenServers, Tasks, cualquier proceso. También los trabajos de Oban que fallan, cuando la aplicación usa Oban (no los que devuelven {:cancel, _} o {:discard, _}). Las excepciones que Plug convierte en un 4xx, como Ecto.NoResultsError, no son errores de tu código y no se reportan. Una caída que llega por el log trae esa línea como mensaje, y sus metadatos simples y su dominio como etiquetas.
Además manda una señal al arrancar y cada hora, para que Collector sepa que la aplicación está arriba aunque no falle nada, con su versión, su entorno y la del SDK.
Sin DSN no se manda nada, así que desarrollo y pruebas quedan en silencio: no exportes COLLECTOR_DSN ahí.
Comprobar que funciona
MIX_ENV=prod mix collector.test
Imprime el identificador del evento si Collector lo aceptó, o qué salió mal (sin DSN, clave rechazada, Collector inalcanzable), y en ese caso termina con 1. En una release, donde no hay tareas de mix:
bin/mi_app rpc 'IO.inspect(Collector.test_event())'
La solicitud y el usuario
Agrega el plug a tu endpoint para ver la solicitud en la que ocurrió cada error. Las credenciales, como las cookies, nunca se mandan:
# lib/mi_app_web/endpoint.ex
plug Collector.Plug
Y di quién tuvo el error, por su identificador, nunca por su correo:
Collector.set_user(current_user.id)
Hazlo en el plug donde lees la sesión y en el on_mount de tus LiveViews, porque cada LiveView es su propio proceso.
Las líneas de código en una release
Collector muestra las líneas alrededor de cada marco de tu código. Las releases no llevan los archivos fuente, así que empaquétalos justo antes de construir la release:
MIX_ENV=prod mix collector.package_source
MIX_ENV=prod mix release
En un Dockerfile es una línea antes de mix release.
Los marcos de tus dependencias aparecen como deps/<paquete>/…, sin código alrededor: solo se empaquetan las fuentes de tu aplicación.
Registros, solicitudes e inicios de sesión
Para que Collector detecte ataques (abuso de inicios de sesión, escaneos, volumen inusual), la aplicación también puede mandar lo que registra, cada solicitud que atiende y sus inicios de sesión. Hace falta una clave de servidor, un secreto distinto del DSN. Defínela junto al DSN:
COLLECTOR_SERVER_KEY=clts_…
Con ella, sin ningún otro cambio, Collector recibe:
- las líneas de log desde
:info, con los valores simples de sus metadatos (un conn, un struct o un mapa se dejan afuera, porque pueden llevar cookies). Las líneas propias de Phoenix, "GET /x" y "Sent 200", también se dejan afuera: cada solicitud ya es un registro; - una entrada por cada solicitud que atiende un endpoint de Phoenix, incluidas las que fallan o no coinciden con ninguna ruta (en una aplicación Plug sin Phoenix, agrega
plug Collector.Plug); - los inicios de sesión, cuando los reportas:
Collector.sign_in(:failed, email, conn: conn, method: :password)
Collector.sign_in(:succeeded, email, conn: conn, method: :password, user: user.id)
En una aplicación hecha con mix phx.gen.auth, llama a Collector.PhxGenAuth.sign_in(conn, user_params, user_or_nil) en las dos ramas de UserSessionController.create; su documentación muestra dónde.
Detrás de un balanceador de carga, enumera sus redes para que la dirección del cliente se lea de X-Forwarded-For (que solo se cree si viene de ellas). Detectar ataques depende de eso:
config :collector,
logs: [
trusted_proxies: ["10.0.0.0/8"],
skip_paths: ["/health"], # exacta, o un prefijo como "/up/*"
level: :info, # el nivel más bajo que se manda
lines: true, # false: sin líneas de log
requests: true, # false: sin solicitudes
sign_ins: true # false: sin inicios de sesión
]
Un error que ocurre mientras se atiende una solicitud lleva su identificador (el de Plug.RequestId), el mismo que sus registros, así el problema enlaza a ellos.
logs: false lo apaga todo. Los segmentos de ruta de parámetros llamados como token, password o secret se mandan con su nombre, para que un enlace de inicio de sesión no quede guardado. Collector guarda lo que se manda durante un año, tal cual: lo que la aplicación registra es responsabilidad suya. Los registros salen en lotes cada segundo, en segundo plano; cuando una release se detiene, manda lo que queda, esperando hasta 5 segundos.
Reportar a mano
try do
charge!(order)
rescue
e ->
Collector.capture_exception(e, stacktrace: __STACKTRACE__)
{:error, :payment_failed}
end
Collector.capture_message("La pasarela de pagos está lenta", level: :warning)
Opciones
| Opción | Valor de entrada | |
|---|---|---|
:dsn | COLLECTOR_DSN | https://clt_…@app.clt.chrom.ar: dónde está Collector más la clave del proyecto. Sin él no se manda nada. |
:key, :endpoint | COLLECTOR_KEY, https://app.clt.chrom.ar | Las dos mitades del DSN, por separado. Un DSN gana sobre ambas. |
:environment | El entorno de Mix con el que se construyó | prod, staging, … |
:release | RELEASE_VSN | Versión o sha de git. |
:in_app | Las aplicaciones de tu proyecto | Qué aplicaciones cuentan como "tu código". Decide cómo se agrupan los errores. |
:server_key | COLLECTOR_SERVER_KEY | La clave secreta con la que se mandan los registros. Definirla enciende los registros. |
:logs | ver arriba | Ajusta los registros, o false para apagarlos. |
:repos | ninguno | Prefijos de telemetría de tus repos de Ecto, como [[:mi_app, :repo]], para anotar las consultas en lo que pasó antes del error, con su duración y lo que esperaron por una conexión. |
Cómo se comporta
Los eventos salen en segundo plano, de a uno, desde una cola acotada (pasados 1000, se descarta el más viejo), así que un Collector lento o caído nunca hace lenta tu aplicación. Los envíos que fallan se reintentan con el mismo identificador, así que nada se cuenta dos veces; cuando Collector pide bajar el ritmo, lo baja. Las señales comparten esa cola, con a lo sumo una esperando, y tienen su propio límite: que frenen las señales nunca frena los errores.