Saltar al contenido principal

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ónValor de entrada
:dsnCOLLECTOR_DSNhttps://clt_…@app.clt.chrom.ar: dónde está Collector más la clave del proyecto. Sin él no se manda nada.
:key, :endpointCOLLECTOR_KEY, https://app.clt.chrom.arLas dos mitades del DSN, por separado. Un DSN gana sobre ambas.
:environmentEl entorno de Mix con el que se construyóprod, staging, …
:releaseRELEASE_VSNVersión o sha de git.
:in_appLas aplicaciones de tu proyectoQué aplicaciones cuentan como "tu código". Decide cómo se agrupan los errores.
:server_keyCOLLECTOR_SERVER_KEYLa clave secreta con la que se mandan los registros. Definirla enciende los registros.
:logsver arribaAjusta los registros, o false para apagarlos.
:reposningunoPrefijos 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.