Download the PHP package directorytree/metrics without Composer

A simple and elegant way to record metrics in your Laravel application.

Contents · Installation · Usage · Testing

Metrics provides a simple, elegant way to record and query metrics in your Laravel application.

Track page views, API calls, user signups, or any other countable events.

Contents

• Requirements
• Installation
• Setup
  • Using the Redis Driver
• Usage
  • Recording Metrics
  • Recording with Values
  • Recording with Categories
  • Recording with Dates
  • Recording Hourly Metrics
  • Recording for Models
  • Recording with Custom Attributes
  • Capturing & Committing
  • Querying Metrics
• Testing
• Extending & Customizing
  • Custom Metric Models
  • Custom Metric Repository
  • Custom Metric Manager

Requirements

• PHP >= 8.1
• Laravel >= 9.0

Installation

You may install the package via composer:

Then, publish the migrations:

Finally, run the migrations:

Setup

Optionally, you may publish the configuration file:

This will create a config/metrics.php file where you may configure the driver and queueing behavior.

Using the Redis Driver

For distributed applications or high-traffic scenarios, you may use the redis driver to store captured metrics in Redis before committing them to the database in batches.

First, set the driver to redis in your configuration:

Or via environment variable:

Then, you may schedule the metrics:commit command to periodically commit metrics from Redis to your database:

[!important] Remember to disable auto_commit in the configuration file if you plan on committing metrics using the commit command.

You may also run the command manually:

This approach provides reduced database load since metrics can be committed in bulk at an expected interval instead of at the end of the request life-cycle.

The Redis driver uses a hash to store pending metrics with a configurable TTL (default of 1 day). This ensures metrics are eventually committed even if the scheduled command fails temporarily.

Usage

Recording Metrics

Record a metric using the Metrics facade:

Or using the metric global helper:

Or using the PendingMetric class:

Which ever method you use, metrics are recorded in the same way. Use whichever you prefer.

For the rest of the documentation, we will use the metric helper for consistency and brevity.

Recording with Values

By default, metrics have a value of 1. You may specify a custom value in the record method:

If you record the same metric multiple times, the values will be summed:

Recording with Categories

Organize metrics into categories:

These will be stored as separate metrics, allowing you to track the same metric across different contexts.

Recording with Dates

By default, metrics are recorded with today's date. You may specify a custom date using the date method:

Recording Hourly Metrics

By default, metrics are recorded at the daily level. For metrics that require hour-level granularity, you may use the hourly() method:

Hourly metrics include the hour (0-23) in addition to the year, month, and day, allowing you to track metrics at a more granular level:

Hourly metrics are stored separately from daily metrics, even for the same metric name:

You can query hourly metrics using the thisHour(), lastHour(), and onDateTime() methods:

[!tip] Use hourly metrics sparingly, as they create 24x more database rows than daily metrics. Reserve hourly tracking for metrics that genuinely benefit from hour-level granularity, or if you need the ability to query recorded metrics within a timezone.

Recording for Models

Associate metrics with Eloquent models using the HasMetrics trait:

Then record metrics for a specific model:

Query metrics for a model:

Recording with Custom Attributes

Store additional context with your metrics by adding custom attributes. This is useful for segmenting metrics by various dimensions like source, country, device type, or any other custom data.

First, create a migration to add custom columns to the metrics table:

Then, use the with() method to record metrics with custom attributes:

Custom attributes are included in the metric's uniqueness check, meaning metrics with different attribute values are stored separately:

This allows you to segment and analyze metrics by any dimension:

You can also use custom attributes with the MetricData class:

Or with the PendingMetric class:

[!important] Core metric attributes (name, category, year, month, day, measurable_type, measurable_id, value) cannot be overridden via custom attributes. They are protected and will always use the values set through their respective methods.

Capturing & Committing

For high-performance scenarios, you may capture metrics in memory and commit them in batches:

Captured metrics are automatically committed when the application terminates. You may also stop capturing manually:

To enable capturing for your entire application, start capturing in your AppServiceProvider:

This will batch all metrics recorded during the request and commit them automatically when the application terminates, reducing database queries and improving performance.

Querying Metrics

The Metric model includes a powerful query builder with date filtering methods:

Chain with standard Eloquent methods:

Testing

Metrics includes a fake implementation for testing:

Access recorded metrics in tests:

Extending & Customizing

Custom Metric Models

By default, metrics are stored using the included DirectoryTree\Metrics\Metric model. You may use a custom model globally or per-metric.

Global Custom Model

To use a custom metric model for all metrics, you may create your own model instance with the below requirements:

1. Be fully unguarded (so the model can fill'ed appropriately)
2. Include the same columns as the default metrics table
3. Include the same casts as the default Metric model

Once you have created your custom model, you may set it as the default using the useModel() method on the DatabaseMetricManager.

This is typically done in your AppServiceProvider:

Per-Metric Custom Model

To use different metric models for different metrics, use the model() method on PendingMetric.

Keep in mind you will have to duplicate the metrics table and its columns for each custom model:

Custom Metric Manager

Create your own metric manager by implementing the MetricManager interface:

Then bind it in your AppServiceProvider:

Custom Metric Repository

Create a custom repository for storing captured metrics:

Then bind it in your AppServiceProvider: