mertaydin / elasticsearch-monitoring
A Laravel dashboard and metric collector for Elasticsearch clusters.
Package info
github.com/mertaydin/elasticsearch-monitoring
Language:Blade
pkg:composer/mertaydin/elasticsearch-monitoring
Requires
- php: ^8.2
- illuminate/console: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- illuminate/view: ^12.0 || ^13.0
Requires (Dev)
- larastan/larastan: ^2.9 || ^3.0
- laravel/pint: ^1.0
- orchestra/testbench: ^10.0 || ^11.0
- phpunit/phpunit: ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- 0.32.4
- 0.32.3
- 0.32.2
- 0.32.1
- 0.32.0
- v0.31.0
- v0.30.0
- v0.29.0
- v0.28.0
- v0.27.0
- v0.26.0
- v0.25.0
- v0.24.0
- v0.23.0
- v0.22.0
- v0.21.0
- v0.20.0
- v0.19.0
- v0.18.0
- v0.17.0
- v0.16.0
- v0.15.0
- v0.14.0
- v0.13.0
- v0.12.0
- v0.11.0
- v0.10.0
- v0.9.0
- v0.8.1
- v0.8.0
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- v0.3.0
- v0.2.0
- v0.1.9
- v0.1.8
- v0.1.7
- v0.1.6
- v0.1.5
- v0.1.4
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- dev-fix/aikido-security-sast-184745975-mcv7
- dev-fix/aikido-security-sast-184743514-2md7
- dev-fix/aikido-security-code-audit-184730194-181i
- dev-fix/use-renderable-es-screenshot-pages
- dev-fix/es-screenshot-server-timeout
- dev-fix/latest-es-screenshot-run
- dev-fix/screenshot-rendering-diagnostics
- dev-fix/aikido-security-code-audit-184730967-vx5j
- dev-fix/aikido-security-code-audit-184730778-jqrj
- dev-fix/aikido-security-code-audit-184729578-eldr
- dev-fix/aikido-security-code-audit-184729364-8nkx
- dev-fix/aikido-security-code-audit-184727729-mbls
- dev-fix/aikido-security-code-audit-184726278-4awc
- dev-docs/real-ui-screenshots
- dev-feat/local-json-viewer
- dev-feat/node-version-compatibility
- dev-feat/node-health-timeline
- dev-feat/node-resource-sorting
- dev-fix/node-explorer-test-assertions
- dev-fix/aikido-security-update-packages-184306471-xxhx
- dev-fix/aikido-security-sast-184299470-hjxc
- dev-fix/aikido-security-sast-184292405-rpzw
- dev-feat/node-explorer
- dev-feat/global-index-search
- dev-feature/problematic-indices-panel
- dev-chore/temporarily-remove-elasticsearch-connection-tests
This package is auto-updated.
Last update: 2026-11-16 22:16:26 UTC
README
A Laravel package for monitoring Elasticsearch clusters with metric collection and a lightweight dashboard.
Read-only by design: the package only reads Elasticsearch metrics, index metadata, mappings, settings, and lifecycle information. It never creates, updates, closes, or deletes indices, and never changes mappings, settings, shard allocation, or ILM policies.
Screenshots
These screenshots are captured from the package running inside a temporary Laravel application connected to a disposable Elasticsearch 8.18 cluster in GitHub Actions. The pages are rendered by the package's real views and use live Elasticsearch responses; only the indexed demo documents are synthetic.
| Cluster dashboard | Index management |
|---|---|
![]() |
![]() |
Features
-
Open and inspect JSON files in a browser-only JSON Viewer with a collapsible tree, key/value search, source editing, pretty printing, minifying, copy, and download. File contents stay in the browser and are never sent to Elasticsearch or uploaded to the server.
-
Inspect a selected Elasticsearch node from the Node Performance page, including IP, roles, CPU, JVM heap, disk usage, document/shard counts, and assigned indices with primary/replica shard counts.
-
Compare Elasticsearch versions across nodes on the Node Performance page, with a version distribution summary and a warning when nodes report different versions. Per-node versions are collected from the read-only
/_nodesAPI. -
Sort the Node Performance comparison table by CPU, JVM heap (RAM), or disk utilization, with the highest usage first.
-
Generate a PDF dashboard report with the selected date range, cluster name, key metrics, visible performance charts, optional previous-period comparison, and notes recorded in that period. PDF generation runs in the browser and does not add Elasticsearch requests or server-side PDF dependencies.
-
Export any dashboard chart as a titled PNG or combine all visible dashboard charts into one PNG directly in the browser.
-
Compare dashboard history charts with the immediately preceding period of equal duration; previous-period lines are aligned to the selected time window and can be toggled locally.
-
Refreshed dashboard layout with a compact navigation bar, clearer visual hierarchy, responsive controls, and consistent cards for KPIs, health, and charts.
-
Automatically aggregate long dashboard chart ranges into hourly averages (over 24 hours) or daily averages (over 7 days); shorter ranges retain raw observations.
-
Filter dashboard history charts by the last 1, 6, or 24 hours, the last 7 days, or a custom date range; retain the selection locally and cap large responses at 2,000 sampled points.
-
Choose a dashboard auto-refresh interval (15 seconds, 30 seconds, 1 minute, or 5 minutes), pause/resume refresh, and suspend background-tab requests.
-
Shard Allocation Explorer with per-node allocation explanations for unassigned or assigned shards. This diagnostic endpoint requires the Elasticsearch cluster
monitorprivilege and does not change cluster state. -
Save frequently used indices as browser-local favorites, filter the index list to favorites, and open them quickly from the dashboard. Dashboard favorite cards also show index health, document count, storage size, and current/total indexing operations; summaries refresh with the dashboard and require no database migration.
-
Export the currently visible index list (including search and favorites filters) as UTF-8 CSV or JSON directly in the browser.
-
Copy index names, node names and IP addresses, shard index/node identifiers, and snapshot repository/name values with one click.
-
Copy the complete formatted mapping JSON or individual top-level mapping sections from Index Management.
-
Show localized clipboard feedback in all six supported languages.
-
Add sortable columns to Index Management for index name, health, primary/replica shard counts, document count, and storage size.
-
Search indices globally from the dashboard with live suggestions, health/document/storage summaries, and direct links to index details.
-
Remember the Index Management search query and favorites-only filter in browser local storage.
-
Reset all Index Management filters and sorting with one click.
-
Monitor per-node query/fetch rates, average operation latency, active search/fetch operations, search queues, and rejection rates with historical trends.
-
Customize the dashboard by hiding sections, dragging them into a preferred order, and restoring the default layout. Preferences are stored in the current browser profile.
-
Customize the seven summary KPI cards independently: show/hide cards, drag to reorder, and pin important cards to the top. Preferences are saved locally in the browser and require no database migration or Elasticsearch requests.
-
Add private dashboard notes to a selected history chart and timestamp. Notes persist in the package database, appear as markers on the matching chart, and can be edited or deleted.
Requirements
- PHP 8.2+ for Laravel 12; PHP 8.3+ for Laravel 13
- Laravel 12 or 13
- Elasticsearch 8.18+ or 9.x
Installation
composer require mertaydin/elasticsearch-monitoring php artisan vendor:publish --tag=elasticsearch-monitoring-config php artisan migrate
Configure your connection in .env:
ELASTICSEARCH_MONITORING_URL=http://127.0.0.1:9200 ELASTICSEARCH_MONITORING_USERNAME= ELASTICSEARCH_MONITORING_PASSWORD= ELASTICSEARCH_MONITORING_API_KEY= ELASTICSEARCH_MONITORING_TIMEOUT=10 ELASTICSEARCH_MONITORING_VERIFY=true
Collect a snapshot with php artisan elasticsearch:collect.
Dashboard: /monitoring/elasticsearch
Index management and per-index performance analysis: /monitoring/elasticsearch/indices
Node performance history: /monitoring/elasticsearch/nodes
Thread pool analysis: /monitoring/elasticsearch/thread-pools
Snapshot & backup monitoring: /monitoring/elasticsearch/snapshots
Shard allocation: /monitoring/elasticsearch/shards
Capacity analysis: /monitoring/elasticsearch/capacity
Alert history: /monitoring/elasticsearch/alerts
Notification delivery history: /monitoring/elasticsearch/alerts/notifications
Query Activity: /monitoring/elasticsearch/query-activity
The index details modal includes a read-only performance analyzer for indexing, search, merge, refresh, flush, query/request cache, segments, and translog statistics. It compares primary-shard values with totals across primary and replica shards and refreshes only the selected index. The Elasticsearch monitor index privilege is required. The dashboard uses web and auth middleware by default. Configure the middleware, dashboard path, and locale in config/elasticsearch-monitoring.php. Set register_schedule to true to register a one-minute collection task and ensure Laravel's scheduler is running.
Dashboard authorization
You can register an authorization callback in your application's AppServiceProvider::boot() method, just like Laravel LogViewer. The callback receives the current request and must return true to allow access:
use ElasticsearchMonitoring\Facades\ElasticsearchMonitoring; public function boot(): void { ElasticsearchMonitoring::auth(function ($request) { return $request->user() && $request->user()->hasRole('SuperAdmin'); }); }
If the callback returns false, the package responds with HTTP 403. If no callback is registered, dashboard access is denied (HTTP 403), even when the middleware stack is customized. Register an explicit callback before exposing the dashboard. Keep the auth middleware enabled unless your callback intentionally handles authentication itself.
Query Activity Monitor
The dedicated Query Activity page shows per-node query and fetch counters, current query/fetch operations, scroll and suggest rates, average query/fetch time per operation, search thread-pool queue depth, and rejection rate. Rates and average times are calculated from counter deltas between successful metric collections, so a second collection is required before rate values appear. The page reads stored metric snapshots (up to the latest 1,440 collections), refreshes its display every 30 seconds, and does not issue additional Elasticsearch requests. Existing installations should run php artisan elasticsearch:collect after updating; historical samples collected before this feature do not contain query activity details.
Elasticsearch API Request History
The /monitoring/elasticsearch/api-requests page records GET requests made by the monitoring panel to Elasticsearch. It shows endpoint, HTTP status, response time, success/failure, and error details, plus rankings for the most-called and slowest endpoints. The latest 500 requests are listed. URL query parameters are stripped; credentials and request bodies are never logged. The feature creates the elasticsearch_api_request_logs table; run php artisan migrate after updating.
Favorites
Favorite indices are stored in the browser's local storage. They are specific to the current browser and browser profile, are not synchronized between users or devices, and do not require a database migration.
Index list sorting
Click the Name, Health, Primaries, Replicas, Documents count, or Storage size column heading to sort the index list. The first click sorts ascending; clicking the same heading again reverses the order. Health is ordered Green, Yellow, then Red. Sorting runs in the browser, works together with search and favorites filters, and does not send additional Elasticsearch requests. The selected column and sort direction are saved in this browser's local storage and restored when you return.
Remembering the index list view
The Index Management page saves the current search query and favorites-only selection in this browser's local storage and restores them when you return. A search query parameter in the page URL takes precedence over the saved search text. These preferences are local to the current browser profile, are not synchronized between users or devices, and do not require a database migration. If browser storage is unavailable, the page continues with its default view.
Resetting the index list
Use Clear filters on the Index Management page to clear the search query, favorites-only selection, and hidden/rollup index filters, and restore the default index sorting. The reset is applied in the browser and refreshes the index list using the default visibility options.
Dashboard notes
Use Dashboard notes to record an operational event against a history chart and exact date/time. Notes are stored in the package database, isolated by the authenticated account, and displayed as markers on the corresponding chart when the timestamp is inside the selected date range. You can create, edit, and delete notes; up to the latest 200 are shown. Run php artisan migrate after updating to create elasticsearch_dashboard_notes. Notes do not write to Elasticsearch.
Index exports
Use Export CSV or Export JSON on the Index Management page to download the currently filtered list. Exports respect the search query and favorites-only filter and include index name, health, status, document count, storage bytes, primary/replica shard counts, creation date when returned by Elasticsearch, data stream, and lifecycle metadata. Files are generated locally in the browser; no export endpoint, database migration, or Elasticsearch write request is used.
Metrics
Cluster health score, active alerts, per-node CPU/JVM/disk usage, documents, shards, search/write thread-pool queues and rejections, plus search and indexing rates calculated from counter deltas. The Thread Pool Analyzer provides per-node, per-pool queue, active, thread, completed, and rejected metrics with historical queue and rejection-rate charts. Snapshot Monitoring lists registered repositories, recent snapshots, shard outcomes, failures, and the latest successful backup. The dedicated Node Performance History page charts per-node CPU, JVM heap, filesystem utilization, search/indexing rates, and thread-pool queues from stored snapshots (up to the latest 1,440 collections). The Shard Allocation page displays primary/replica placement, shard states, unassigned reasons, and per-node shard distribution using the CAT Shards read API. Alert thresholds are configurable under alerts.thresholds in the package configuration. Email, Slack, and Microsoft Teams notifications can be enabled independently under alerts.notifications.channels; configure mail recipients or webhook URLs and set a cooldown period. Notification delivery attempts, failures, and cooldown suppressions are recorded at /monitoring/elasticsearch/alerts/notifications. Queue workers are recommended for non-blocking delivery; the default synchronous queue driver also works. Rates are available after at least two successful collections. Alert history records when an alert first appears, each subsequent observation, its latest value, and when it is resolved. Open /monitoring/elasticsearch/alerts to review active and resolved events. Existing installations should run php artisan migrate after updating.
Snapshot Monitoring requires the Elasticsearch monitor_snapshot cluster privilege. It reads repository metadata and the latest 50 snapshots per repository, caches results for 60 seconds, and does not expose repository settings or perform backup operations.
Copying identifiers and mappings
Copy buttons are available for index names, node names and IP addresses, shard index/node identifiers, and snapshot repository/snapshot names. The Index Management details modal supports copying the complete formatted mapping JSON or an individual top-level mapping section. Clipboard feedback is localized across all six supported languages. Node IP addresses are taken from the node statistics response and stored with subsequent metric snapshots; historical snapshots are not backfilled.
Compatibility
The package detects the Elasticsearch version from GET / and supports Elasticsearch 8.18+ and 9.x. It uses Laravel's HTTP client; the official Elasticsearch PHP SDK is not required.
Localization
Turkish (tr), English (en), Simplified Chinese (zh_CN), Hindi (hi), Spanish (es), and Arabic (ar). Arabic uses RTL layout.
Security
Keep the dashboard behind authentication and authorization. Store credentials in environment variables and keep TLS verification enabled in production. The package is strictly read-only against Elasticsearch; it has no index, mapping, settings, shard, or ILM modification features. Index details display ILM policy, phase, action, step, index age, rollover alias, and any failed-step information in read-only form.
Development
composer install
composer test
composer analyse
composer pint-test
Documentation
License
MIT
Alert notifications
Notifications are disabled by default. Enable only the channels you use in the published package configuration:
'alerts' => [ 'notifications' => [ 'cooldown_minutes' => 30, 'channels' => [ 'mail' => ['enabled' => true, 'recipients' => ['ops@example.com']], 'slack' => ['enabled' => true, 'webhook_url' => env('ELASTICSEARCH_MONITORING_SLACK_WEBHOOK')], 'teams' => ['enabled' => true, 'webhook_url' => env('ELASTICSEARCH_MONITORING_TEAMS_WEBHOOK')], ], ], ],
Set the Slack and Teams webhook environment variables in your application environment. New alert events are delivered once per channel; recurring observations of an active event do not resend notifications. If an alert resolves and reappears during the configured cooldown, delivery is suppressed and recorded. Failed queued deliveries are retried up to three times with backoff. Run a Laravel queue worker when using an asynchronous queue connection.
Dashboard layout preferences
Use Customize dashboard to hide or show the summary, favorites, health, metrics, node comparison, and chart sections. Drag sections in the list to change their order, or reset the layout to its default. Preferences are stored in browser local storage for the current browser profile; they are not synchronized across devices and do not require a database migration.
Dashboard automatic refresh
Choose a dashboard refresh interval of 15 seconds, 30 seconds, 1 minute, or 5 minutes. Pause and resume automatic refresh at any time. The selected interval is saved in the current browser profile and restored on your next visit. Automatic requests are suspended while the dashboard tab is in the background and resume when it becomes visible again. The dashboard also shows the time of the last refresh attempt. Manual refresh remains available while automatic refresh is paused.
Dashboard chart exports
Use the Download PNG action on an individual chart to save a titled image, or choose Download all charts as PNG to create one combined image containing the visible dashboard charts. The selected date range is included in the image. Exports are generated in the browser; no export endpoint, database change, or additional Elasticsearch request is required.
Elasticsearch connection status
The dashboard header checks the Elasticsearch root information endpoint and displays Connected, Slow response, or Connection lost, along with the latest successful connection time and check latency. The status is refreshed every 30 seconds independently of metric collection. The slow-response threshold defaults to 1,000 ms and can be changed with ELASTICSEARCH_MONITORING_SLOW_RESPONSE_MS (or connection.slow_response_ms in the published configuration). The check uses an authenticated, read-only GET request and does not change cluster state.


