Configuración - Laravel
Dónde está la configuración
Todo está en config/ray.php, y cada valor tiene su equivalente en .env.
| Clave | Por defecto | Significado |
|---|---|---|
token, private_key | - | credenciales del proyecto; sin ambas el paquete calla |
url | https://dockray.io | instancia de DockRay |
environment | APP_ENV | columna de entorno en el panel |
release | null | versión de la aplicación desplegada |
sample_rate | 1 | proporción de eventos de error enviados |
traces_sample_rate | 0 | proporción de transacciones enviadas; 0 desactiva la medición |
send_default_user | true | adjunta identificador, correo y nombre del usuario autenticado |
send_default_pii | false | adjunta la dirección IP y el user agent |
ignore_exceptions | [] | clases de excepción que nunca se notifican |
ignore_transactions | horizon*, telescope*, _debugbar* | rutas nunca medidas, patrones como en Request::is() |
options.max_request_body_size | medium | none, small, medium o always |
options.attach_stacktrace | false | pila también en los mensajes simples |
Entornos
Cada entorno debería informar con un nombre inequívoco: production, staging, preview. El nombre es una columna del panel y un filtro de la lista de errores, así que sin él una caída de producción se ve igual que un error provocado en una prueba. Deja el entorno local sin credenciales: sin token ni clave la integración se carga y permanece en silencio, de modo que no necesitas desactivarla con una condición aparte.
Qué dejar fuera de las notificaciones
ignore_exceptions actúa además de la propia lista dontReport de Laravel, así que ValidationException, AuthenticationException y HttpException se omiten sin ninguna configuración. Añade aquí las excepciones que en tu aplicación son un resultado normal y no una avería:
'ignore_exceptions' => [
\App\Exceptions\PaymentDeclinedException::class,
\Illuminate\Session\TokenMismatchException::class,
],La regla es una sola: a DockRay llega aquello sobre lo que alguien debe actuar. Un pago rechazado previsible o un token de formulario caducado forman parte del funcionamiento normal y solo consumen el cupo mensual.
Nombre de las transacciones
Las transacciones se nombran según el patrón de la ruta: GET /orders/{order}, no GET /orders/8123. Así una ruta sigue siendo una fila del panel por muchos identificadores que pasen por ella. Si ves miles de transacciones distintas, casi siempre significa que la ruta está definida sin parámetro.
Contexto de usuario
El middleware adjunta el identificador, el correo y el nombre del usuario autenticado. Desactívalo con RAY_SEND_DEFAULT_USER=false o sustitúyelo por tu propio conjunto de campos:
Ray::setUser(['id' => $account->id, 'username' => $account->slug]);La dirección IP y el user agent solo se adjuntan con RAY_SEND_DEFAULT_PII=true. Es una decisión independiente de la identidad del usuario, porque también afecta a los invitados.
Notificar a mano
use Dock\Ray\Laravel\Ray;
use Dock\Ray\Severity;
Ray::message('La importación nocturna terminó tarde', Severity::warning());Colas y comandos de Artisan
Ambos se ejecutan fuera de la pila de middleware HTTP, así que notifican errores pero no generan transacciones. El hub es un singleton para todo el proceso: un worker de cola de larga vida mantiene un cliente y una conexión en lugar de construirlos en cada trabajo.
Proteger la clave privada
La clave privada es un secreto del proyecto, no un identificador. Guárdala en variables de entorno, en un gestor de secretos o en la configuración del servidor: nunca en el repositorio, en los registros, en una captura de pantalla ni en código que llegue al navegador. Un proyecto puede tener varias claves, así que producción y preproducción deberían tener la suya: cada una se revoca por separado sin interrumpir a las demás. La sospecha de que una clave se ha filtrado ya es motivo suficiente para revocarla y generar otra.