cosmastech / laravel-statsd-adapter
Easily use statsd-client-adapter within your Laravel project
Requires
- php: ^8.2
- cosmastech/statsd-client-adapter: ^0.4
- illuminate/contracts: ^10.0|^11.0
- illuminate/support: ^10.0|^11.0
Requires (Dev)
- cosmastech/psr-logger-spy: ^0.0.2
- datadog/php-datadogstatsd: ^1.6.1
- friendsofphp/php-cs-fixer: ^3.59
- laravel/facade-documenter: dev-main
- league/statsd: ^2.0.0
- orchestra/testbench: ^9.1
- phpstan/phpstan: ^1.11
- phpunit/phpunit: ^11.2.5
Suggests
- datadog/php-datadogstatsd: For DataDog stats
- league/statsd: For generic statsd clients
This package is auto-updated.
Last update: 2024-10-21 14:17:10 UTC
README
Laravel StatsD Adapter
Overview
The Laravel StatsD Adapter is a package that provides a seamless integration between Laravel applications and StatsD, a network daemon for collecting and aggregating metrics. By using this adapter, you can effortlessly monitor and measure the performance of your Laravel application, track various metrics, and send them to a StatsD server.
Why Use This Adapter?
- Save time: logs are great, but metrics can quickly tell the big picture of your application's health.
- Performance Monitoring: Easily track the performance of your Laravel application, including response times, database queries, and other custom metrics.
- Aggregation: StatsD collects and aggregates metrics, providing valuable insights into your application's performance over time.
- Flexibility: Configure the adapter to suit your specific needs. You can use multiple statsd instances in one environment or configure each environment to write to a different location: your local environment to write to a log, staging to a statsd instance, and production to DataDog.
- Testability: use
memory
adapter to write unit tests which confirm that stats are recorded under given conditions.
Installation
You can install the package via Composer:
composer require cosmastech/laravel-statsd-adapter
After installing the package, publish the configuration file using the following command:
php artisan vendor:publish --provider="Cosmastech\LaravelStatsDAdapter\StatsDAdapterServiceProvider"
Optional Dependencies
If you wish to use DataDog for logging stats, require the composer package
composer require datadog/php-datadogstatsd
For using League's statsd client, you'll need to install their package.
composer require league/statsd
Configuration
The configuration file config/statsd-adapter.php
allows you to customize the adapter's behavior.
Here are the available options:
- Default Connection: Specify the default StatsD connection.
- Default Tags: In addition to sending tags based on an as needed basis, you can also include tags in every outgoing request.
- Connections: Define multiple StatsD connections, each with its own settings.
You can use the example configuration,
return [ 'default' => env("STATSD_ADAPTER_DEFAULT", "datadog"), "default_tags" => [ "app_version" => "1.0.2", ], 'channels' => [ "datadog" => [ "adapter" => "datadog", "host" => env("DD_AGENT_HOST"), "port" => env("DD_DOGSTATSD_PORT"), "socket_path" => null, "datadog_host" => null, "decimal_precision" => null, "global_tags" => [], "metric_prefix" => null, "disable_telemetry" => null, ], ], ];
Usage
Basic Usage
To send a simple metric, you can use the Stats
facade:
use Cosmastech\LaravelStatsDAdapter\Stats; // Increment a counter Stats::increment('page.views'); // Record a gauge Stats::gauge('user.login', 1); // Record a timing (in ms) Stats::timing('response.time', 320);
If you prefer using dependency injection in your functions, use the StatsDClientAdapter
interface.
use Cosmastech\StatsDClientAdapter\Adapters\StatsDClientAdapter; use App\Models\User; use App\Models\Post; class DeleteAllUserPostsAction { public function __construct(private readonly StatsDClientAdapter $statsClient) { } public function __invoke(User $user): void { $user->posts->each(function(Post $post) use ($user) { $post->delete(); $this->statsClient->decrement("posts", 1.0, ["user_id" => $user->id], 1); }); } }
Use Cases
Tracking Page Views
Track the number of times a page is viewed:
Stats::increment('page.views', tags: ['url' => '/home']);
Monitoring Response Times
Measure and monitor the response time of your application:
function makeSomeApiCall() { return \Http::get("https://packagist.org/packages/list.json?vendor=cosmastech"); } $apiResponseToDoSomethingWith = Stats::time(makeSomeApiCall(...), "api-request");
Database Query Monitoring
Track the number of database queries and their execution time:
\DB::listen(function ($query) { Stats::increment('database.queries'); Stats::timing('database.query_time', $query->time); });
Advanced Configuration
Custom Connections
You can define multiple connections and use them as needed:
Stats::channel('memory')->increment('custom.metric');
Dynamic Metrics
Create dynamic metric names based on runtime data:
$role = auth()->role; // Let's assume the User model has a property named `role` Stats::increment("user.{$role}.login");
Contributing
Contributions are welcome! Please submit a pull request or open an issue to discuss your ideas.
License
This package is open-sourced software licensed under the WTFPL license.