README

A complete, production-ready, and lightweight monitoring solution for Laravel applications. This package tracks, aggregates, and stores application events, slow requests, third-party API delays, database bottlenecks, cache misses, job failures, exception reports, and authentication failures with custom Persian translations and automatic request tracing (Trace ID).

یک پکیج کامل، سبک و آماده برای محیط‌های عملیاتی لاراول جهت مانیتورینگ همه‌جانبه‌ی نرم‌افزار. این پکیج تمامی درخواست‌ها، پردازش‌های کند، کوئری‌های زمان‌بر دیتابیس، استثناها (Exceptions)، صف‌ها، ورودهای ناموفق و عملکردهای سیستم را با برچسب‌های فارسی و ردگیری خودکار تراکنش‌ها (Trace ID) ثبت و تحلیل می‌کند.

🚀 Features (ویژگی‌ها)

🪵 Comprehensive Request Logging: Capture incoming request payloads, headers, methods, IPs, and status codes.
🔀 Automatic Request Tracing (Trace ID): Generates and injects unique trace IDs into request attributes and response headers (X-Trace-Id) for easy tracking.
⏱️ Performance Monitoring (Slow Triggers): Log slow HTTP requests, slow queue processing, and slow database queries based on configurable thresholds.
🌐 Third-Party API Tracking: Automatically track request details, response payloads, and latency of outgoing HTTP requests.
🛡️ Security & Privacy: Sanitize sensitive request parameters (e.g. password, token, otp) automatically.
📊 Insightful Dashboard APIs: Exposes robust JSON endpoints for listing logs, viewing detailed traces, and calculating system health statistics.
🧹 Automated Cleanups: Out-of-the-box Artisan command to purge old info, warning, and error logs automatically.
📅 Jalali Calendar Support: Dates formatted in Shamsi (Persian) natively using morilog/jalali.

📦 Installation (نصب)

You can install the package via composer:

composer require nishtman/monitoring

1. Run Migrations (اجرای میگریشن‌ها)

The package automatically registers its database migrations. Execute them to create the monitoring_logs table:

php artisan migrate

2. Publish Configuration (انتشار فایل پیکربندی)

Publish the package configuration file to customize thresholds, connection settings, and translation arrays:

php artisan vendor:publish --provider="Nishtman\Monitoring\MonitoringServiceProvider" --tag="monitoring-config"

⚙️ Configuration (پیکربندی)

After publishing, you can configure the package in config/monitoring.php. Below is a breakdown of available keys and their .env counterparts:

Configuration Key	.env Variable	Default	Description
`enabled`	`MONITORING_ENABLED`	`false`	Enable or disable the entire monitoring engine
`user_model`	-	`App\Models\User::class`	The eloquent model representing your application User
`monitoring_log.enabled`	`MONITORING_LOG_ENABLED`	`true`	Enable database writing for logs
`routes_prefix`	`MONITORING_ROUTES_PREFIX`	`api/monitoring`	Base URL path prefix for internal monitoring APIs
`queue_name`	`MONITORING_QUEUE`	`default`	Queue name to handle asynchronous log storage
`queue_connection`	`MONITORING_CONNECTION`	`sync`	Connection used to dispatch `StoreMonitoringLogJob`
`slow_request_threshold`	`MONITORING_SLOW_REQUEST_THRESHOLD`	`2000`	Slow incoming HTTP request limit in milliseconds
`slow_third_party_request_threshold`	`MONITORING_SLOW_THIRD_PARTY_THRESHOLD`	`3000`	Outgoing HTTP request latency limit in ms
`slow_queue_job_threshold`	`MONITORING_SLOW_QUEUE_JOB_THRESHOLD`	`5000`	Slow queue job limit in milliseconds
`slow_database_query_threshold`	`MONITORING_SLOW_DB_QUERY_THRESHOLD`	`500`	Slow SQL query limit in milliseconds

🛠️ Usage (نحوه استفاده)

1. Automatic Monitoring (مانیتورینگ خودکار)

When enabled (MONITORING_ENABLED=true), the package hooks into standard Laravel events out-of-the-box:

Incoming HTTP requests (via global middleware)
Database queries exceeding your threshold
Failed and slow queue jobs
Exceptions & validation errors
Authentication failures
Failed scheduled console tasks
Logged exception messages

2. Manual Custom Logging (ثبت دستی لاگ)

You can record custom application events using the Monitoring facade:

use Nishtman\Monitoring\Monitoring;
use Nishtman\Monitoring\Enums\LogTypes;
use Nishtman\Monitoring\Enums\EventTypes;

// Standard Info Log (لاگ اطلاع‌رسانی)
Monitoring::info(
    title: 'تغییر رمز عبور',
    type: LogTypes::security(),
    event: EventTypes::security_breach(),
    message: 'کاربر رمز عبور خود را تغییر داد',
    context: ['user_id' => 1]
);

// Warning Log (ثبت هشدار)
Monitoring::warning(
    title: 'عدم موجودی انبار',
    type: LogTypes::system(),
    message: 'درخواست ثبت سفارش با شکست مواجه شد',
    statusCode: 422
);

// Error Log (ثبت خطا)
Monitoring::error(
    title: 'شکست در اتصال درگاه',
    type: LogTypes::api(),
    message: 'اتصال به درگاه بانکی سامان برقرار نشد',
    responseData: ['error_code' => 5003],
    statusCode: 500
);

// Exception Logging (ثبت استثنا همراه با اطلاعات Trace)
try {
    throw new Exception("خطای نامشخص در همگام‌سازی فایل");
} catch (Throwable $e) {
    Monitoring::exception($e);
}

🧹 Log Cleanup (پاک‌سازی خودکار لاگ‌ها)

Over time, monitoring tables can grow significantly. To keep your database light, the package includes an automated cleanup command.

For ease of use, you can schedule it in your routes/console.php (Laravel 11+) or app/Console/Kernel.php (Laravel 10):

// Daily Cleanup
$schedule->command('monitoring:cleanup')->daily();

Retention Rules (دوران نگهداری):

Info level logs: Deleted after 7 days.
Warning level logs: Deleted after 30 days.
Error & Critical level logs: Deleted after 90 days.

🌐 API Endpoints (وب‌سرویس‌های مانیتورینگ)

The package registers the following administrative endpoints. (Note: Ensure you wrap or secure these endpoints in production under authenticated middleware if needed, or customize via routing).

GET /api/monitoring - Paginated list of monitoring logs with filter and search queries.
GET /api/monitoring/{id} - Details of a single log including stack trace and related tracer logs.
GET /api/monitoring/stats - Overall statistics including error breakdown, total count, today's count, and top issues.

🧪 Testing (تست‌ها)

Run tests to ensure everything is operating correctly:

composer test

📄 License (مجوز)

The MIT License (MIT). Please see License File for more information.

nishtman / monitoring

Maintainers

Package info

Statistics

Security