README

A PHP/Laravel package to send errors, logs, and heartbeats to the Monitoring Monolith.

Installation

Laravel

composer require binary-hype/monitoring

The package uses Laravel's auto-discovery, so the service provider is registered automatically.

Publish the configuration file:

php artisan vendor:publish --tag=monitor-config

Vanilla PHP

composer require binary-hype/monitoring

Manual initialization required (see Vanilla PHP Usage).

Configuration

Add these to your .env file:

MONITOR_API_KEY=your-project-api-key-here
MONITOR_ENDPOINT=https://monitoring.binary-hype.com/api/v1
MONITOR_ENABLED=true
MONITOR_ENVIRONMENT=production

Configuration Options

Option	Default	Description
`api_key`	`null`	Your project's API key from the monitoring dashboard
`endpoint`	`https://monitoring.binary-hype.com/api/v1`	The monitoring server URL
`enabled`	`true`	Toggle monitoring on/off
`environment`	`APP_ENV`	Environment name for error tagging
`capture_user`	`true`	Include authenticated user info
`capture_request`	`true`	Include request data
`capture_session`	`false`	Include session data
`sample_rate`	`1.0`	Percentage of errors to capture (0.0 to 1.0)
`queue.enabled`	`true`	Send reports via queue
`queue.connection`	`redis`	Queue connection to use
`queue.queue`	`monitor`	Queue name

Ignored Exceptions

By default, these exceptions are not reported:

Illuminate\Validation\ValidationException
Symfony\Component\HttpKernel\Exception\NotFoundHttpException
Illuminate\Auth\AuthenticationException
Illuminate\Session\TokenMismatchException

Filtered Fields

Sensitive fields are automatically redacted from reports:

password, password_confirmation
secret, token, api_key
credit_card, card_number, cvv

Usage

Automatic Exception Capture

Once installed and configured, exceptions are captured automatically. No code changes needed.

Manual Error Reporting

use BinaryHype\Monitoring\Facades\Monitor;

// Report an exception
try {
    // risky code
} catch (\Exception $e) {
    Monitor::captureException($e);
}

// Report with additional context
Monitor::captureException($e, [
    'order_id' => 123,
    'action' => 'checkout',
]);

// Report a custom message
Monitor::captureMessage('Something unexpected happened', 'warning', [
    'custom_context' => 'value',
]);

Adding Context

use BinaryHype\Monitoring\Facades\Monitor;

// Set user context (if not using Laravel's auth)
Monitor::setUser([
    'id' => 123,
    'email' => 'user@example.com',
    'name' => 'John Doe',
]);

// Add custom context to all future reports
Monitor::setContext('order', [
    'order_id' => 456,
    'total' => 99.99,
]);

// Add tags
Monitor::setTags([
    'feature' => 'checkout',
    'version' => '2.1.0',
]);

Log Channel

Add the monitor channel to config/logging.php:

'channels' => [
    // ... other channels

    'monitor' => [
        'driver' => 'monitor',
        'level' => env('MONITOR_LOG_LEVEL', 'error'),
    ],
],

Use it directly:

Log::channel('monitor')->error('Payment failed', [
    'order_id' => 123,
    'reason' => 'Insufficient funds',
]);

Or add it to your stack:

'stack' => [
    'driver' => 'stack',
    'channels' => ['daily', 'monitor'],
],

Vanilla PHP Usage

<?php

require 'vendor/autoload.php';

use BinaryHype\Monitoring\Monitor;

// Initialize the client
$monitor = new Monitor([
    'api_key' => 'your-api-key',
    'endpoint' => 'https://monitoring.binary-hype.com/api/v1',
    'environment' => 'production',
]);

// Set as global exception handler
$monitor->registerExceptionHandler();
$monitor->registerErrorHandler();
$monitor->registerShutdownHandler();

// Or capture manually
try {
    // risky code
} catch (\Exception $e) {
    $monitor->captureException($e);
}

Heartbeat Endpoint

The package automatically registers a health check endpoint that the monitoring server pings.

Endpoint: GET /_monitor/health

Response:

{
  "status": "ok",
  "timestamp": "2026-02-01T12:00:00Z",
  "php_version": "8.3.0",
  "laravel_version": "12.0.0",
  "environment": "production",
  "checks": {
    "database": "ok",
    "cache": "ok"
  }
}

Configure Health Checks

// config/monitor.php

'heartbeat' => [
    'enabled' => true,
    'route' => '/_monitor/health',
    'middleware' => [], // Add middleware if needed
    'checks' => [
        'database' => true,
        'cache' => true,
        'queue' => false,
    ],
],

Artisan Commands

Test Integration

php artisan monitor:test

Validates configuration, sends a test error, and verifies the heartbeat endpoint.

Example output:

Testing Monitoring Integration...

✓ Configuration valid
✓ API endpoint reachable (https://monitoring.binary-hype.com/api/v1)
✓ Test error sent successfully (ID: err_abc123)
✓ Heartbeat endpoint accessible (/_monitor/health)

All tests passed! Your integration is working correctly.

API Reference

Monitor Facade

Method	Description
`captureException(Throwable $e, array $context = [])`	Capture and report an exception
`captureMessage(string $message, string $level, array $context = [])`	Report a custom message
`setUser(array $user)`	Set user context (`id`, `email`, `name`)
`setContext(string $key, array $data)`	Add custom context data
`setTags(array $tags)`	Add tags to all future reports
`flush()`	Force send all queued reports
`isEnabled()`	Check if monitoring is enabled

Troubleshooting

Errors not appearing in dashboard

Check that MONITOR_ENABLED=true
Verify your MONITOR_API_KEY is correct
Ensure the environment is not in ignored_environments
Check that the exception type is not in ignored_exceptions
Run php artisan monitor:test

Queue jobs failing

Ensure Redis is running
Check queue worker is processing the monitor queue
Review failed jobs: php artisan queue:failed

Timeout errors

Increase the timeout config value
Enable queue-based reporting
Check network connectivity to monitoring server

Testing

composer test

Requirements

PHP ^8.2
Laravel ^10.0 | ^11.0 | ^12.0 (for Laravel integration)
Guzzle ^7.0

License

MIT License. See LICENSE for details.

binary-hype / monitoring

Maintainers

Details