> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Recorders personalizados de Pulse en paquetes

> Aprende a usar los recorders de Laravel Pulse para agregar en el panel los eventos propios de un paquete. Se explica la suscripción con listen, la agregación con Pulse::record, la configuración de ignore y sample_rate, y el manejo de excepciones.

Laravel Pulse agrega en el panel las solicitudes, consultas, jobs y más. Cuando tu paquete realiza su propio trabajo, un recorder personalizado te permite monitorizar en Pulse el número y la duración de ese trabajo.

Esta guía construye un recorder que se suscribe a un evento que despacha un paquete y registra su número y duración. Para el uso básico de Pulse, consulta [Pulse](https://kawax.biz/es/pulse.md).

> [!NOTE]
>
> Esta guía se basa en el código fuente de Pulse 1.11.0. El evento `ReportGenerated` de los ejemplos es una clase hipotética con fines ilustrativos. En un paquete real, sustitúyelo por tu propio evento.

## Cómo funciona

Cuando un recorder recibe un evento, añade registros al búfer de Pulse. El búfer se guarda por lotes en el momento de la ingesta.

```mermaid theme={null}
flowchart LR
    A["Evento despachado"] --> B["listen llama<br>a record"]
    B --> C["Pulse::record<br>crea un Entry"]
    C --> D["Búfer de Pulse"]
    D --> E["Guardado en la ingesta"]
    E --> F["pulse_entries"]
    E --> G["pulse_aggregates"]
    F --> H["Mostrado en el panel"]
    G --> H
```

## Crear un recorder

Un recorder declara los eventos a los que se suscribe en la propiedad `listen` e implementa el trabajo en el método `record()`. El siguiente ejemplo registra el evento `ReportGenerated` que despacha un paquete. Se supone que el evento tiene las propiedades `$type` y `$durationMs`.

```php theme={null}
<?php

namespace Acme\Reports\Pulse;

use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Recorders\Concerns\Ignores;
use Laravel\Pulse\Recorders\Concerns\Sampling;

class ReportGenerationRecorder
{
    use Ignores, Sampling;

    public array $listen = [
        ReportGenerated::class,
    ];

    public function record(ReportGenerated $event): void
    {
        if ($this->shouldIgnore($event->type) || ! $this->shouldSample()) {
            return;
        }

        Pulse::record(
            type: 'report_generation',
            key: $event->type,
            value: $event->durationMs,
        )->count()->avg()->max();
    }
}
```

Los traits `Ignores` y `Sampling` leen la configuración `ignore` y `sample_rate` descrita más abajo.

## Registrar el recorder en la aplicación

Registra el recorder en el array `recorders` del archivo `config/pulse.php` de la aplicación. Usa el nombre de la clase del recorder como clave y especifica como valor el indicador de activación y la configuración.

```php theme={null}
'recorders' => [
    // Mantén los recorders existentes tal como están
    Acme\Reports\Pulse\ReportGenerationRecorder::class => [
        'enabled' => true,
        'sample_rate' => 1,
        'ignore' => ['/^debug_/'],
    ],
],
```

`PulseServiceProvider` carga `pulse.recorders` y registra los recorders cuando `pulse.enabled` está activado. Un recorder con `enabled` en `false` no se registra. En lugar de reescribir esta configuración automáticamente desde el paquete, es más seguro mostrar el ejemplo de configuración en las instrucciones de instalación.

## Tipos de agregación

`Pulse::record()` devuelve un `Entry`. Al encadenar `count()`, `min()`, `max()`, `sum()` o `avg()`, se guarda el agregado correspondiente en `pulse_aggregates`.

| Método | Valor guardado |
| - | - |
| `count()` | Número |
| `min()` | Valor mínimo |
| `max()` | Valor máximo |
| `sum()` | Suma |
| `avg()` | Media |
| `onlyBuckets()` | Guarda solo los resultados agregados, sin registros individuales en `pulse_entries` |

`min()`, `max()`, `sum()` y `avg()` usan `value` en su cálculo. `count()` por sí solo no necesita `value`.

Cuando un evento se dispara con mucha frecuencia, `onlyBuckets()` reduce el número de filas en `pulse_entries`.

## Guardar un valor de cadena

Cuando quieras guardar una cadena, como el estado más reciente, en lugar de agregar un número, usa `Pulse::set()`. El valor se guarda en la tabla `pulse_values`.

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::set('report_status', $event->type, $event->status);
```

El `value` debe pasarse como `string`.

## Aplazar el trabajo costoso

El closure que se pasa a `Pulse::lazy()` no se ejecuta de inmediato. Se ejecuta cuando Pulse ingiere los datos. Úsalo cuando el registro lleve tiempo y quieras que se ejecute después de enviar la respuesta.

```php theme={null}
Pulse::lazy(function () use ($event) {
    Pulse::record('report_size', $event->type, $event->rows)->sum();
});
```

## Registrar el usuario autenticado

Cuando necesites el identificador del usuario autenticado, usa `Pulse::resolveAuthenticatedUserId()`. Devuelve `null` cuando no hay ningún usuario autenticado.

```php theme={null}
$userId = Pulse::resolveAuthenticatedUserId();
```

## Ignorar, muestrear y filtrar

Usa estas cuatro herramientas para reducir lo que se registra:

* Configuración `ignore`: omite el registro cuando el valor pasado a `shouldIgnore()` coincide con alguna de las expresiones regulares. En el ejemplo anterior, se omiten los eventos cuyo `$event->type` coincide con `/^debug_/`.
* Configuración `sample_rate`: la comprueba `shouldSample()`. `1` registra todos los eventos y `0.1` registra aproximadamente el 10 %.
* `Pulse::ignore()`: desactiva el registro dentro del callback y devuelve el resultado del callback.
* `Pulse::filter()`: recibe cada `Entry` o `Value` antes de guardarlo y solo guarda los elementos para los que devuelve `true`.

## Manejo de excepciones

Pulse envuelve el trabajo de los recorders y la ingesta en `rescue()`. Las excepciones lanzadas dentro de un recorder no llegan a tu aplicación. Si `handleExceptionsUsing()` no está configurado, la excepción se descarta silenciosamente. Para reportar excepciones, configúralo en tu aplicación.

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::handleExceptionsUsing(fn (Throwable $e) => report($e));
```

## Pruebas

Para probar un recorder, puedes despachar el evento, llamar a `Pulse::ingest()` y comprobar la fila guardada. El siguiente ejemplo se ha derivado del código fuente de Pulse y no se ha ejecutado. Asegúrate de que `pulse.enabled` esté activado en tu entorno de pruebas.

```php theme={null}
use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;

it('records ReportGenerated in pulse_entries', function () {
    event(new ReportGenerated(type: 'monthly', durationMs: 120));

    Pulse::ingest();

    $this->assertDatabaseHas('pulse_entries', [
        'type' => 'report_generation',
        'key' => 'monthly',
        'value' => 120,
    ]);
});
```

## Diseño de las claves

`key` es la unidad de agregación. Si usas valores que crecen sin límite, como IDs de usuario o URLs, el volumen de datos aumenta y los agregados se vuelven difíciles de leer. Usa para `key` valores de un conjunto limitado, como tipos de evento o nombres de procesos.


## Related topics

- [Temas avanzados](https://kawax.biz/es/advanced/index.md)
- [Drivers de sesión personalizados en paquetes](https://kawax.biz/es/advanced/package-session-drivers.md)
- [Stores de caché personalizados y contratos en paquetes](https://kawax.biz/es/advanced/package-cache-drivers.md)
- [Canales de notificación personalizados en paquetes y verificación de la entrega](https://kawax.biz/es/advanced/package-notification-channels.md)
- [UserProvider personalizado en paquetes](https://kawax.biz/es/advanced/package-user-providers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.