Using counter type metric | laravel-prometheus | Spatie       

 SPATIE  

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

spatie.be/open-source

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

 Version   v1      

 Other versions for crawler [v1](https://spatie.be/docs/laravel-prometheus/v1) 

  Using counter type metric    
- [ Introduction ](https://spatie.be/docs/laravel-prometheus/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-prometheus/v1/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-prometheus/v1/requirements)
- [ Installation &amp; setup ](https://spatie.be/docs/laravel-prometheus/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-prometheus/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-prometheus/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-prometheus/v1/about-us)

Basic usage
-----------

- [ Creating gauges ](https://spatie.be/docs/laravel-prometheus/v1/basic-usage/creating-gauges)
- [ 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)

Setting up Prometheus and Grafana
---------------------------------

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

Advanced usage
--------------

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

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

###  On this page 

1. [ Using Counter Type Metric ](#content-using-counter-type-metric)
2. [ Cache Configuration ](#content-cache-configuration)

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.

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.

### 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,
```

### 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
    ```

### Concurrent updates

Cached metrics are read, changed and written back. Concurrent requests, queue workers or Octane workers can overwrite each other's updates, even when they update different metrics of the same type.

Enable `cache_lock` in `config/prometheus.php` to serialize updates per metric type:

```
'cache_lock' => true,
```

All writers sharing the metrics must enable this option and use the same shared cache and lock store. Array stores only coordinate within one process; file stores require a shared filesystem. Acquiring and releasing a lock adds cache operations to each update.

When enabled, an update waits up to 3 seconds to acquire the lock. If it times out, Laravel's `Illuminate\Contracts\Cache\LockTimeoutException` is thrown and the metric is not updated. Stores without lock support throw `InvalidArgumentException`. There is no unlocked fallback. Leave `cache_lock` disabled if you prefer the previous best-effort behavior.

Locks expire after 5 seconds to recover from terminated workers. Updates must finish within that lease; slower updates can still overlap after it expires. Locking does not make collecting and wiping metrics atomic, so avoid `wipe_storage_after_rendering` when concurrent writers must retain every update.

### 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.

 A good
match?
-------------

### What we do best

- All things Laravel
- Custom frontend components
- Building APIs
- AI-powered features
- Simplifying things
- Clean solutions
- Integrating services

### Not our cup of tea

- WordPress themes
- Cutting corners
- Free mockups to win a job
- "Just execute the briefing"

 In short: we'd like to be a **substantial part** of your project.

 [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)
