PHPackages                             mohsenabrishami/stethoscope - 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. mohsenabrishami/stethoscope

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

mohsenabrishami/stethoscope
===========================

laravel server monitoring

2.7.2(1y ago)29222.4k↓32.8%14[2 issues](https://github.com/MohsenAbrishami/stethoscope/issues)MITVuePHP ^8.0CI passing

Since Oct 9Pushed 1y ago1 watchersCompare

[ Source](https://github.com/MohsenAbrishami/stethoscope)[ Packagist](https://packagist.org/packages/mohsenabrishami/stethoscope)[ Docs](https://github.com/MohsenAbrishami/stethoscope)[ Fund](https://www.buymeacoffee.com/abrishami)[ RSS](/packages/mohsenabrishami-stethoscope/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (37)Used By (0)

[![](art/stethoscope.png)](art/stethoscope.png) Stethoscope
For listening to your Laravel app server heartbeat
===============================================================================================================

[](#-stethoscope-for-listening-to-your-laravel-app-server-heartbeat)

 [Features](#features) | [Installation](#installation) | [Usage](#usage) | [Dashboard](#dashboard) | [Configuration](#configuration) | [Notification](#notification) | [Testing](#testing) | [Changelog](#changelog) | [Contributing](#contributing) | [Credits](#credits) | [License](#license)

 [ ![Packagist](https://camo.githubusercontent.com/c4322df29085fdb548735e16cc551bfc5f530fb95871bd6cad6de1f7444bda3c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6f6873656e616272697368616d692f73746574686f73636f7065) ](https://packagist.org/packages/mohsenabrishami/stethoscope) [ ![license](https://camo.githubusercontent.com/d81b59beffe28a64555ee35161be042afda4b8f81c6c5c63a414a345e6b0867f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d6f6873656e616272697368616d692f73746574686f73636f7065) ](https://packagist.org/packages/mohsenabrishami/stethoscope) [ ![downloads total](https://camo.githubusercontent.com/587be7dba596bef6a3332a3f9e5efb94d35cddd82bc496652a7bfd4d403c4915/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6f6873656e616272697368616d692f73746574686f73636f70652e737667) ](https://packagist.org/packages/mohsenabrishami/stethoscope) [ ![tests](https://github.com/mohsenabrishami/stethoscope/workflows/Tests/badge.svg) ](https://packagist.org/packages/mohsenabrishami/stethoscope) [ ![tests](https://camo.githubusercontent.com/bfa1fffdcc3ecfa9ea4855ddd1069f296e3942866aa12b0bd5ed01cfb92fc800/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f4d6f6873656e416272697368616d692f73746574686f73636f70652e737667) ](https://scrutinizer-ci.com/g/MohsenAbrishami/stethoscope)

This Laravel package allows you to monitor the infrastructure.

With this package, You can check your server health at any time.

Features
--------

[](#features)

- Monitoring CPU usage percentage
- Monitoring memory usage percentage
- Monitoring Storage free space
- Checking the network connection status
- Checking web Server status (Nginx/Apache)
- Recording log when CPU, memory, and Storage usage exceeds the specified threshold
- Recording log when the network connection fails or the web server deactivated
- Sending email when a problem occurs in the CPU, memory, Storage, web server, and network of server

Do you need more options? you can make an issue or contributes to the package

Get Started
-----------

[](#get-started)

### Requirements

[](#requirements)

- **PHP 8.0+**
- **Laravel 8+**
- **Linux Operating System (Debian, Ubuntu, mint, ...)**

### Installation

[](#installation)

This package requires PHP 8.0 and Laravel 8.0 or higher. You can install the package via composer:

```
composer require mohsenabrishami/stethoscope
```

and then run:

```
php artisan vendor:publish --tag=stethoscope-publish-config
```

Stethoscope allows you to record reports both in a file and in a database. If you set the database driver in the config file, you must run migrate command:

```
php artisan migrate
```

Usage
-----

[](#usage)

Once installed, see your server health details with a command:

```
php artisan stethoscope:listen
```

The output will be like this:

 [![](art/listen_command_output.png)](art/listen_command_output.png)

But the work of this package didn't stop there. you can set thresholds for CPU, memory and Storage consumption. if CPU and memory consumption exceeds thresholds or Storage free space is less than thresholds, then a log is created from details consumption. also, you can config this package so that if the deactivated web server or disconnected internet log is created. To start monitoring your server, just run this command:

```
php artisan stethoscope:monitor
```

You can monitor your server constantly with the run this command by a cron job. You may want to be notified if there is a problem in the server. For this, it is enough to set your email admin in the config file.

If you are worried about the increase in logs, use the following command. This command deletes old logs based on the number of days you defined in the config file.

```
php artisan stethoscope:clean
```

Dashboard
---------

[](#dashboard)

Stethoscope provides a dashboard where you can easily see the current status of the server at any time. Also, in this dashboard, you can see a history of the times when resource consumption exceeded the limit or when the network and web server were disabled.

[![monitoring-panel](https://raw.githubusercontent.com/MohsenAbrishami/monitoring-panel/main/src/assets/monitoring_panel.png)](https://raw.githubusercontent.com/MohsenAbrishami/monitoring-panel/main/src/assets/monitoring_panel.png)

If you use the monitoring panel, you must publish the build files:

```
php artisan vendor:publish --tag=stethoscope-publish-view
```

Remember that the monitoring dashboard is disabled by default. To activate, you must set monitoring\_panel.status to true in config file. Also, the log storage driver must be a database, not a file.

You can put a key to access the admin panel. If you define a key, you can access the dashboard only when you enter the key in the address.

you can access this panel with address

```
    /*
    |--------------------------------------------------------------------------
    | Dashboard Configuration
    |--------------------------------------------------------------------------
    | Here, you can specify whether the monitoring panel is enabled and the key required to access it.
    | Also, you can customize the monitoring panel path.
    |
    */
    'monitoring_panel' => [
        'status' => false,
        'path' => 'monitoring-panel',
        'key' => env('MONITORING_PANEL_KEY'),
    ],
```

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

[](#configuration)

You can easily customize this package in the config/stethoscope.php.

In this file, You can configure the following:

- Resources that should be monitored. We can monitor the CPU, memory, Storage, network connection, and web server status.
- Web server that is installed on your server. We support Nginx and apache.
- Storage driver and path to saving log files.
- Resources Thresholds. Include maximum CPU and memory usage and minimum Storage space.
- Custom network URL for network connection monitor.
- Driver to save resource logs (support file storage and database).
- Emails address to send notification emails when your server has problems.
- Number of days for which resource logs must be kept.

By default, the configuration looks like this:

```
    /*
    |--------------------------------------------------------------------------
    | Monitorable Resources
    |--------------------------------------------------------------------------
    | Here you can Define which resources should be monitored.
    | Set true if you want a resource to be monitored, otherwise false.
    |
    */

    'monitorable_resources' => [
        'cpu' => true,
        'memory' => true,
        'storage' => true,
        'network' => true,
        'web_server' => true,
    ],

    /*
    |--------------------------------------------------------------------------
    | Web Server Name
    |--------------------------------------------------------------------------
    | Here you can define what web server installed on your server.
    | Set `nginx` or `apache`
    |
    */

    'web_server_name' => 'nginx',

    /*
    |--------------------------------------------------------------------------
    | Log File Storage
    |--------------------------------------------------------------------------
    | Define storage driver and path for save log file.
    |
    */

    'log_file_storage' => [
        'driver' => 'local',
        'path' => 'stethoscope/',
    ],

    /*
    |--------------------------------------------------------------------------
    | Thresholds
    |--------------------------------------------------------------------------
    | If resource consumption exceeds these thresholds, a log will be created.
    | You may define maximum CPU and memory usage by percent.
    | You may define minimum Storage space by GB.
    |
    */

    'thresholds' => [

        'cpu' => env('CPU_MONITOR_THRESHOLD', 90),

        'memory' => env('MEMORY_MONITOR_THRESHOLD', 80),

        'storage' => env('storage_MONITOR_THRESHOLD', 10),

    ],

    /*
    |--------------------------------------------------------------------------
    | Network Monitor URL
    |--------------------------------------------------------------------------
    | Here you can define the multiple desired URL for network monitoring.
    | If an address cannot be reached, it checks other addresses to make sure that the problem is with the server network
    |
    */

    'network_monitor_url' => env('NETWORK_MONITOR_URL', ['https://1.1.1.1', 'https://www.google.com']),

    /*
    |--------------------------------------------------------------------------
    | Log Record Driver
    |--------------------------------------------------------------------------
    | Set `database` for save logs in database and `file` for record logs in file
    |
    */

    'drivers' => [
        'log_record' => env('STETHOSCOPE_LOG_DRIVER', 'file'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Clean up resource logs
    |--------------------------------------------------------------------------
    | Here you define the number of days for which resource logs must be kept.
    | Older resource logs will be removed.
    |
    */
    'cleanup_resource_logs' => 7,
```

Notification
------------

[](#notification)

stethoscope can send you server problems through notifications. By default, sending notifications via email is supported. To use this feature, you must enter the email address of the admin user in the config file.

```
'mail' => [
    'to' => null,
],
```

### Adding extra notification channels

[](#adding-extra-notification-channels)

It's easy to add an extra notification channel such as Telegram or native mobile push notification, etc. In the following example we're going to add the Telegram push notifications channel. Other notification drivers can be added in the same way.

### 1. Install the notification channel driver

[](#1-install-the-notification-channel-driver)

First you need to create your custom driver. For Telegram push notifications, you can use following package:

```
laravel-notification-channels/telegram

```

After composer has pulled in the package, just follow [the installation instructions of the package](https://github.com/laravel-notification-channels/telegram)to complete the installation.

### 2. Creating your own custom notification

[](#2-creating-your-own-custom-notification)

In the following, you'll need to create your own notification class like the one below:

```
namespace App\Notifications;

use Illuminate\Bus\Queueable;
use MohsenAbrishami\Stethoscope\Notifications\LogReportNotification;
use NotificationChannels\Telegram\TelegramMessage;

class StethoscopeNotification extends LogReportNotification
{
    use Queueable;

    public function toTelegram()
    {
        $formattedMessage = "
        *Message from stethoscope:*

        *Be careful!! 💀*

        Your server has the following problems:
        " . (isset($this->logs['cpu']) ? '- Cpu usage: ' . $this->logs['cpu'] . ' %' : '') . "
        " . (isset($this->logs['memory']) ? '- Memory usage: ' . $this->logs['memory'] . ' %' : '') . "
        " . (isset($this->logs['network']) ? '- Network connection status: ' . $this->logs['network'] : '') . "
        " . (isset($this->logs['storage']) ? '- Remaining free space on the Storage:  ' . $this->logs['storage'] . ' GB' : '') . "
        " . (isset($this->logs['webServer']) ? '- Web server status:  ' . $this->logs['webServer'] : '') . "
    ";

        return TelegramMessage::create()->content($formattedMessage);
    }
}
```

### 3. Creating your own custom notifiable

[](#3-creating-your-own-custom-notifiable)

Also, you should create notifiable class. For this example, as you can see below, the Telegram channel ID should be returned:

```
namespace App\Notifications;

use MohsenAbrishami\Stethoscope\Notifications\Notifiable;

class StethoscopeNotifiable extends Notifiable
{
    public function routeNotificationForTelegram()
    {
        return config('stethoscope.notifications.telegram.channel_id');
    }
}
```

### 4. Register your custom notification in the config file

[](#4-register-your-custom-notification-in-the-config-file)

Finally, you should register notification and notifiable classes and add the telegram channel id:

```
    /*
    |--------------------------------------------------------------------------
    | Notifications
    |--------------------------------------------------------------------------
    | You can get notified when specific events occur. you should set an email to get notifications here.
    | If you don't need to send an email notification, set null.
    |
    */
    'notifications' => [

        'notifications' => [
            App\Notifications\StethoscopeNotification::class => ['telegram'],
        ],

        'notifiable' => App\Notifications\StethoscopeNotifiable::class,

        'telegram' => [
            'channel_id' => env('TELEGRAM_CHAT_ID')
        ]

    ],
```

Testing
-------

[](#testing)

Run the tests with:

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

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

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Credits
-------

[](#credits)

- [Mohsen Abrishami](https://github.com/mohsenabrishami)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance31

Infrequent updates — may be unmaintained

Popularity46

Moderate usage in the ecosystem

Community11

Small or concentrated contributor base

Maturity63

Established project with proven stability

 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 ~17 days

Recently: every ~42 days

Total

36

Last Release

717d ago

Major Versions

0.5.0 → 1.0.02023-01-10

1.1.2 → 2.0.02023-05-01

### Community

Maintainers

![](https://www.gravatar.com/avatar/cc5d22c679c92790f1b26d8ab1129db7131d416544312ebafeeadc337045b145?d=identicon)[MohsenAbrishami](/maintainers/MohsenAbrishami)

---

Top Contributors

[![MohsenAbrishami](https://avatars.githubusercontent.com/u/31363832?v=4)](https://github.com/MohsenAbrishami "MohsenAbrishami (313 commits)")

---

Tags

laravelmonitoring-serverphplaravelserver monitoringstethoscope

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mohsenabrishami-stethoscope/health.svg)

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

###  Alternatives

[spatie/laravel-health

Monitor the health of a Laravel application

86910.0M83](/packages/spatie-laravel-health)[marvinlabs/laravel-discord-logger

Logging to a discord channel in Laravel

2081.1M2](/packages/marvinlabs-laravel-discord-logger)[larabug/larabug

Laravel 6.x/7.x/8.x/9.x/10.x/11.x/12.x/13.x bug notifier

299549.3k1](/packages/larabug-larabug)[hosmelq/laravel-logsnag

Integrate the power of LogSnag's real-time event tracking into your Laravel application.

237.9k](/packages/hosmelq-laravel-logsnag)

PHPackages © 2026

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