README

A production-ready Laravel wrapper for the Netdata API v3 PHP SDK. Provides facade, multi-connection support, caching, artisan commands, monitoring, health checks, and more.

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x, or 13.x
• davit-vardanyan/netdata-php ^1.0

Installation

composer require davit-vardanyan/netdata-laravel

The package auto-discovers its service provider and facade.

Configuration

Publish the configuration file:

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

Set your environment variables in .env:

NETDATA_TOKEN=your-bearer-token
NETDATA_BASE_URL=https://registry.my-netdata.io

The base URL defaults to https://registry.my-netdata.io. Point it at any Netdata agent or Cloud instance — for example, a local agent at http://localhost:19999.

Multi-Connection Setup

// config/netdata.php
'connections' => [
    'default' => [
        'token' => env('NETDATA_TOKEN'),
        'base_url' => env('NETDATA_BASE_URL', 'https://registry.my-netdata.io'),
        'timeout' => (int) env('NETDATA_TIMEOUT', 30),
        'read_timeout' => (int) env('NETDATA_READ_TIMEOUT', 60),
        'retry' => [
            'max_attempts' => (int) env('NETDATA_RETRY_MAX', 3),
            'base_delay_ms' => (int) env('NETDATA_RETRY_DELAY', 1000),
        ],
    ],
    'local' => [
        'token' => '',
        'base_url' => 'http://localhost:19999',
    ],
],

Quick Start

use DavitVardanyan\NetdataLaravel\Facades\Netdata;

$nodes = Netdata::nodes()->list();
$cpuData = Netdata::data()->cpu();
$alerts = Netdata::alerts()->list();

Usage

All 13 Resource Accessors

use DavitVardanyan\NetdataLaravel\Facades\Netdata;

Netdata::data()->cpu();              // CPU metrics (last 10 min)
Netdata::data()->memory();           // Memory metrics
Netdata::data()->disk();             // Disk metrics
Netdata::data()->network();          // Network metrics
Netdata::data()->query($request);    // Custom data query via DataQueryRequest
Netdata::weights()->query($request); // Metric weight/correlation analysis
Netdata::contexts()->list();         // Browse metric contexts
Netdata::nodes()->list();            // List monitored nodes
Netdata::alerts()->list();           // Active alert summaries
Netdata::functions()->list();        // Agent functions
Netdata::info()->get();              // Agent info (version, hostname, OS)
Netdata::search()->query('cpu');     // Search across metrics
Netdata::badges()->svg('system.cpu');// Generate badge SVGs
Netdata::allMetrics()->get();        // Export all metrics (Prometheus format)
Netdata::config()->tree();           // Agent configuration tree
Netdata::streamPath()->get();        // Streaming path info
Netdata::claim()->info();            // Agent claim status

Dependency Injection

use DavitVardanyan\NetdataLaravel\NetdataManager;

public function __construct(private NetdataManager $netdata) {}

$this->netdata->nodes()->list();
$this->netdata->connection('local')->nodes()->list();

Multiple Connections

Netdata::connection('local')->nodes()->list();
Netdata::connection('production')->alerts()->list();

Caching

Caching is enabled by default. Configure per-resource TTLs in config/netdata.php:

'cache' => [
    'enabled' => true,
    'store' => null, // uses default cache store
    'prefix' => 'netdata',
    'ttl' => [
        'nodes' => 300,      // 5 minutes
        'contexts' => 1800,  // 30 minutes
        'info' => 3600,      // 1 hour
        'functions' => 1800, // 30 minutes
        'data' => 60,        // 1 minute
        'alerts' => 30,      // 30 seconds
    ],
],

Resources like weights, search, badges, allMetrics, config, streamPath, and claim bypass the cache automatically.

Flush cache programmatically:

Netdata::flushCache();              // Flush all
Netdata::flushCache('nodes');       // Flush nodes only

Artisan Commands

php artisan netdata:test                          # Test connectivity
php artisan netdata:nodes                         # List monitored nodes
php artisan netdata:alerts                        # List active alerts
php artisan netdata:alerts --status=critical      # Filter by status
php artisan netdata:health                        # System health overview (CPU, RAM, disk, network)
php artisan netdata:metrics system.cpu            # Query metric data
php artisan netdata:metrics system.cpu --after=-3600 --points=60
php artisan netdata:contexts                      # List metric contexts
php artisan netdata:contexts --filter=system      # Filter contexts
php artisan netdata:info                          # Agent information
php artisan netdata:functions                     # List agent functions
php artisan netdata:functions --execute=processes # Execute a function

All commands support --connection=NAME and --json flags.

Monitoring

Alert Polling

Polls for new alerts and dispatches AlertTriggered events. Alerts are deduplicated by name and chart.

// config/netdata.php
'monitoring' => [
    'alerts' => [
        'enabled' => true,
        'poll_interval' => 60,
        'dispatch_events' => true,
        'notify' => [
            'enabled' => true,
            'channels' => ['mail', 'slack'],
            'recipients' => ['admin@example.com'],
        ],
    ],
],

Node Status Monitoring

Detects nodes going online/offline and dispatches NodeWentOffline / NodeCameOnline events.

'monitoring' => [
    'nodes' => [
        'enabled' => true,
        'poll_interval' => 120,
        'dispatch_events' => true,
    ],
],

Threshold Rules

Monitor specific metrics against thresholds. Supports >, >=, <, <=, ==, != operators with optional duration-based breach tracking.

'monitoring' => [
    'thresholds' => [
        'enabled' => true,
        'rules' => [
            [
                'context' => 'system.cpu',
                'dimension' => 'user',
                'operator' => '>',
                'value' => 90,
                'duration' => 300, // seconds the threshold must be breached
                'severity' => 'critical',
            ],
        ],
    ],
],

Events

Listen to monitoring events in your EventServiceProvider or anywhere Laravel events are registered:

use DavitVardanyan\NetdataLaravel\Events\AlertTriggered;
use DavitVardanyan\NetdataLaravel\Events\NodeWentOffline;
use DavitVardanyan\NetdataLaravel\Events\NodeCameOnline;
use DavitVardanyan\NetdataLaravel\Events\MetricThresholdExceeded;

Event::listen(AlertTriggered::class, function (AlertTriggered $event) {
    Log::warning("Alert: {$event->alert->name} [{$event->alert->status->value}]");
});

Event::listen(NodeWentOffline::class, function (NodeWentOffline $event) {
    Log::error("Node offline: {$event->node->name}");
});

Event::listen(MetricThresholdExceeded::class, function (MetricThresholdExceeded $event) {
    Log::critical("{$event->context}.{$event->dimension} {$event->operator} {$event->threshold} (value: {$event->value})");
});

Health Check

use DavitVardanyan\NetdataLaravel\Health\NetdataHealthCheck;

$check = app(NetdataHealthCheck::class);
$result = $check->run();
// $result->status: Status::Ok, Status::Warning, or Status::Failed
// $result->message: Human-readable description

// Check a specific connection
$result = $check->connection('local')->run();

Middleware

Log request performance with the built-in middleware:

// In a route group or kernel
use DavitVardanyan\NetdataLaravel\Middleware\NetdataPerformanceMiddleware;

Route::middleware(NetdataPerformanceMiddleware::class)->group(function () {
    // ...
});

Testing

Use the FakesNetdata trait in your Pest or PHPUnit tests:

use DavitVardanyan\NetdataLaravel\Testing\FakesNetdata;

uses(FakesNetdata::class);

test('dashboard shows node list', function () {
    $fake = $this->fakeNetdata();
    $fake->fakeNodes([
        ['nd' => 'abc', 'nm' => 'web-1', 'v' => 'v2.0.0'],
    ]);

    $this->get('/dashboard')->assertOk();

    $fake->assertCalled('/api/v3/nodes');
});

Running the Package Tests

vendor/bin/pest              # Run tests (63 tests, 136 assertions)
vendor/bin/phpstan analyse   # Static analysis (level 8)
vendor/bin/pint --test       # Code style check (Laravel preset)

Releasing

To create a new tag and GitHub release entirely from the command line:

# 1. Bump version in composer.json, update CHANGELOG.md, commit
git add composer.json CHANGELOG.md
git commit -m "chore: release v1.x.x"

# 2. Create an annotated tag
git tag -a v1.x.x -m "Release v1.x.x"

# 3. Push the commit and the tag
git push origin main
git push origin v1.x.x

# 4. Create the GitHub release (requires the gh CLI)
gh release create v1.x.x \
  --title "v1.x.x" \
  --notes "$(sed -n '/^## \[1.x.x\]/,/^## \[/p' CHANGELOG.md | head -n -1)"

The sed command above extracts the relevant CHANGELOG section automatically as release notes. Install the gh CLI with brew install gh and authenticate once with gh auth login.

License

MIT License. See LICENSE for details.