Configuración - PHP

Opciones que conviene conocer

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.

in_app_exclude decide si la pila es legible

Es la opción más subestimada del SDK. Los frames bajo las rutas indicadas en in_app_exclude se marcan como código de terceros, así que el panel muestra el lugar del fallo en tu aplicación y no el frame más profundo dentro de una biblioteca:

init([
    'in_app_exclude' => [__DIR__.'/../vendor'],
]);

Sin ella, todos los errores parecen originarse en vendor/, y lo que viaja a Jira y Notion es justamente la parte significativa de la pila, es decir, los frames marcados como código de la aplicación.

Cuándo salen los eventos

Por defecto, después de la respuesta. Los eventos se encolan durante la petición y se entregan desde un manejador de cierre, cuando PHP-FPM o LiteSpeed ya ha cerrado la conexión con el navegador: un servicio de monitorización lento o inaccesible no retrasa entonces la página para el visitante. Donde el SAPI no puede cerrar la conexión antes (por ejemplo mod_php), la cola se vacía igualmente al cerrar, así que el envío no ocurre en medio de la petición.

La cola guarda como máximo 50 eventos por petición; por encima se descartan los nuevos, ya que los eventos repetidos se agrupan por huella de todos modos. 'send_after_response' => false pasa al envío en línea; en CLI ya es el valor por defecto, porque un worker de larga vida no debería retener informes hasta el fin del proceso.

Transacciones HTTP

use Dock\Ray\Framework\HttpTransaction;

$transaction = HttpTransaction::start('GET /checkout', $url, 'GET');

$transaction->measureHandling('app.handle');

// ... atender la petición ...

$transaction->finish($response->getStatusCode());

El primer argumento es un patrón de ruta, no una dirección concreta: GET /orders/{order}, no GET /orders/8123. De lo contrario la lista de transacciones se deshace en miles de entradas. Las transacciones solo se envían con traces_sample_rate mayor que cero.

Enriquecer los eventos

use Dock\Ray\Breadcrumb;
use function Dock\Ray\{addBreadcrumb, configureScope};

addBreadcrumb(new Breadcrumb(
    Breadcrumb::LEVEL_INFO,
    Breadcrumb::TYPE_DEFAULT,
    'auth',
    'User logged in'
));

configureScope(function (\Dock\Ray\State\Scope $scope) {
    $scope->setTag('feature', 'payments');
    $scope->setUser(['id' => 42, 'email' => 'user@example.com']);
});

Las etiquetas son la forma más económica de filtrar un área de la aplicación en el panel. Define los datos de usuario de forma consciente: son datos personales, y send_default_pii está desactivado por defecto por una razón.

Errores del navegador

Un navegador no puede autenticarse directamente ante DockRay, porque la clave privada del proyecto debe quedarse en el servidor. Por eso el SDK ofrece un script recolector y un normalizador del lado del servidor, y el evento recorre este camino:

navegador  →  tu aplicación  →  DockRay
           (sin clave)       (clave del proyecto)

use Dock\Ray\Browser\BrowserEvent;
use Dock\Ray\Browser\Collector;

// Al renderizar la página: apunta el recolector a tu propio endpoint.
$config = Collector::config(endpoint: '/errors/browser', token: $csrfToken);

// Collector::scriptPath() es el archivo que hay que servir o encolar.

// Al recibir un informe: todo lo que hay en $payload no es de confianza.
$event = BrowserEvent::fromArray($payload, $referer, $userAgent);

if ($event !== null) {
    $hub->captureEvent($event);
}

fromArray() devuelve null para todo lo que no puede convertir en evento y recorta cada cadena que conserva. Las barreras del endpoint las escribes tú: un token CSRF, un límite de tamaño de cuerpo y un límite por IP son exactamente lo que usan nuestros plugins. El recolector también se limita: un informe por error distinto y por vista de página, y diez por vista, descartando ResizeObserver loop y el Script error. de origen cruzado.

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.