PHP SDK

Monitor Laravel Queues, Symfony Messenger, or any custom PHP queue system with the jobviz/agent Composer package. PHP 8.1+ required.

Laravel Queues Auto-discovery, zero config

Symfony Messenger EventSubscriber integration

Custom / MultiProvider Any PHP queue system

1. Install

Install via Composer. Requires PHP 8.1+.

terminal
 composer require jobviz/agent 

Prerequisites

PHP 8.1+
A Jobviz account — sign up free
Optional: laravel/framework 10+ or symfony/messenger 6.0+ (depending on your queue system)

2. Laravel Queues

The Laravel provider auto-discovers via the service provider. Just add your API key to .env and you're done. Works with all Laravel queue drivers (Redis, SQS, database, Beanstalkd, etc.).

Setup Zero config (auto-discovery)

Peer dependency laravel/framework 10+

Events captured waiting, active, completed, failed, delayed

Environment setup

.env
 // config/jobviz.php is auto-published via the service provider.
// Set your API key in .env:

// .env
JOBVIZ_API_KEY=your-api-key
JOBVIZ_ENV=production 

Configuration

config/jobviz.php
 // config/jobviz.php
return [
    'api_key'    => env('JOBVIZ_API_KEY'),
    'endpoint'   => env('JOBVIZ_ENDPOINT', 'https://app.jobviz.dev/api/v1/events'),
    'env'        => env('JOBVIZ_ENV', env('APP_ENV', 'production')),

    // Only monitor specific queues (null = all)
    'queues'     => null,

    // Batching
    'batch_size'      => 100,
    'max_buffer_size' => 10000,

    // Data capture
    'capture_input'        => true,
    'capture_stack_traces' => true,

    // Redact sensitive keys (true = defaults, or pass an array)
    'redact_keys' => ['password', 'token', 'secret', 'credit_card'],

    // Debug mode
    'debug' => env('JOBVIZ_DEBUG', false),
]; 

Note: Publish the config with php artisan vendor:publish --tag=jobviz-config. The service provider auto-starts the agent and flushes events on application termination.

3. Symfony Messenger

The Symfony provider implements EventSubscriberInterface, so it can be registered directly with Symfony's event dispatcher. Supports all transports (AMQP, Redis, Doctrine, InMemory, etc.).

Setup EventSubscriber tag

Peer dependency symfony/messenger 6.0+

Events captured waiting, active, completed, failed, delayed

Standalone setup

src/Kernel.php
 use Jobviz\Agent\JobvizAgent;
use Jobviz\Agent\Config;
use Jobviz\Agent\Providers\SymfonyMessengerProvider;

// 1. Create the provider
$provider = new SymfonyMessengerProvider(
    transports: ['async', 'failed'],   // null = all transports
    captureInput: true,
    captureStackTraces: true,
);

// 2. Register as an event subscriber
$eventDispatcher->addSubscriber($provider);

// 3. Start the agent
$config = new Config(
    apiKey: $_ENV['JOBVIZ_API_KEY'],
    endpoint: 'https://app.jobviz.dev/api/v1/events',
    env: 'production',
);
$agent = new JobvizAgent($config, $provider);
$agent->start(); 

Symfony DI (services.yaml)

config/services.yaml
 # config/services.yaml
services:
  Jobviz\Agent\Providers\SymfonyMessengerProvider:
    arguments:
      $transports: null          # monitor all transports
      $captureInput: true
      $captureStackTraces: true
    tags:
      - { name: kernel.event_subscriber }

  Jobviz\Agent\Config:
    arguments:
      $apiKey: '%env(JOBVIZ_API_KEY)%'
      $endpoint: 'https://app.jobviz.dev/api/v1/events'
      $env: '%kernel.environment%'

  Jobviz\Agent\JobvizAgent:
    arguments:
      - '@Jobviz\Agent\Config'
      - '@Jobviz\Agent\Providers\SymfonyMessengerProvider'
    calls:
      - [start] 

Tip: The provider hooks into WorkerMessageReceivedEvent, WorkerMessageHandledEvent, WorkerMessageFailedEvent, WorkerMessageRetriedEvent, and SendMessageToTransportsEvent. It extracts retry counts from RedeliveryStamp and message IDs from TransportMessageIdStamp automatically.

4. Custom provider

Implement the QueueProviderInterface to integrate any PHP queue system. Two methods: connect(Closure $push) and disconnect().

src/MyQueueProvider.php
 use Jobviz\Agent\Providers\QueueProviderInterface;
use Jobviz\Agent\JobEvent;
use Jobviz\Agent\EventType;
use Closure;

class MyQueueProvider implements QueueProviderInterface
{
    private ?Closure $push = null;

    public function connect(Closure $push): void
    {
        $this->push = $push;
        // Subscribe to your queue system here
    }

    public function disconnect(): void
    {
        $this->push = null;
        // Clean up connections
    }

    // Call this when a job event occurs
    private function emit(JobEvent $event): void
    {
        if ($this->push !== null) {
            ($this->push)($event);
        }
    }
} 

5. MultiProvider

Use MultiProvider to monitor multiple queue backends under a single Jobviz agent. All events appear in the same dashboard.

bootstrap.php
 use Jobviz\Agent\JobvizAgent;
use Jobviz\Agent\Config;
use Jobviz\Agent\Providers\MultiProvider;
use Jobviz\Agent\Providers\LaravelQueueProvider;
use Jobviz\Agent\Providers\SymfonyMessengerProvider;

$provider = new MultiProvider([
    new LaravelQueueProvider(events: app('events')),
    new SymfonyMessengerProvider(),
    new MyCustomProvider(),
]);

$config = new Config(apiKey: $_ENV['JOBVIZ_API_KEY']);
$agent = new JobvizAgent($config, $provider);
$agent->start(); 

6. In-job logging

Use Jobviz::log() inside your job handlers to attach structured log entries that appear as a timeline in the dashboard.

app/Jobs/SendWelcomeEmail.php
 use Jobviz\Agent\Jobviz;

// Inside your job's handle() method
class SendWelcomeEmail implements ShouldQueue
{
    public function handle(): void
    {
        Jobviz::log($this->job, 'Fetching template');

        $template = $this->fetchTemplate();
        Jobviz::log($this->job, 'Template fetched', ['id' => $template->id]);

        Mail::to($this->user)->send(new WelcomeMail($template));
        Jobviz::log($this->job, 'Email sent');
    }
} 

7. Deployment tracking

Track deployments to correlate failures with code changes. Jobviz overlays deploy markers on your dashboard timeline.

deploy.php
 use Jobviz\Agent\Jobviz;

// In a deploy script or boot sequence
Jobviz::trackDeployment([
    'version'    => '1.4.2',
    'commitHash' => 'abc123f',
]); 

8. Configuration reference

All available Config constructor parameters and their defaults.

Option	Type	Default	Description
`apiKey`	`string`	required	Your Jobviz API key
`endpoint`	`string`	`https://app.jobviz.dev/api/v1/events`	API endpoint URL
`env`	`?string`	`null`	Environment tag (production, staging, etc.)
`queues`	`?string[]`	`null`	Queue names to monitor (null = all)
`batchSize`	`int`	`100`	Events per batch
`maxBufferSize`	`int`	`10000`	Max buffered events before dropping oldest
`captureInput`	`bool`	`true`	Capture job input/payload data
`captureStackTraces`	`bool`	`true`	Capture error stack traces
`redactKeys`	`bool \| string[]`	`false`	Redact sensitive fields from job data
`debug`	`bool`	`false`	Enable debug logging

9. Graceful shutdown

Call $agent->stop() to flush pending events and cleanly disconnect before your process exits.

shutdown
 // Laravel: handled automatically via the service provider.

// Standalone: flush before exit
register_shutdown_function(function () use ($agent) {
    $agent->stop();
});

// Or with Symfony kernel.terminate
$kernel->addListener('kernel.terminate', function () use ($agent) {
    $agent->stop();
}); 

Features

Automatic event capture

Hooks into Laravel's event dispatcher and Symfony's EventSubscriber system. No manual instrumentation needed.

Sensitive data redaction

Built-in recursive redactor strips passwords, tokens, and secrets from job payloads before they leave your server.

Batched HTTP transport

Events are buffered and sent in batches with automatic retry (4 attempts, exponential backoff) and rate-limit handling.

Trace ID correlation

Automatically extracts traceId and correlationId from job payloads for cross-service correlation.

Need help getting set up?

Open an issue on GitHub or ask in our Discord community — we're happy to help.

Get started free