# Table of Contents

- [Introduction | laravel-prometheus | Spatie](#introduction-laravel-prometheus-spatie)
- [Support us | laravel-prometheus | Spatie](#support-us-laravel-prometheus-spatie)
- [Requirements | laravel-prometheus | Spatie](#requirements-laravel-prometheus-spatie)
- [Installation & setup | laravel-prometheus | Spatie](#installation-setup-laravel-prometheus-spatie)
- [Questions and issues | laravel-prometheus | Spatie](#questions-and-issues-laravel-prometheus-spatie)
- [Changelog | laravel-prometheus | Spatie](#changelog-laravel-prometheus-spatie)
- [About us | laravel-prometheus | Spatie](#about-us-laravel-prometheus-spatie)
- [Creating gauges | laravel-prometheus | Spatie](#creating-gauges-laravel-prometheus-spatie)
- [Using Horizon exporters | laravel-prometheus | Spatie](#using-horizon-exporters-laravel-prometheus-spatie)
- [Using cached values | laravel-prometheus | Spatie](#using-cached-values-laravel-prometheus-spatie)
- [Using Queue exporters | laravel-prometheus | Spatie](#using-queue-exporters-laravel-prometheus-spatie)
- [Introduction | laravel-prometheus | Spatie](#introduction-laravel-prometheus-spatie)
- [Using grafana.com | laravel-prometheus | Spatie](#using-grafana-com-laravel-prometheus-spatie)
- [Self-hosted | laravel-prometheus | Spatie](#self-hosted-laravel-prometheus-spatie)
- [Using fly.io | laravel-prometheus | Spatie](#using-fly-io-laravel-prometheus-spatie)
- [Creating multiple endpoints | laravel-prometheus | Spatie](#creating-multiple-endpoints-laravel-prometheus-spatie)
- [Creating collectors | laravel-prometheus | Spatie](#creating-collectors-laravel-prometheus-spatie)
- [Using counter type metric | laravel-prometheus | Spatie](#using-counter-type-metric-laravel-prometheus-spatie)

---

# Introduction | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Introduction

Laravel Prometheus
==================

Export Laravel metrics to Prometheus

[Repository](https://github.com/spatie/laravel-prometheus)

971,069

247

Introduction
------------

### On this page

1.  [Built-in Collectors](https://spatie.be/docs/laravel-prometheus/v1/introduction#content-built-in-collectors)
    

This package can export key metrics of your app to [Prometheus](https://prometheus.io/)
. It does this by providing an easy way to register metrics. Here's an example where we are going to export the user count to Prometheus.

Prometheus::addGauge('User count')
    ->value(fn() => User::count());

These metrics will be exposed at the `/prometheus` endpoint. The package offers a way to add a security layer, so your key metrics don't become public.

You can configure your Prometheus instance to periodically crawl and import the metrics at the `/prometheus` endpoint of your app. Using [Grafana](https://grafana.com/)
, you can visualize the data points that are stored in Prometheus.

[#](https://spatie.be/docs/laravel-prometheus/v1/introduction#content-built-in-collectors-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/introduction#content-built-in-collectors "Permalink")
Built-in Collectors
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

The package includes several built-in collectors for common Laravel functionality:

### [#](https://spatie.be/docs/laravel-prometheus/v1/introduction#content-queue-metrics-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/introduction#content-queue-metrics "Permalink")
Queue Metrics

Monitor your Laravel queues with comprehensive metrics including queue sizes, pending jobs, delayed jobs, and more. Supports all Laravel queue drivers (Redis, Database, SQS, etc.) with graceful fallbacks. If you're using Horizon, please use the Horizon collectors listed below instead!

// Enable all queue collectors
$this\->registerQueueCollectors(\['high', 'normal', 'low'\], 'redis');

### [#](https://spatie.be/docs/laravel-prometheus/v1/introduction#content-horizon-metrics-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/introduction#content-horizon-metrics "Permalink")
Horizon Metrics

Export Laravel Horizon metrics including supervisor status, workload distribution, job throughput, and failure rates.

// Enable all Horizon collectors
$this\->registerHorizonCollectors();

[About us](https://spatie.be/docs/laravel-prometheus/v1/about-us)

[Support us](https://spatie.be/docs/laravel-prometheus/v1/support-us)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/introduction.md)

 ESC

Enter a search term to find results in the documentation.

---

# Support us | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Support us

Support us
==========

We invest a lot of resources into creating our [best in class open source packages](https://spatie.be/open-source)
. You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us)
.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us)
. We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards)
.

[Introduction](https://spatie.be/docs/laravel-prometheus/v1/introduction)

[Requirements](https://spatie.be/docs/laravel-prometheus/v1/requirements)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/support-us.md)

 ESC

Enter a search term to find results in the documentation.

---

# Requirements | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Requirements

Requirements
============

The laravel-prometheus package requires **PHP 8.3+**, **Laravel 10+**.

[Support us](https://spatie.be/docs/laravel-prometheus/v1/support-us)

[Installation & setup](https://spatie.be/docs/laravel-prometheus/v1/installation-setup)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/requirements.md)

 ESC

Enter a search term to find results in the documentation.

---

# Installation & setup | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Installation & setup

Installation & setup
====================

You can install the package via composer:

composer require spatie/laravel-prometheus

Next, you should run the `prometheus:install` command.

php artisan prometheus:install

This will publish a config file named `prometheus.php` in your config with the following contents:

return \[\
    'enabled' => true,\
\
    /\*\
     \* The urls that will return metrics.\
     \*/\
    'urls' => \[\
        'default' => 'prometheus',\
    \],\
\
    /\*\
     \* Only these IP's will be allowed to visit the above urls.\
     \* When set to \`null\` all IP's are allowed.\
     \*/\
    'allowed\_ips' => \[\
        // '1.2.3.4',\
    \],\
\
    /\*\
     \* This is the default namespace that will be\
     \* used by all metrics\
     \*/\
    'default\_namespace' => 'app',\
\
    /\*\
     \* The middleware that will be applied to the urls above\
     \*/\
    'middleware' => \[\
        Spatie\\Prometheus\\Http\\Middleware\\AllowIps::class,\
    \],\
\
    /\*\
     \* You can override these classes to customize low-level behaviour of the package.\
     \* In most cases, you can just use the defaults.\
     \*/\
    'actions' => \[\
        'render\_collectors' => Spatie\\Prometheus\\Actions\\RenderCollectorsAction::class,\
    \],\
\];

It will also create and register a service provider called `PrometheusServiceProvider`, where you can register your own collectors.

This is the default content of the `PrometheusServiceProvider`:

namespace App\\Providers;

use Illuminate\\Support\\ServiceProvider;
use Spatie\\Prometheus\\Collectors\\Horizon\\CurrentMasterSupervisorCollector;
use Spatie\\Prometheus\\Collectors\\Horizon\\CurrentProcessesPerQueueCollector;
use Spatie\\Prometheus\\Collectors\\Horizon\\CurrentWorkloadCollector;
use Spatie\\Prometheus\\Collectors\\Horizon\\FailedJobsPerHourCollector;
use Spatie\\Prometheus\\Collectors\\Horizon\\HorizonStatusCollector;
use Spatie\\Prometheus\\Collectors\\Horizon\\JobsPerMinuteCollector;
use Spatie\\Prometheus\\Collectors\\Horizon\\RecentJobsCollector;
use Spatie\\Prometheus\\Facades\\Prometheus;

class PrometheusServiceProvider extends ServiceProvider
{
    public function register()
    {
        /\*
         \* Here you can register all the exporters that you
         \* want to export to prometheus
         \*/
        Prometheus::addGauge('my\_gauge', function () {
            return 123.45;
        });

        /\*
         \* Uncomment this line if you want to export
         \* all Horizon metrics to prometheus
         \*/
        // $this->registerHorizonCollectors();
    }

    public function registerHorizonCollectors(): self
    {
        Prometheus::registerCollectorClasses(\[\
            CurrentMasterSupervisorCollector::class,\
            CurrentProcessesPerQueueCollector::class,\
            CurrentWorkloadCollector::class,\
            FailedJobsPerHourCollector::class,\
            HorizonStatusCollector::class,\
            JobsPerMinuteCollector::class,\
            RecentJobsCollector::class,\
        \]);

        return $this;
    }
}

### [#](https://spatie.be/docs/laravel-prometheus/v1/installation-setup#content-configuring-the-metrics-endpoint-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/installation-setup#content-configuring-the-metrics-endpoint "Permalink")
Configuring the metrics endpoint

By default, the metrics endpoint will be available at `/prometheus`. You can change this by changing the default url in the `prometheus.php` config file.

// in config/prometheus.php
'urls' => \[\
    'default' => 'alternative-url',\
\],

### [#](https://spatie.be/docs/laravel-prometheus/v1/installation-setup#content-securing-the-metrics-endpoint-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/installation-setup#content-securing-the-metrics-endpoint "Permalink")
Securing the metrics endpoint

You probably don't want the endpoint that exposes your metrics to be publicly accessible. By adding an ip address to the `allowed_ips` key of the `prometheus.php` config file, you can restrict access to the endpoint to only that ip address.

In this example only requests from 1.2.3.4 can see the metrics. Requests from other IPs will get a 403 response.

// in config/prometheus.php

'allowed\_ips' => \[\
    '1.2.3.4',\
\],

### [#](https://spatie.be/docs/laravel-prometheus/v1/installation-setup#content-exporting-horizon-metrics-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/installation-setup#content-exporting-horizon-metrics "Permalink")
Exporting Horizon metrics

To export the Horizon metrics, uncomment this line in the default service provider:

$this\->registerHorizonCollectors();

[Requirements](https://spatie.be/docs/laravel-prometheus/v1/requirements)

[Questions and issues](https://spatie.be/docs/laravel-prometheus/v1/questions-issues)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/installation-setup.md)

 ESC

Enter a search term to find results in the documentation.

---

# Questions and issues | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Questions and issues

Questions and issues
====================

Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving the health library? Feel free to [create an issue on GitHub](https://github.com/spatie/laravel-prometheus/issues)
, we'll try to address it as soon as possible.

If you've found a bug regarding security please mail [security@spatie.be](mailto:security@spatie.be)
 instead of using the issue tracker.

[Installation & setup](https://spatie.be/docs/laravel-prometheus/v1/installation-setup)

[Changelog](https://spatie.be/docs/laravel-prometheus/v1/changelog)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/questions-issues.md)

 ESC

Enter a search term to find results in the documentation.

---

# Changelog | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Changelog

Changelog
=========

All notable changes to laravel-prometheus are documented [on GitHub](https://github.com/spatie/laravel-prometheus/blob/main/CHANGELOG.md)

[Questions and issues](https://spatie.be/docs/laravel-prometheus/v1/questions-issues)

[About us](https://spatie.be/docs/laravel-prometheus/v1/about-us)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/changelog.md)

 ESC

Enter a search term to find results in the documentation.

---

# About us | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 About us

About us
========

[Spatie](https://spatie.be/)
 is a webdesign agency based in Antwerp, Belgium.

Open source software is used in all projects we deliver. Laravel, Nginx, Ubuntu are just a few of the free pieces of software we use every single day. For this, we are very grateful. When we feel we have solved a problem in a way that can help other developers, we release our code as open source software [on GitHub](https://spatie.be/open-source)
.

[Changelog](https://spatie.be/docs/laravel-prometheus/v1/changelog)

[Creating gauges](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/about-us.md)

 ESC

Enter a search term to find results in the documentation.

---

# Creating gauges | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Basic-usage Creating gauges

Creating gauges
===============

### On this page

1.  [Adding a help text](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-adding-a-help-text)
    
2.  [Setting a namespace](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-setting-a-namespace)
    
3.  [Using labels](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-using-labels)
    
4.  [Alternative syntax](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-alternative-syntax)
    

To export your first metric to Prometheus, you should call `Prometheus::addGauge` method. This can be done anywhere in your code, but typically it's done in the `app/Providers/PrometheusServiceProvider.php` file that was published when installing the package.

Prometheus::addGauge('My gauge')
    ->value(fn() => 123.45);

This will create a gauge metric named `my_gauge` with the value of `123.45`. The metric will be present on the `/prometheus` endpoint.

You can add as many gauges as you want. Here's an example where we export the user count.

Prometheus::addGauge('User count')
    ->value(fn() => User::count());

[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-adding-a-help-text-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-adding-a-help-text "Permalink")
Adding a help text
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

You can add a help text to your metric by chaining the `helpText` method.

Prometheus::addGauge('User count')
    ->helpText('This is the number of users in our app')
    ->value(fn() => User::count());

[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-setting-a-namespace-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-setting-a-namespace "Permalink")
Setting a namespace
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

When exporting the metrics, a namespace value will be prefixed to the metric name. By default, the namespace is set to `app`. So, when you export a gauge named `User count`, the metric name will be `app_user_count`.

You can change the default namespace in the `namespace` key of the `config/prometheus.php` file.

To change the namespace of a specific gauge, you can chain the `namespace` method.

Prometheus::addGauge('User count')
    ->namespace('My custom namespace')
    ->value(fn() => User::count());

The above gauge will be exported as `my_custom_namespace_user_count`.

[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-using-labels-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-using-labels "Permalink")
Using labels
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Labels are a powerful feature of Prometheus. They allow you to add additional dimensions to your metrics. For example, you can add a label to the `User count` gauge to distinguish between active and inactive users.

To start using a label, you should call the `label` method on the gauge and pass the label name.

The callable passed to `value` should return an array of tuples. Each tuple should contain the value and an array of labels. The number of labels should match the number of labels defined on the gauge.

Prometheus::addGauge('User count')
    ->label('status')
    ->value(function() {
        return \[\
            \[User::where('status', 'active')->count(), \['active'\]\],\
            \[User::where('status', 'inactive')->count(), \['inactive'\]\],\
        \];
    });

[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-alternative-syntax-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges#content-alternative-syntax "Permalink")
Alternative syntax
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Instead of using multiple methods, you can also use named arguments to set the gauge properties.

Prometheus::addGauge(
    name: 'User count',
    helpText: 'This is the number of users in our app',
    namespace: 'My custom namespace',
    labels: \['status'\],
    value: function() {
        return \[\
            \[User::where('status', 'active')->count(), \['active'\]\],\
            \[User::where('status', 'inactive')->count(), \['inactive'\]\],\
        \];
    }
);

[About us](https://spatie.be/docs/laravel-prometheus/v1/about-us)

[Using Horizon exporters](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-horizon-exporters)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/basic-usage/creating-gauges.md)

 ESC

Enter a search term to find results in the documentation.

---

# Using Horizon exporters | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Basic-usage Using Horizon exporters

Using Horizon exporters
=======================

We can export key metrics from Horizon to Prometheus. To enable this feature, uncomment this line in the `app/Providers/PrometheusServiceProvider.php` file.

$this\->registerHorizonCollectors();

This will register the following collectors:

*   `horizon_master_supervisors`: exports the number of master supervisors.
*   `horizon_current_processes`: exports the number of processes currently running per queue
*   `horizon_current_workload`: exports the number of jobs currently waiting per queue.
*   `horizon_failed_jobs_per_hour jobs`: exports the number of failed jobs in the past hour
*   `horizon_status`: exports if the Horizon is running, paused, or inactive
*   `horizon_jobs_per_minute`: exports the number of jobs processed in the last minute
*   `horizon_recent_jobs`: exports the number of recent jobs

[Creating gauges](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges)

[Using cached values](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-cached-values)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/basic-usage/using-horizon-exporters.md)

 ESC

Enter a search term to find results in the documentation.

---

# Using cached values | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Basic-usage Using cached values

Using cached values
===================

Coming soon...

[Using Horizon exporters](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-horizon-exporters)

[Using Queue exporters](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/basic-usage/using-cached-values.md)

 ESC

Enter a search term to find results in the documentation.

---

# Using Queue exporters | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Basic-usage Using Queue exporters

Using Queue exporters
=====================

### On this page

1.  [Configuration](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-configuration)
    
2.  [Prometheus Metrics](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-prometheus-metrics)
    
3.  [Individual Collectors](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-individual-collectors)
    

> **Important**: If you are using Laravel Horizon, you should use the [Horizon exporters](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-horizon-exporters.md)
>  instead of these queue exporters. Horizon provides its own comprehensive queue monitoring and these two exporters should not be used together as they may conflict or provide duplicate metrics.

We can export key metrics from Laravel's built-in queue system to Prometheus. To enable this feature, uncomment this line in the `app/Providers/PrometheusServiceProvider.php` file.

$this\->registerQueueCollectors(\['default'\]);

This will register the following collectors for monitoring your Laravel queues:

*   `queue_size`: exports the total number of jobs in each queue
*   `queue_pending_jobs`: exports the number of pending jobs per queue
*   `queue_delayed_jobs`: exports the number of delayed jobs per queue (supported drivers)
*   `queue_reserved_jobs`: exports the number of reserved jobs per queue
*   `queue_oldest_pending_job_age`: exports the age of the oldest pending job in seconds (supported drivers)

[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-configuration-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-configuration "Permalink")
Configuration
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### [#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-basic-usage-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-basic-usage "Permalink")
Basic Usage

Register collectors for the default connection and default queue:

$this\->registerQueueCollectors(\['default'\]);

### [#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-custom-connection-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-custom-connection "Permalink")
Custom Connection

Monitor queues on a specific connection:

$this\->registerQueueCollectors(\['high', 'low'\], 'redis');

[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-prometheus-metrics-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-prometheus-metrics "Permalink")
Prometheus Metrics
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

All metrics include `connection` and `queue` labels for filtering and aggregation:

\# HELP app\_queue\_size The total number of jobs in the queue
# TYPE app\_queue\_size gauge
app\_queue\_size{connection="redis",queue="high"} 45
app\_queue\_size{connection="redis",queue="low"} 12

# HELP app\_queue\_delayed\_jobs The number of delayed jobs in the queue
# TYPE app\_queue\_delayed\_jobs gauge
app\_queue\_delayed\_jobs{connection="redis",queue="high"} 3
app\_queue\_delayed\_jobs{connection="redis",queue="low"} 0

[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-individual-collectors-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters#content-individual-collectors "Permalink")
Individual Collectors
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

You can also register collectors individually with custom parameters in your `PrometheusServiceProvider`.

use Spatie\\Prometheus\\Collectors\\Queue\\QueueSizeCollector;
use Spatie\\Prometheus\\Collectors\\Queue\\QueueDelayedJobsCollector;

Prometheus::registerCollectorClasses(\[\
    QueueSizeCollector::class,\
    QueueDelayedJobsCollector::class,\
\], \['connection' => 'redis', 'queues' => \['critical', 'high', 'normal'\]\]);

[Using cached values](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-cached-values)

[Introduction](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/introduction)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/basic-usage/using-queue-exporters.md)

 ESC

Enter a search term to find results in the documentation.

---

# Introduction | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Setting-up-prometheus-and-grafana Introduction

Introduction
============

This package provides a simple way to export metrics from your Laravel application to Prometheus. Grafana is a popular tool to create dashboards backed by Prometheus as the data source.

In this section, we'd like to share a couple of options on how to set up Prometheus and Grafana to monitor your Laravel application.

These sections aims to serve as a starting point. We won't go into details on how to every option of Grafana. There are plenty of resources available on the internet.

[Using Queue exporters](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/using-queue-exporters)

[Using grafana.com](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/setting-up-prometheus-and-grafana/introduction.md)

 ESC

Enter a search term to find results in the documentation.

---

# Using grafana.com | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Setting-up-prometheus-and-grafana Using grafana.com

Using grafana.com
=================

### On this page

1.  [Configuring Grafana](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com#content-configuring-grafana)
    
2.  [Creating a dashboard](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com#content-creating-a-dashboard)
    

The easiest way to get started using Prometheus and visualizing data via Grafana is by creating a free account on [grafana.com](https://grafana.com/)
 and using the hosted Grafana instance.

During this process, you'll install the Grafana agent, which will read the metrics on your `/prometheus` endpoint, and push them to Grafana.com.

[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com#content-configuring-grafana-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com#content-configuring-grafana "Permalink")
Configuring Grafana
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Once your account has been created, you'll be on your account dashboard. There, you should launch your Grafana instance by clicking the "Launch" button.

![Grafana.com dashboard](https://spatie.be/docs/images/launch-grafana.jpg)

At this point, you'll be redirected to your Grafana instance. There, you must go to "Connections" and add a new connection of type "Hosted prometheus Metrics".

![Grafana.com new connection](https://spatie.be/docs/images/new-connection.jpg)

When creating a new connection, choose "Via Grafana Agent".

![Grafana.com agent](https://spatie.be/docs/images/grafana-agent.jpg).

Next, follow the wizard, install the agent, and create a new config.

![Grafana.com config](https://spatie.be/docs/images/new-config.jpg).

Follow, the steps to create the config file, and start the agent on your server. To keep the agent running, you might use something like [Supervisord](http://supervisord.org/)
 (Laravel Forge users can just create [a daemon](https://forge.laravel.com/docs/1.0/resources/daemons.html)
)

In the `scrape_configs` key of the config, you should add a job to scrape the `/prometheus` endpoint of your Laravel application. For example:

  global:
      scrape\_interval: 10s
  configs:
      \- name: hosted-prometheus
        scrape\_configs:
            \- job\_name: laravel
              scrape\_interval: 10s
              metrics\_path: /prometheus
              static\_configs:
                  \- targets: \['your-app.com'\]
        remote\_write:
            \- url: <filled in by the wizard>
              basic\_auth:
                  username: <filled in by the wizard>
                  password: <filled in by the wizard>

Of course, you should replace `your-app.com` with the domain of your application.

[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com#content-creating-a-dashboard-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com#content-creating-a-dashboard "Permalink")
Creating a dashboard
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Once you've configured the agent, you can create a new dashboard. Head over to "Dashboards" and create a new dashboard.

On that screen, click "+ Add Visualization"

![Grafana.com visualization](https://spatie.be/docs/images/add-dashboard.jpg).

Next, click your hosted prometheus instance as the source.

![Grafana.com visualization](https://spatie.be/docs/images/prometheus-source.jpg).

In the metric dropdown, you should see all the metrics that are being scraped from your Laravel application.

![Grafana.com metrics](https://spatie.be/docs/images/metrics.jpg).

From here on, you can create your dashboard as you would normally do in Grafana. For more information on how to create dashboards, please refer to the [Grafana documentation](https://grafana.com/docs/grafana/latest/guides/getting_started/)
.

[Introduction](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/introduction)

[Self-hosted](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/setting-up-prometheus-and-grafana/using-grafana-com.md)

 ESC

Enter a search term to find results in the documentation.

---

# Self-hosted | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Setting-up-prometheus-and-grafana Self-hosted

Self-hosted
===========

### On this page

1.  [1\. Provision a server on Laravel Forge and install Prometheus and Grafana on it](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-1-provision-a-server-on-laravel-forge-and-install-prometheus-and-grafana-on-it)
    
2.  [2\. Configure Prometheus to scrape the metrics from your application and store them in its database](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-2-configure-prometheus-to-scrape-the-metrics-from-your-application-and-store-them-in-its-database)
    
3.  [3\. Configure Grafana to connect to Prometheus and visualize the metrics:](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-3-configure-grafana-to-connect-to-prometheus-and-visualize-the-metrics)
    

To receive metrics from your applications using Prometheus, and visualize them using Grafana, you can use a docker image that is deployed on your server.

Here are the general steps to set up Prometheus and Grafana via Laravel Forge. This isn't meant as a full guide, but rather as a starting point for you to get started.

[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-1-provision-a-server-on-laravel-forge-and-install-prometheus-and-grafana-on-it-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-1-provision-a-server-on-laravel-forge-and-install-prometheus-and-grafana-on-it "Permalink")
1\. Provision a server on Laravel Forge and install Prometheus and Grafana on it
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

*   Connect to your server via SSH.
*   Install Prometheus by following [the official installation guide](https://prometheus.io/docs/prometheus/latest/installation/)
    
*   Install Grafana by following [the official installation guide](https://grafana.com/docs/grafana/latest/installation/)
    

[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-2-configure-prometheus-to-scrape-the-metrics-from-your-application-and-store-them-in-its-database-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-2-configure-prometheus-to-scrape-the-metrics-from-your-application-and-store-them-in-its-database "Permalink")
2\. Configure Prometheus to scrape the metrics from your application and store them in its database
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

*   Edit the Prometheus configuration file `/etc/prometheus/prometheus.yml` and add a new job to scrape metrics from your application. For example:

scrape\_configs:
\- job\_name: laravel
  scrape\_interval: 10s
  metrics\_path: /prometheus
  static\_configs:
    \- targets: \['your-laravel-app.com'\]

This configuration tells Prometheus to scrape metrics from your application every 10 seconds and store them in its database.

[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-3-configure-grafana-to-connect-to-prometheus-and-visualize-the-metrics-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted#content-3-configure-grafana-to-connect-to-prometheus-and-visualize-the-metrics "Permalink")
3\. Configure Grafana to connect to Prometheus and visualize the metrics:
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

*   Open Grafana in your web browser by visiting http://your-server-ip:3000.
*   Log in with the default credentials (username: admin, password: admin).
*   Add a new Prometheus data source by clicking on the gear icon on the left sidebar, then selecting "Data Sources", then "Add data source".
*   Fill in the form with the following details:

Name: Prometheus Type: Prometheus URL: http://localhost:9090

This configuration tells Grafana to connect to Prometheus at http://localhost:9090.

*   Create a new dashboard by clicking on the plus icon on the left sidebar, then selecting "Dashboard", then "Add new panel".
*   Choose a visualization type (e.g. graph, gauge, table) and configure it to display the metrics you want to monitor.
*   Save the dashboard and view it to see the metrics in real-time.

That's it! You should now have Prometheus and Grafana set up to monitor your application's metrics.

[Using grafana.com](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-grafana-com)

[Using fly.io](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/setting-up-prometheus-and-grafana/self-hosted.md)

 ESC

Enter a search term to find results in the documentation.

---

# Using fly.io | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Setting-up-prometheus-and-grafana Using fly.io

Using fly.io
============

### On this page

1.  [Configuring Your Fly App](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics#content-configuring-your-fly-app)
    
2.  [Creating a Dashboard](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics#content-creating-a-dashboard)
    

Applications hosted on [fly.io](https://fly.io/)
 get a Grafana dashboard automatically (available at [fly-metrics.com](https://fly-metrics.net/)
).

You can publish your custom metrics to Fly, and view them in this hosted Grafana dashboard.

[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics#content-configuring-your-fly-app-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics#content-configuring-your-fly-app "Permalink")
Configuring Your Fly App
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Fly.io will scrape prometheus metrics automatically - we just need to tell it where to find them.

Assuming your application is outputing prometheus metrics at the default `/prometheus` endpoint, you can add the following [`[metrics]` configuring](https://fly.io/docs/reference/metrics/#custom-metrics)
 to your app's `fly.toml` file:

\[metrics\]
port = 8080 # Match your "internal\_port" config
path = "/prometheus" # default for this package

After you make this configuration change, you'll need to deploy your app for it to take effect. Run `fly deploy`, and Fly will begin scraping metrics.

Metrics will be available at [fly-metrics.com](https://fly-metrics.net/)
, where you can create new dashboards/graphs using your custom metrics via the "Prometheus on Fly" data source.

[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics#content-creating-a-dashboard-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics#content-creating-a-dashboard "Permalink")
Creating a Dashboard
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

From within [fly-metrics.com](https://fly-metrics.net/)
, you can choose to create a new Dashboard. From there, you can add a new panel.

![fly-metrics.net dashboard](https://spatie.be/docs/images/add-dashboard-fly.png)

To find your metrics, choose the "Prometheus on Fly" data source.

![fly-metrics.net graph](https://spatie.be/docs/images/prometheus-source-fly.png)

From here on, you can create your dashboard as you would normally do in Grafana. For more information on how to create dashboards, please refer to the [Grafana documentation](https://grafana.com/docs/grafana/latest/guides/getting_started/)
.

[Self-hosted](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/self-hosted)

[Creating multiple endpoints](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-multiple-endpoints)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/setting-up-prometheus-and-grafana/using-fly-metrics.md)

 ESC

Enter a search term to find results in the documentation.

---

# Creating multiple endpoints | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Advance-usage Creating multiple endpoints

Creating multiple endpoints
===========================

By default, all metrics are exported at the default `/prometheus` endpoint. You can configure Prometheus to periodically scrape metrics from this endpoint using a specified frequency.

If you want to export metrics that should be exported with an alternative frequency, you can create a new endpoint and configure Prometheus to scrape metrics from this endpoint using an alternative frequency.

To use multiple endpoints, you first need to configure them in the `prometheus.php` config file. Here's an example, where we configure an alternative endpoint

// in config/prometheus.php
    'urls' => \[\
        'default' => 'prometheus',\
        'alternative' => 'alternative-endpoint',\
    \],

To expose a metric at the alternative endpoint, you can use the `urlName` method on the metric. Here's an example:

use Spatie\\Prometheus\\Facades\\Prometheus;

Prometheus::addGauge('User count')
    ->urlName('alternative')
    ->value(fn() => User::count();

[Using fly.io](https://spatie.be/docs/laravel-prometheus/v1/setting-up-prometheus-and-grafana/using-fly-metrics)

[Creating collectors](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/creating-collectors)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/advance-usage/using-multiple-endpoints.md)

 ESC

Enter a search term to find results in the documentation.

---

# Creating collectors | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Advance-usage Creating collectors

Creating collectors
===================

When you create a package that contains metrics that should be easily be registered by your package users, you can create a collector.

A collector is a class that implements the `Spatie\Prometheus\Collectors` interface and is responsible for registering the metrics.

This is how the interface looks like.

namespace Spatie\\Prometheus\\Collectors;

interface Collector
{
    public function register(): void;
}

In the `register` method of your collector, you should can register metrics, such as gauges. Here's an example collector take from our own package, that will register a gauge to export an horizon metric.

namespace Spatie\\Prometheus\\Collectors\\Horizon;

use Laravel\\Horizon\\Contracts\\MasterSupervisorRepository;
use Spatie\\Prometheus\\Collectors\\Collector;
use Spatie\\Prometheus\\Facades\\Prometheus;

class CurrentMasterSupervisorCollector implements Collector
{
    public function register(): void
    {
        Prometheus::addGauge('Number of master supervisors')
            ->name('horizon\_master\_supervisors')
            ->helpText('The number of master supervisors')
            ->value(fn () => app(MasterSupervisorRepository::class)->all());
    }
}

Users of your package can register your collector by calling the `registerCollectorClasses` method on the `Prometheus` facade.

// in a service provider

use Spatie\\Prometheus\\Facades\\Prometheus;
use Spatie\\Prometheus\\Collectors\\Horizon\\CurrentMasterSupervisorCollector;

Prometheus::registerCollectorClasses(\[\
    CurrentMasterSupervisorCollector::class,\
\]);

[Creating multiple endpoints](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-multiple-endpoints)

[Using counter type metric](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/advance-usage/creating-collectors.md)

 ESC

Enter a search term to find results in the documentation.

---

# Using counter type metric | laravel-prometheus | Spatie

[Docs](https://spatie.be/docs)
 [Laravel-prometheus](https://spatie.be/docs/laravel-prometheus/v1)
 Advance-usage Using counter type metric

Using counter type metric
=========================

### On this page

1.  [Using Counter Type Metric](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-using-counter-type-metric)
    
2.  [Cache Configuration](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-cache-configuration)
    

[#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-using-counter-type-metric-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-using-counter-type-metric "Permalink")
Using Counter Type Metric
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

**Overview**

A Counter is a metric that only increases in value. It is typically used to count events, such as the number of requests received or tasks completed.

**Creating a Counter**

You can create a Counter metric using the `addCounter` method:

$counter = Prometheus::addCounter('my\_counter');

**Setting an Initial Value**

You can also define an initial value for your counter when creating it. This is useful if you want to start counting from a specific number:

$counter = Prometheus::addCounter('my counter')->setInitialValue(100);

**Incrementing the Counter**

To increment the counter, you can use the `inc` method:

$counter\->inc();

This will increase the counter by one.

If you need to increment the counter by a value greater than one, you can pass the value as an argument to the `inc()` method:

$counter\->inc(2);

**Best Practices**

*   **Naming Conventions:** Use descriptive names for your counters to make it clear what they are tracking. For example, `user_registration_total` or `api_request_count`.
*   **Atomic Increments:** Ensure that increments are atomic, especially in multi-threaded or multi-process environments, to avoid race conditions.

[#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-cache-configuration-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-cache-configuration "Permalink")
Cache Configuration
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

By default, the cache setting is set to `null`, which means that the metric will be stored in memory without using Laravel's caching system. This is suitable for simple setups or testing environments.

### [#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-configuring-cache-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-configuring-cache "Permalink")
Configuring Cache

You can configure the cache in the config/prometheus.php file:

/\*\*
\* Select a cache to store gauges, counters, summaries and histograms between requests.
\* In a multi node setup you should ensure that each node writes to its own
\* cache instance or uses a node specific prefix.
\* Configure the cache store in config/cache.php.
\*
\* to use an in memory adapter for testing use array or null as your store
\* or remove the cache entry all together:
\*  'cache' => null       // InMemory implementation without laravel cache
\*  'cache' => 'array'    // InMemory implementation using laravel cache
\*/
'cache' => null,

### [#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-cache-options-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-cache-options "Permalink")
Cache Options

*   **In-Memory Cache:** If you want to use an in-memory cache without relying on Laravel's cache system, keep the cache option as null.
*   **Laravel Cache:** To store metrics in Laravel's cache, set the cache option to a valid cache driver defined in your `config/cache.php` file:
    
    'cache' => 'redis', // Using Redis for caching metrics
    

### [#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-conclusion-1 "Permalink")
[#](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/using-counter-metric#content-conclusion "Permalink")
Conclusion

By properly configuring the cache, you can ensure that your metrics are persisted and shared across requests, making them more reliable in production environments.

[Creating collectors](https://spatie.be/docs/laravel-prometheus/v1/advance-usage/creating-collectors)

[Help us improve this page](https://github.com/spatie/laravel-prometheus/blob/main/docs/advance-usage/using-counter-metric.md)

 ESC

Enter a search term to find results in the documentation.

---