README

Laravel Lamet (Laravel + Metrics)

A simple, high-performance package to record and aggregate metrics in Laravel applications, ready for Grafana dashboards.

📋 Table of Contents

🚀 Installation
✨ Usage
- Basic Usage
- Available Methods
📝 Notes
📚 More
Commands
Configuration
Environment Variables
Cache System
- Cache Configuration
Scheduled Tasks
Grafana Integration
Testing
Contributing
License

🚀 Installation

Install via Composer:
```
composer require itsemon245/lamet
```
Publish the configuration and migration:
```
php artisan lamet:install
```
This will publish config/lamet.php and the migration to database/migrations/lamet/.

Alternatively, you can publish them separately:
```
php artisan vendor:publish --tag=lamet-config
php artisan vendor:publish --tag=lamet-migrations
```

Configure your database and cache:

Set up your desired database connection in config/database.php (e.g., sqlite, mysql, pgsql). Postgres is recommended

 'lamet' => [
     'driver' => 'pgsql',
     'url' => env('LAMET_DATABASE_URL'),
     'host' => env('LAMET_DB_HOST', '127.0.0.1'),
     'port' => env('LAMET_DB_PORT', '5432'),
     'database' => env('LAMET_DB_DATABASE', 'lamet_metrics'),
     'username' => env('LAMET_DB_USERNAME', 'root'),
     'password' => env('LAMET_DB_PASSWORD', ''),
     'charset' => 'utf8',
     'prefix' => '',
     'prefix_indexes' => true,
     'search_path' => 'public',
     'sslmode' => 'prefer',
 ],

Create a new cache store or use an existing one from config/cache.php (e.g., redis).
Add and update the .env variables for the new database connection

#Database Connection
LAMET_DB_HOST=127.0.0.1
LAMET_DB_PORT=5432
LAMET_DB_DATABASE=lamet_metrics
LAMET_DB_USERNAME=root
LAMET_DB_PASSWORD=

#Other Config options (these are the defaults)
LAMET_CACHE_STORE=redis
LAMET_CACHE_PREFIX=metrics:
LAMET_CACHE_TTL=3600
LAMET_CACHE_BATCH_SIZE=1000
LAMET_LOG=false

[!NOTE] > Quick Setup: Use the provided misc/postgres-docker-compose.yml example to quickly spin up a PostgreSQL container for development and testing.

Run the migration:
```
php artisan migrate
```
[!IMPORTANT] The 5th step is very important. If you skip this your metrics won't be saved in the database. Also keep in mind that you have to set the frequency lower than the ttl value in config/lamet.php
Schedule periodic flushing: In app/Console/Kernel.php:
```
protected function schedule(Schedule $schedule): void
{
    $schedule->command('lamet:flush')->everyFiveMinutes();
}
```
[!TIP] Higher frequency means less granularity, not suitable for realtime metrics but lower memory usage Lower frequency means more granularity, suitable for realtime metrics but higher memory usage Keep it between 5-20 minutes in general.

✨ Usage

Basic Usage

Record a simple metric using the facade:

use Itsemon245\Lamet\Facades\Metrics;

// Record an API request
Metrics::increment('api.requests', 1, [
    'endpoint' => '/users',
    'method' => 'GET',
    'status_code' => 200
]);

Available Methods

Basic Metrics: Counter & Gauge Metrics
Timing: Time-based Metrics
Exceptions: Exception Tracking
Database: Database Query Monitoring
Cache Management: Cache Operations
Data Retrieval: Data Retrieval
Cleanup: Cleanup Operations

Each method supports three usage patterns:

Facade: Metrics::methodName()
Helper Functions: metricsMethodName()
Dependency Injection: Inject MetricsManager

For advanced usage and query examples, see:

Query Examples - Common SQL queries for Grafana
Advanced Usage - Advanced metric types and patterns
Grafana Queries - Grafana-specific query examples

📝 Notes

The tags column is flexible and can store any key-value pairs.
The recorded_at column is used for time-series queries in Grafana.
The type column defaults to counter for all metrics.
The unit column is available for any unit

📚 More

See the published config/lamet.php for all options.
See the migration for the table structure.
For advanced usage, see the helper functions and artisan commands provided.

Commands

`lamet:install`

Installs the package by publishing configuration and migration files.

php artisan lamet:install

Options:

--force: Overwrite existing files

`lamet:flush`

Flushes cached metrics to the database.

php artisan lamet:flush

Options:

--dry-run: Run the command without actually doing anything
-P|--print: Print the flush keys
--force: Force flush even if cache is disabled

`lamet:clean`

Cleans old metrics from the database.

php artisan lamet:clean

Options:

--dry-run: Run the command without actually doing anything
--days=30: Number of days to keep (default: 30)
--force: Force the operation without confirmation

Configuration

The package configuration is located in config/lamet.php. You can customize the following options:

General Settings

enabled: Enable/disable metrics recording
log_metrics: Log metrics to Laravel's log system
default_tags: Default tags to add to all metrics (environment, app_name, user fields)

Database Query Monitoring

db_query.enabled: Enable/disable auto database query monitoring
db_query.metric_name: Name for database query metrics
db_query.tags: Tags to include with database queries
db_query.store_only_slow_query: Store only slow queries (default: true)
db_query.slow_query_name_suffix: Suffix for slow query metric names (default: '.slow')
db_query.slow_query_threshold: Threshold in milliseconds for slow queries (default: 1500ms)

Exception Monitoring

exception.enabled: Enable/disable auto exception monitoring
exception.metric_name: Name for exception metrics
exception.tags: Tags to include with exception metrics

Ignore Configuration

ignore.paths: Array of paths to ignore when recording metrics
ignore.exceptions: Array of exception classes to ignore
ignore.db_query.tables: Array of database tables to ignore when monitoring queries
ignore.db_query.sql_patterns: Array of regex patterns to ignore specific SQL queries

Cache Configuration

cache.store: Cache store to use (default: redis)
cache.prefix: Prefix for cache keys (default: metrics:)
cache.ttl: Time to live for cached metrics (default: 3600 seconds)
cache.batch_size: Number of metrics to insert in one batch (default: 1000)

Database Settings

table: Database table name for storing metrics
connection: Database connection to use (null to disable database storage)

Environment Variables

You can configure the package using these environment variables:

LAMET_ENABLED=true
LAMET_LOG=false
LAMET_TABLE=lamet

# Cache Configuration
LAMET_CACHE_STORE=redis
LAMET_CACHE_PREFIX=lamet:
LAMET_CACHE_TTL=3600
LAMET_CACHE_BATCH_SIZE=1000

Cache System

The package includes a caching system that stores metrics in cache first, then periodically flushes them to the database. This provides:

Better Performance: Metrics are stored in fast cache storage
Reduced Database Load: Batch inserts instead of individual records
Data Aggregation: Similar metrics are automatically aggregated
Fault Tolerance: Metrics survive application restarts

Cache Configuration

LAMET_CACHE_STORE: Cache store to use (default: redis)
LAMET_CACHE_PREFIX: Prefix for cache keys (default: metrics:)
LAMET_CACHE_TTL: Time to live for cached metrics (default: 3600 seconds)
LAMET_CACHE_BATCH_SIZE: Number of metrics to insert in one batch (default: 1000)

Scheduled Tasks

Add these to your app/Console/Kernel.php to automatically flush and clean metrics:

protected function schedule(Schedule $schedule): void
{
    // Flush metrics every 5 minutes
    $schedule->command('lamet:flush')->everyFiveMinutes();

    // Clean old metrics daily at 2 AM (keep last 90 days)
    // $schedule->command('lamet:clean --days=90 --force')->dailyAt('02:00');
}

Grafana Integration

The package is designed to work seamlessly with Grafana for creating beautiful dashboards and visualizations.

Database as Data Source

Connect your metrics database to Grafana:

Add Data Source in Grafana:
- PostgreSQL: Use the PostgreSQL data source
- MySQL: Use the MySQL data source

Connection Settings:

Host: your-database-host
Database: your-metrics-database
User: your-database-user
Password: your-database-password

Recommended Dashboard Panels

Time Series: Response times, memory usage, CPU usage
Stat: Current values, totals, averages
Table: Top endpoints, error rates, recent events
Gauge: Current system health, utilization

Alerting

Set up Grafana alerts based on your metrics:

-- High response time alert
SELECT avg(value) as avg_response_time
FROM lamet
WHERE name = 'api.response_time'
  AND recorded_at >= now() - interval '5 minutes'
HAVING avg(value) > 1000;  -- Alert if > 1 second

For more Grafana query examples, see Grafana Queries.

Testing

Run the test suite:

composer test

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

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

itsemon245 / lamet

Maintainers

Details

README

Laravel Lamet (Laravel + Metrics)

📋 Table of Contents

🚀 Installation

✨ Usage

Basic Usage

Available Methods

📝 Notes

📚 More

Commands

`lamet:install`

`lamet:flush`

`lamet:clean`

Configuration

General Settings

Database Query Monitoring

Exception Monitoring

Ignore Configuration

Cache Configuration

Database Settings

Environment Variables

Cache System

Cache Configuration

Scheduled Tasks

Grafana Integration

Database as Data Source

Recommended Dashboard Panels

Alerting

Testing

Contributing

License