README

Jmonitor.io is a SaaS monitoring service that provides insights, alerting and premade dashboards from multiple sources commonly found in PHP web project stack (MySQL, Redis, Apache, Nginx, etc.).

This package provides collectors that gather metrics and send them to Jmonitor.io.

Website: https://jmonitor.io
Symfony integration: https://github.com/jmonitor/jmonitor-bundle

Requirements

PHP 7.4
A project using Composer

Installation

composer require jmonitor/collector

Quick Start

Create a project in jmonitor.io and get your API key.

Then, create a separate script and start collecting metrics:

use Jmonitor\Jmonitor;
use Jmonitor\Collector\Apache\ApacheCollector;

$jmonitor = new Jmonitor('apiKey');

// Add some collectors... see the documentation below for more collectors
$jmonitor->addCollector(new ApacheCollector('https://example.com/server-status'));
$jmonitor->addCollector(new SystemCollector());
// ... 

// send metrics to Jmonitor (see "Scheduling" section)
$jmonitor->collect();

HTTP Client (PSR-18)

You can inject any PSR-18 HTTP client (e.g., Symfony HttpClient via Psr18Client, Guzzle via an adapter, etc.). Example :

composer require symfony/http-client nyholm/psr7

use Symfony\Component\HttpClient\Psr18Client;

$httpClient = ... // create or retrieve your Symfony HttpClient instance
$client = new Psr18Client()->withOptions(...);

$jmonitor = new Jmonitor('apiKey', $client);

Running the collector

Do not call $jmonitor->collect() on every web request. Create a specific script and run it in a separate process.

You are strongly encouraged to run it in a long-running worker process. The response headers include the delay before the next request, which you can use to schedule subsequent runs.
One example is provided in the examples folder.

You also can take a look at the CollectorCommand from the Symfony bundle for a more advanced example:
https://github.com/jmonitor/jmonitor-bundle/blob/master/src/Command/CollectorCommand.php

In production, it is recommended to run the worker under a process manager (e.g. Supervisor or systemd) to ensure it is kept running and restarted if necessary. For practical guidance, you can follow Symfony Messenger's recommendations:
https://symfony.com/doc/current/messenger.html#deploying-to-production

Debugging and Error Handling

Each collector is isolated and executed within a try/catch block.
Use the CollectionResult returned by collect() method to inspect outcomes.

By default, collect() call send metrics to the server.
You can disable this by passing send: false

By default, collect() throws InvalidServerResponseException when the server response status code is >= 400.
You can disable this by passing throwOnFailure: false

use Psr\Http\Message\ResponseInterface;
use Jmonitor\CollectionResult;


/**
 * Send metrics, you can :
 * - Disable throwing an exception on error
 * - Disable sending metrics to the server
 */
$result = $jmonitor->collect(throwOnFailure: false);
// Or disable completely the sending of metrics to the server
$result = $jmonitor->collect(send: false);

/**
 * Use $result to inspect
 */
// Human-readable summary (string)
$conclusion = $result->getConclusion(); 

// List of Exceptions if any (\Throwable[])
$errors = $result->getErrors(); 

// The raw response from jmonitor, if any (ResponseInterface|null)
$response = $result->getResponse(); 

// All metrics collected (mixed[])
$metrics = $result->getMetrics();

Collectors

System
Apache
Nginx
Mysql
Php
Redis
Caddy (+FrankenPHP)

System

Collects system metrics like CPU usage, memory usage, disk usage, etc. Linux only for now. Feel free to open an issue if you need other OS support.

use Jmonitor\Collector\System\SystemCollector;

$collector = new SystemCollector();

// There is actually a "RandomAdapter" you can use on a Windows OS for testing purposes
$collector = new SystemCollector(new RandomAdapter());

Apache

Collects metrics from Apache "mod_status" module. Enable it and expose a status URL. There are some resources to help you with that:
- Apache docs (FR - EN): https://httpd.apache.org/docs/current/mod/mod_status.html.
- Guide (EN): https://statuslist.app/apache/apache-status-page-simple-setup-guide/
- Guide (FR): https://www.blog.florian-bogey.fr/activer-et-configurer-le-server-status-apache-mod_status.html
```
use Jmonitor\Collector\Apache\ApacheCollector;

$collector = new ApacheCollector('http://localhost/server-status');
```
Nginx

Collects metrics from Nginx "stub_status" module. Enable it and expose a status URL. There are some resources to help you with that:
- Nginx docs (EN): https://nginx.org/en/docs/http/ngx_http_stub_status_module.html
- Stackoverflow (EN): https://stackoverflow.com/questions/62269902/nginx-how-to-create-status-with-stub-status
- Guide (EN): https://easyengine.io/tutorials/nginx/status-page/
```
use Jmonitor\Collector\Nginx\NginxCollector;

$collector = new NginxCollector('http://localhost/nginx_status');
```

Mysql

Collects MySQL variables and status. Connect via PDO or Doctrine DBAL (open an issue if you need other drivers, e.g., mysqli).

use Jmonitor\Collector\Mysql\MysqlCollector;
use Jmonitor\Collector\Mysql\Adapter\PdoAdapter;
use Jmonitor\Collector\Mysql\Adapter\DoctrineAdapter;
use Jmonitor\Collector\Mysql\MysqlStatusCollector;
use Jmonitor\Collector\Mysql\MysqlVariablesCollector;
use Jmonitor\Collector\Mysql\MysqlQueriesCountCollector;

// Using PDO
$adapter = new PdoAdapter($pdo); // your \PDO instance

// or using Doctrine DBAL
$adapter = new DoctrineAdapter($connection); // your Doctrine\DBAL\Connection instance

// Mysql has multiple collectors, use the same adapter for all of them
$collector = new MysqlStatusCollector($adapter);
$collector = new MysqlVariablesCollector($adapter);
$collector = new MysqlQueriesCountCollector($adapter, 'your_db_name');

PHP

Collects PHP metrics (loaded extensions, some ini keys, FPM, opcache, etc.).

Important

PHP configuration can differ significantly between CLI and web server.
To collect web‑server context metrics from a CLI script, which is probably what you want to do, expose an HTTP endpoint that returns these metrics as JSON (see below).

Collect CLI-context metrics (current context)

use Jmonitor\Collector\Php\PhpCollector;

$collector = new PhpCollector();

Collect web-server context metrics from CLI
Expose a metrics endpoint (and make sure it is properly secured). You can reuse php-exposer.php from this repo or create your own:

<?php

use Jmonitor\Collector\Php\PhpCollector;

require __DIR__ . '/../vendor/autoload.php';

header('Content-Type: application/json');

echo json_encode((new PhpCollector())->collect(), JSON_THROW_ON_ERROR);

Then, in your CLI script, point the collector to that URL:

use Jmonitor\Collector\Php\PhpCollector;

$collector = new PhpCollector('https://localhost/php-metrics.php');

Redis

Collects Redis metrics from the INFO command.

use Jmonitor\Collector\Redis\RedisCollector;

// Any client supporting INFO: PhpRedis, Predis, RedisArray, RedisCluster, Relay...
$redis = new \Redis([...]);

$collector = new RedisCollector($redis);

Caddy / FrankenPHP

Collects from the Caddy metrics endpoint. It will also gather FrankenPHP metrics if available.

use Jmonitor\Collector\Caddy\CaddyCollector

$collector = new CaddyCollector('http://localhost:2019/metrics');

Integrations

Symfony: https://github.com/jmonitor/jmonitor-bundle

Roadmap

Memcached
Custom metrics collection

Need help?

Open an issue on this repo https://github.com/jmonitor/collector/issues
Open a discussion on https://github.com/orgs/jmonitor/discussions

jmonitor / collector

Maintainers

Details