Application Metrics in Hazaar Framework

About 2 min

Application Metrics in Hazaar Framework

Overview

Hazaar Framework provides built-in support for application metrics, allowing you to track key performance indicators such as request counts, execution times, and memory usage. These metrics are useful for monitoring, debugging, and optimizing your application, especially in production environments or when running under advanced server setups like FrankenPHP worker mode.

Enabling Metrics

To enable metrics collection in your Hazaar application, update your configuration file (typically app/configs/app.php) as follows:

return [
    'production' => [
        // ...other config...
        'metrics' => [
            'enabled' => true,           // Enable metrics collection
            'file' => 'metrics.dat',     // Metrics data file (relative to app path)
        ],
        // ...other config...
    ],
    // ...other environments...
];

enabled: Set to true to activate metrics.
file: The filename where metrics will be stored. This should be writable by the application process.

How Metrics Work

When metrics are enabled, Hazaar tracks the following for each request:

Hits: Number of requests processed.
Execution Time: Time taken to process the request (in milliseconds).
Memory Usage: Peak memory usage during request processing.

These metrics are stored in the specified metrics file using a custom binary format for efficient storage and retrieval. The metrics file is automatically created and managed by the framework.

Metrics Lifecycle

Initialization: On application startup, Hazaar checks if metrics are enabled and prepares the metrics file.
Data Collection: During request processing, the framework collects relevant metrics.
Storage: When a request finishes (during application shutdown), metrics are written to the metrics file. This ensures that metrics are reliably stored, even when running in persistent worker environments like FrankenPHP.

Metrics and FrankenPHP Worker Mode

FrankenPHP worker mode allows PHP applications to run persistently, handling multiple requests in a single process. In this mode, it's crucial that metrics are stored after each request to ensure accuracy and consistency.

Hazaar Framework handles this automatically:

Metrics are updated and stored during the application's shutdown phase, which is triggered at the end of each request.
This guarantees that metrics reflect the actual performance and usage for every request, regardless of the server mode.

Accessing Metrics Data

The metrics file can be analyzed or visualized using custom tools or scripts. The framework provides methods to retrieve and graph metrics data programmatically. For advanced usage, refer to the API documentation for the Hazaar\File\Metric class.

Warning

There is currently no built-in interface to view metrics directly. However, the Hazaar tool will soon include a feature for viewing and analyzing metrics data easily.

Example: Enabling Metrics

// app/configs/app.php
return [
    'production' => [
        'metrics' => [
            'enabled' => true,
            'file' => 'metrics.dat',
        ],
        // ...other config...
    ],
];

Troubleshooting

Metrics not stored? Ensure the metrics file path is writable by the application process.
Metrics file missing? The framework will create it automatically if permissions allow.
Running in FrankenPHP? No special configuration is needed; metrics are stored correctly after each request.