PHPackages                             renoki-co/laravel-exporter-contracts - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PSR & Standards](/categories/psr-standards)
4. /
5. renoki-co/laravel-exporter-contracts

ActiveLibrary[PSR & Standards](/categories/psr-standards)

renoki-co/laravel-exporter-contracts
====================================

Base contracts implementation for Prometheus exports in Laravel.

2.2.0(3y ago)4173.7k↓25%8[3 PRs](https://github.com/renoki-co/laravel-exporter-contracts/pulls)4Apache-2.0PHPPHP ^8.0CI passing

Since Sep 27Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/renoki-co/laravel-exporter-contracts)[ Packagist](https://packagist.org/packages/renoki-co/laravel-exporter-contracts)[ Docs](https://github.com/renoki-co/laravel-exporter-contracts)[ GitHub Sponsors](https://github.com/rennokki)[ RSS](/packages/renoki-co-laravel-exporter-contracts/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (15)Used By (4)

Laravel Prometheus Exporter
===========================

[](#laravel-prometheus-exporter)

[![CI](https://github.com/renoki-co/laravel-exporter-contracts/workflows/CI/badge.svg?branch=master)](https://github.com/renoki-co/laravel-exporter-contracts/workflows/CI/badge.svg?branch=master)[![codecov](https://camo.githubusercontent.com/8dad9629e2db686404419c76da4a48f165eb4958ca39c6d040718c001347e4fa/68747470733a2f2f636f6465636f762e696f2f67682f72656e6f6b692d636f2f6c61726176656c2d6578706f727465722d636f6e7472616374732f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/renoki-co/laravel-exporter-contracts/branch/master)[![StyleCI](https://camo.githubusercontent.com/b31bc39005db1400adf6be2aff44cd001591028728f9d850c5e4a61cd216bd0e/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3431303830323330302f736869656c643f6272616e63683d6d6173746572)](https://github.styleci.io/repos/410802300)[![Latest Stable Version](https://camo.githubusercontent.com/d6f34cf081532424deef0d486c35cada59f2da7e25b99c6e7729251088bb6f4c/68747470733a2f2f706f7365722e707567782e6f72672f72656e6f6b692d636f2f6c61726176656c2d6578706f727465722d636f6e7472616374732f762f737461626c65)](https://packagist.org/packages/renoki-co/laravel-exporter-contracts)[![Total Downloads](https://camo.githubusercontent.com/6cd25c11499b15353cd2b3daf4c32c2d355f2cd5164e0c33a3505346a0798709/68747470733a2f2f706f7365722e707567782e6f72672f72656e6f6b692d636f2f6c61726176656c2d6578706f727465722d636f6e7472616374732f646f776e6c6f616473)](https://packagist.org/packages/renoki-co/laravel-exporter-contracts)[![Monthly Downloads](https://camo.githubusercontent.com/ebbd561af379a81c85a86352a4017f2411aa0675bed6bc221ffc6f7d01b49e0f/68747470733a2f2f706f7365722e707567782e6f72672f72656e6f6b692d636f2f6c61726176656c2d6578706f727465722d636f6e7472616374732f642f6d6f6e74686c79)](https://packagist.org/packages/renoki-co/laravel-exporter-contracts)[![License](https://camo.githubusercontent.com/3a7c59f124aab40b4749b6b6170f29e4e1e12c79254defe5cff6f60d7501d69a/68747470733a2f2f706f7365722e707567782e6f72672f72656e6f6b692d636f2f6c61726176656c2d6578706f727465722d636f6e7472616374732f6c6963656e7365)](https://packagist.org/packages/renoki-co/laravel-exporter-contracts)

Base contracts implementation for Prometheus exports in Laravel.

🤝 Supporting
------------

[](#-supporting)

**If you are using one or more Renoki Co. open-source packages in your production apps, in presentation demos, hobby projects, school projects or so, sponsor our work with [Github Sponsors](https://github.com/sponsors/rennokki). 📦**

[![](https://camo.githubusercontent.com/3ddc7db046ff511d6e8a13d9abfcae0f556b232f991b4b0028402da25d962b24/68747470733a2f2f6769746875622d636f6e74656e742e73332e66722d7061722e7363772e636c6f75642f7374617469632f34312e6a7067)](https://github-content.renoki.org/github-repo/41)

🚀 Installation
--------------

[](#-installation)

You can install the package via composer:

```
composer require renoki-co/laravel-exporter-contracts
```

Publish the config:

```
$ php artisan vendor:publish --provider="RenokiCo\LaravelExporter\LaravelExporterServiceProvider" --tag="config"
```

🙌 Usage
-------

[](#-usage)

All you have to do is to create a `\RenokiCo\LaravelExporter\Metric` class that defines how the values will update on each Prometheus call to scrap, and the definition of the collector.

By default, metrics are available on the `/exporter/group/metrics` endpoint and you can point Prometheus towards it for scraping. (i.e. `http://localhost/exporter/group/metrics`)

You can choose one of the following classes to extend:

- `\RenokiCo\LaravelExporter\GaugeMetric` for gauges
- `\RenokiCo\LaravelExporter\CounterMetric` for counters

For example, you can define gauges for users:

```
use RenokiCo\LaravelExporter\GaugeMetric;

class DatabaseUsers extends GaugeMetric
{
    /**
     * Get the metric help.
     *
     * @return string
     */
    protected function help(): string
    {
        return 'Get the total amount of users.';
    }

    /**
     * Perform the update call on the collector.
     * Optional, as some metrics can be modified somewhere else.
     *
     * @return void
     */
    public function update(): void
    {
        $this->set(User::count());
    }
}
```

In your `AppServiceProvider`'s `boot()` method, register your metric:

```
use RenokiCo\LaravelExporter\Exporter;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Exporter::register(DatabaseUsers::class);
    }

    // ...
}
```

You don't need to set the values. When the Prometheus scraper will make the request for metrics, the gauge will automatically be set.

Labelling
---------

[](#labelling)

You may label data by setting default values (i.e. server name, static data, etc.) and on-update.

```
class DatabaseRecords extends GaugeMetric
{
    /**
     * Define the default labels with their values.
     *
     * @return array
     */
    protected function defaultLabels(): array
    {
        return [
            'static_label' => 'static-value',
        ];
    }

    /**
     * Get the metric allowed labels.
     *
     * @return array
     */
    protected function allowedLabels(): array
    {
        return [
            'model',
            'static_label',
        ];
    }

    /**
     * Perform the update call on the collector.
     * Optional, as some metrics can be modified somewhere else.
     *
     * @return void
     */
    public function update(): void
    {
        $models = [
            User::class,
            Post::class,
            Team::class,
        ];

        foreach ($models as $model) {
            $this->set(
                value: $model::count(),
                labels: ['model' => $model,
            ]);
        }
    }
}
```

Grouping
--------

[](#grouping)

If you wish to have separate endpoints for different metrics, consider specifying it in the `$showsOnGroup` property:

```
class CustomMetrics extends Metric
{
    /**
     * The group this metric gets shown into.
     *
     * @var string|null
     */
    public static $showsOnGroup = 'metrics-reloaded';

    // ...
}
```

Under the hood, Laravel Exporter registers a route that allows you to scrape any group:

```
Route::get('/exporter/group/{group?}', ...);
```

To scrape this specifc metric (and other metrics that are associated with this group), the endpoint is `/exporter/group/metrics-reloaded` (i.e. `http://localhost/exporter/group/metrics-reloaded`).

Sending string responses
------------------------

[](#sending-string-responses)

In some cases you may want to export the string-alike, Prometheus-formatted response without using the internal metrics.

To do so, use the `exportResponse` function. The function will return the response directly instead of relying on the `Metric` class and subsequent class registrations via the `Exporter::register()` function.

```
use RenokiCo\LaravelExporter\Exporter;

Exporter::exportResponse(function () {
    return