PHPackages                             cacheerphp/monitor - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. cacheerphp/monitor

ActiveLibrary[Logging & Monitoring](/categories/logging)

cacheerphp/monitor
==================

Dashboard and telemetry reporter for CacheerPHP.

v1.1.0(2mo ago)111↓92.9%MITPHPPHP >=8.1

Since Apr 3Pushed 2mo agoCompare

[ Source](https://github.com/CacheerPHP/monitor)[ Packagist](https://packagist.org/packages/cacheerphp/monitor)[ RSS](/packages/cacheerphp-monitor/feed)WikiDiscussions main Synced today

READMEChangelog (7)Dependencies (4)Versions (14)Used By (0)

Cacheer Monitor
===============

[](#cacheer-monitor)

 **Real-time dashboard and telemetry for [CacheerPHP](https://github.com/cacheerphp/CacheerPHP). Instruments your cache layer automatically — no code changes required.**

 [![Latest Version](https://camo.githubusercontent.com/bacd6b939559e31c500fd89d19544fcc204914d5fec63e694f1508276a364c9b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f636163686565727068702f6d6f6e69746f722e7376673f7374796c653d666f722d7468652d626164676526636f6c6f723d626c7565)](https://github.com/cacheerphp/monitor/releases) [![PHP Version](https://camo.githubusercontent.com/cc97ee5ee03d38e4d63000f237f502885b2742d41fc5357ac7fe04dd0d89b09a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f636163686565727068702f6d6f6e69746f722f5048503f7374796c653d666f722d7468652d626164676526636f6c6f723d626c7565)](https://camo.githubusercontent.com/cc97ee5ee03d38e4d63000f237f502885b2742d41fc5357ac7fe04dd0d89b09a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f636163686565727068702f6d6f6e69746f722f5048503f7374796c653d666f722d7468652d626164676526636f6c6f723d626c7565) [![Downloads](https://camo.githubusercontent.com/acfe2bf914f22448b16f2afc23353e34949e2b4aa6fd0adc3289ac3871b9f899/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636163686565727068702f6d6f6e69746f723f7374796c653d666f722d7468652d626164676526636f6c6f723d626c7565)](https://camo.githubusercontent.com/acfe2bf914f22448b16f2afc23353e34949e2b4aa6fd0adc3289ac3871b9f899/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636163686565727068702f6d6f6e69746f723f7374796c653d666f722d7468652d626164676526636f6c6f723d626c7565) [![License](https://camo.githubusercontent.com/daa52099573be5a50c320c4387496400f2f722e49f86a42db8d5778130d3582d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e3f7374796c653d666f722d7468652d6261646765)](https://github.com/cacheerphp/monitor) [![CacheerPHP](https://camo.githubusercontent.com/78f669b626a8bbb18b1e489ccc88df336060a4088d7b7dddfa588e900ec36033/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436163686565725048502d253545342e37253230253743253743253230253545352e302d626c75653f7374796c653d666f722d7468652d6261646765)](https://github.com/cacheerphp/CacheerPHP)

---

Why Cacheer Monitor?
--------------------

[](#why-cacheer-monitor)

Caching makes apps fast — but *blind* caching causes stale data, wasted memory, and hard-to-trace bugs. Cacheer Monitor gives you **real-time visibility** into every cache operation with zero code changes:

- **Zero-config setup** — installs via Composer, auto-registers via `autoload.files`
- **Live dashboard** — glassmorphic UI with animated charts, dark/light theme
- **Hit-rate gauge** — hero metric with circular SVG ring, instant health check
- **Timeline insights** — hits vs misses, latency trends, TTL distribution
- **Key inspector** — drill into any key: history, stats, live value preview
- **SSE streaming** — events push to the dashboard in real time
- **Export** — download events as JSON or CSV
- **Token-based auth** — protect destructive actions with `CACHEER_MONITOR_TOKEN`
- **Sensitive data redaction** — passwords, tokens, and API keys are auto-masked in previews

---

Requirements
------------

[](#requirements)

- PHP 8.1+
- CacheerPHP `^4.7 || ^5.0`

---

Quick Start
-----------

[](#quick-start)

### 1. Install

[](#1-install)

```
composer require cacheerphp/monitor
```

That's it. The package self-registers via Composer's `autoload.files` — every cache operation on any `Cacheer` instance is instrumented automatically as soon as `vendor/autoload.php` is loaded.

### 2. Launch the dashboard

[](#2-launch-the-dashboard)

```
vendor/bin/cacheer-monitor serve --port=9966
```

### 3. Open your browser

[](#3-open-your-browser)

Navigate to  — events will appear as your app runs.

---

Table of Contents
-----------------

[](#table-of-contents)

- [How It Works](#how-it-works)
- [Dashboard Features](#dashboard-features)
- [Configuration](#configuration)
- [CLI Reference](#cli-reference)
- [REST API](#rest-api)
- [Custom Events File Path](#custom-events-file-path)
- [Security](#security)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)

---

How It Works
------------

[](#how-it-works)

On install, `src/Boot/bootstrap.php` is registered in Composer's autoloader. When your app loads `vendor/autoload.php`, the bootstrap runs and calls:

```
Cacheer::addListener(new CacheerMonitorListener(new JsonlReporter()));
```

CacheerPHP's built-in event dispatcher fires after every cache operation (`put`, `get`, `flush`, `clear`, `renew`, `tag`, etc.) and the listener writes structured JSONL records to disk. The dashboard server reads those records in real time.

### The JSONL Reporter

[](#the-jsonl-reporter)

The `JsonlReporter` is built for production:

- **File locking** — concurrent writes are safe via `.lock` files
- **Auto-rotation** — rotates at 10 MB to prevent unbounded growth
- **Instance IDs** — each reporter instance tags events for multi-process identification

### Alternative: InstrumentedCacheer

[](#alternative-instrumentedcacheer)

If you prefer explicit instrumentation over auto-registration:

```
use Cacheer\Monitor\InstrumentedCacheer;

$cache = InstrumentedCacheer::wrap($originalCacheer);
```

All cache calls are proxied through the monitor transparently.

---

Dashboard Features
------------------

[](#dashboard-features)

FeatureDescription**Metric cards**Hits, misses, puts, flushes, renews, clears, errors, avg latency (p95/p99)**Hit-rate gauge**Animated SVG circular ring — the hero metric**Hit-rate alert**Configurable threshold banner — warns when hit rate drops below N%**Hits vs Misses chart**10-minute rolling timeline with 30s buckets**Latency chart**Avg latency over time**TTL distribution**Bar chart: ≤1min, >1min, >5min, >1hr, >1day, forever**Drivers doughnut**Event count breakdown by driver**Top keys**10 most-accessed keys with search filter**Namespaces grid**Event counts per namespace**Event stream**Live feed with type badges, key, driver, duration, TTL, size, value type**Key Inspector**Slide-in panel: hit/miss/write stats, timestamps, live value preview, recent events**Value preview**Captured or live-resolved cache values with automatic sensitive field redaction**Export**Download events as JSON or CSV**SSE real-time**Server-Sent Events push updates to the dashboard**Auto-refresh**Configurable: off, 1s, 2s, 5s, 10s — persisted to localStorage**Time-range filter**5m, 15m, 1h, 6h, 24h, All**Dark / Light theme**Toggle with FOUC prevention — persisted to localStorage**Activity pulse**Animated top bar fires on every API fetch**Floating nav**Desktop sidebar with IntersectionObserver-based section highlighting---

Configuration
-------------

[](#configuration)

All configuration is via **environment variables** (OS env or `.env` file in your project root):

VariableDefaultDescription`CACHEER_MONITOR_EVENTS``sys_get_temp_dir()/cacheer-monitor.jsonl`Path to the JSONL events file`CACHEER_MONITOR_TOKEN`*(none)*If set, required via `X-Monitor-Token` header to clear events`CACHEER_MONITOR_CAPTURE_VALUES``false`Enable value preview capture in events`CACHEER_MONITOR_STREAM_TIMEOUT``30`SSE stream connection timeout (seconds)`CACHEER_MONITOR_PREVIEW_BYTES``2048`Max bytes for value preview JSON`CACHEER_MONITOR_REDACT_KEYS`*(empty)*Comma-separated list of additional keys to redact in previews### Built-in redacted keys

[](#built-in-redacted-keys)

The following keys are **always masked** in value previews, regardless of configuration:

`password`, `passwd`, `pwd`, `secret`, `token`, `access_token`, `refresh_token`, `authorization`, `api_key`, `apikey`, `private_key`, `client_secret`, `cookie`, `session`

---

CLI Reference
-------------

[](#cli-reference)

```
vendor/bin/cacheer-monitor serve [options]
```

FlagDefaultDescription`--host=``127.0.0.1`Host to bind to`--port=``9966`Port to listen on`--events=`*(auto-resolved)*Explicit path to the JSONL events file`--quiet`—Suppress request logging```
vendor/bin/cacheer-monitor help
```

---

REST API
--------

[](#rest-api)

MethodEndpointDescription`GET``/api/health`Server health check`GET``/api/config`Active configuration (events file path, origin)`GET``/api/metrics`Aggregated metrics with filtering`GET``/api/events`Paginated event log`POST``/api/events/clear`Rotate and clear events file (token-protected)`GET``/api/events/stream`SSE stream of live events`GET``/api/events/export`Export events as JSON or CSV`POST``/api/events/cleanup-rotated`Delete rotated log files older than N days`GET``/api/keys/inspect`Key inspector: history, stats, live value preview### Query parameters

[](#query-parameters)

Most read endpoints accept:

ParamTypeDescription`limit``int`Max events to return`namespace``string`Filter by namespace`from``float`Unix timestamp — start of time range`until``float`Unix timestamp — end of time range**Key inspector** — `/api/keys/inspect`:

ParamTypeDescription`key``string`**(required)** Cache key to inspect`namespace``string`Namespace filter`limit``int`Max events for this key`live``bool`Force live cache lookup**Export** — `/api/events/export`:

ParamTypeDescription`format``string``json` or `csv`**Cleanup** — `/api/events/cleanup-rotated` (POST body):

```
{ "max_age_days": 7 }
```

---

Custom Events File Path
-----------------------

[](#custom-events-file-path)

By default, events are written to the path resolved in this order:

1. `CACHEER_MONITOR_EVENTS` environment variable
2. `.env` file in the project root
3. System temp dir (`sys_get_temp_dir() . '/cacheer-monitor.jsonl'`)

Relative paths are always resolved from the consuming project root, not from `vendor/cacheerphp/monitor`.

To use a custom path:

```
use Silviooosilva\CacheerPhp\Cacheer;
use Cacheer\Monitor\CacheerMonitorListener;
use Cacheer\Monitor\Reporter\JsonlReporter;

Cacheer::removeListeners();
Cacheer::addListener(new CacheerMonitorListener(
    new JsonlReporter('/var/log/myapp/cacheer-events.jsonl')
));
```

Start the server pointing to the same file:

```
vendor/bin/cacheer-monitor serve --events=/var/log/myapp/cacheer-events.jsonl
```

---

Security
--------

[](#security)

- **Local by default** — binds to `127.0.0.1`; not exposed to the network
- **Token protection** — set `CACHEER_MONITOR_TOKEN` to require authentication on destructive actions
- **Sensitive data redaction** — passwords, tokens, and API keys are auto-masked in value previews
- **No-cache headers** — all API responses include `Cache-Control: no-store`
- **CORS** — `Access-Control-Allow-Origin: *` for local development

> **Warning:** Do not expose the dashboard on a public interface without adding authentication.

---

Documentation
-------------

[](#documentation)

Full documentation: [cacheerphp.com/docs/en/cacheer-monitor/](https://cacheerphp.com/docs/v5/en/cacheer-monitor/quick-start/)

---

Contributing
------------

[](#contributing)

Contributions are welcome! Please open an issue or submit a pull request.

---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance85

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

7

Last Release

76d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/66147538?v=4)[Sílvio Silva](/maintainers/silviooosilva)[@silviooosilva](https://github.com/silviooosilva)

---

Top Contributors

[![silviooosilva](https://avatars.githubusercontent.com/u/66147538?v=4)](https://github.com/silviooosilva "silviooosilva (27 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/cacheerphp-monitor/health.svg)

```
[![Health](https://phpackages.com/badges/cacheerphp-monitor/health.svg)](https://phpackages.com/packages/cacheerphp-monitor)
```

###  Alternatives

[psr/log

Common interface for logging libraries

10.4k1.2B11.6k](/packages/psr-log)[open-telemetry/api

API for OpenTelemetry PHP.

1941.5M277](/packages/open-telemetry-api)[open-telemetry/sdk

SDK for OpenTelemetry PHP.

2328.5M344](/packages/open-telemetry-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)