Configuración - Drupal
Dónde está la configuración
Administración → Configuración → Desarrollo → DockRay, es decir /admin/config/development/dock-ray. El formulario muestra el estado actual de la configuración, el resultado de la última prueba y un botón Enviar evento de prueba que comprueba la conexión sin salir de la página.
Origen de la configuración
Origen de la configuración decide cómo conviven una sobrescritura en settings.php y los valores guardados en el formulario:
| Origen | Comportamiento |
|---|---|
| Auto (predeterminado) | una clave definida en settings.php gana para su campo, el resto viene del formulario. Es exactamente como se comportaba el módulo antes de existir este campo: el settings.php de nadie deja de funcionar. |
| Solo settings.php | el token, la clave y la URL del formulario se ignoran aunque estén rellenos; un campo sin clave correspondiente vuelve a su valor predeterminado, no al formulario |
| Solo este formulario | settings.php se ignora aunque defina una sobrescritura: útil cuando un archivo de ajustes compartido fija un proyecto por defecto y un sitio necesita el suyo |
Los campos bloqueados se muestran con el valor que realmente rige y una nota que lo explica. Siguen enviando ese valor con el resto del formulario: un elemento deshabilitado de la Form API entrega #default_value en lugar de omitir la clave, así que guardar con un campo bloqueado no puede vaciar lo guardado.
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.
Cómo funciona la notificación
El módulo registra un canal de logger. Drupal ya convierte cada error de PHP y cada excepción no capturada en una entrada de registro, así que un solo canal lo cubre todo, y no hay un segundo manejador de errores compitiendo con el del núcleo.
minimum_level es una severidad RFC 5424: 3 (Error) informa de errores, críticos, alertas y emergencias, e ignora avisos y notices. Una entrada que lleva una excepción se informa con su pila de llamadas; el resto se convierte en mensajes.
| Nivel | Abarca |
|---|---|
2 Critical | solo fallos críticos y superiores |
3 Error | recomendado: errores y todo lo más grave |
4 Warning | también los avisos: en un sitio grande, muchos más eventos |
Transacciones
El tiempo de las peticiones solo se mide cuando traces_sample_rate es mayor que cero. La transacción se abre en kernel.request y se cierra en kernel.terminate. Nada sale durante la petición: los eventos se encolan y salen desde un manejador de cierre una vez enviada la respuesta, así que un panel lento nunca retrasa una página.
Errores de JavaScript
Desactivado por defecto. Al activarlo, el módulo carga en las páginas no administrativas un recolector que informa de window.onerror y de los rechazos de promesas no gestionados al sitio, no al panel: un navegador no puede autenticarse ante DockRay sin la clave privada, y esta quedaría legible en el código de la página.
Los informes van a POST /dock-ray/browser-error, con un límite de 16 kB y una limitación de 20 por dirección IP y hora a través del servicio flood de Drupal. El recolector se sirve desde /dock-ray/collector.js, porque el SDK vive en el directorio vendor/ del proyecto, fuera del docroot en la mayoría de instalaciones. Cada petición responde 202 con independencia de si se aceptó el informe.
Notificar a mano
try {
$this->import();
}
catch (\Throwable $exception) {
\Drupal::service('dock_ray.hub')->captureException($exception);
throw $exception;
}\Drupal::logger('my_module')->error(...) también llega a DockRay, por el mismo canal que todo lo demás, así que tu propio código no necesita una integración aparte.
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.