README

Metrics endpoint for Laravel applications

Using this package provides easy way for integration metrics endpoint into your Illuminate-based application.

Install

Require this package with composer using the following command:

$ composer require avto-dev/app-metrics-laravel "^2.0"

Installed composer is required (how to install composer).

You need to fix the major version of package.

After that you should "publish" package configuration file using next command:

$ php ./artisan vendor:publish --provider="AvtoDev\\AppMetrics\\ServiceProvider"

And configure it in the file ./config/metrics.php.

Usage

Feel free to write your own metric classes and add it after into metrics.metric_classes configuration array.

Metric class must implements MetricInterface and optionally HasDescriptionInterface/HasLabelsInterface/HasTypeInterface. In metric constructor you can request any dependencies - DI will inject it automatically.

Also metric class can implements MetricsGroupInterface (for metrics grouping).

When your metric classes are ready and successfully registered into configuration file - you can request special route (/metrics by default):

$ curl http://127.0.0.1:8080/metrics?format=json
[{"name": "some_metric", "value": 1, "labels": {"foo":"bar"}}]

$ curl http://127.0.0.1:8080/metrics?format=prometheus
some_metric{foo="bar"} 1

Configuration allows you to change endpoint URI, set password protection, and more.

Secret verification can be completed using sending get-parameter ?secret=XXX or HTTP header X-SECRET.

Formatters

Out of the box this package provides json and prometheus metrics formats. Feel free to write your own formatters.

Prometheus formatter

Prometheus formatter uses some constants for metric's values(Nan, +Inf, -Inf) and types(counter,summary,gauge,histogram, untyped). You can find it in PrometheusValuesDictionary and HasTypeInterface

Keep in mind that Prometheus accepts only numeric metrics values. This formatter will try to cast metrics values to numeric format (integer or float). And will set Nan if casting to numeric is impossible. Examples for formatting values:

Input	Output
`1.2`	`'1.2'`
`1`	`'1'`
`true`	`'1'`
`false`	`'0'`
`'123'`	`'123'`
`'12foo'`	`'Nan'`
`['10', '20']`	`'Nan'`
`null`	`'Nan'`
`'Nan'`	`'Nan'`
`'+Inf'`	`'+Inf'`
`'-Inf'`	`'-Inf'`

Skipping metrics

If during construction or formatting metrics would be thrown exception that implements AvtoDev\AppMetrics\Exceptions\ShouldBeSkippedMetricExceptionInterface then this metric would be skipped from formatters output and exception would be reported by Illuminate\Contracts\Debug\ExceptionHandler

Testing

For package testing we use phpunit framework and docker-ce + docker-compose as develop environment. So, just write into your terminal after repository cloning:

$ make build
$ make latest # or 'make lowest'
$ make test

Changes log

Changes log can be found here.

Support

If you will find any package errors, please, make an issue in current repository.

License

This is open-sourced software licensed under the MIT License.

avto-dev / app-metrics-laravel

Maintainers

Details