npm package: @stellartech/prometheus-directus
Description: Export Directus metrics into Prometheus. Exposes request counts, durations, and collection sizes on /metrics endpoint.
Latest version: 2.0.1

# Directus Extension: Prometheus

Expose Directus metrics to your Prometheus instance.

Compatible with **Directus 11.x**.

## Installation

### Via Directus Marketplace

Search for `@stellartech/prometheus-directus` in the Directus Marketplace and install directly from the admin panel.

### Via npm

```bash
npm install @stellartech/prometheus-directus
```

After installation, restart your Directus instance. Metrics will be available at the `/metrics` endpoint.

## Configuration

| Option                        | Description                                               | Default      |
|-------------------------------|-----------------------------------------------------------|--------------|
| `PROMETHEUS_METRICS_ENDPOINT` | The endpoint on which the prometheus metrics are exposed. | `"/metrics"` |

## Exposed Metrics

This extension exposes the following metrics:

### Request Metrics

| Metric                                    | Type      | Labels                           | Description                                                    |
|-------------------------------------------|-----------|----------------------------------|----------------------------------------------------------------|
| `directus_request_count`                  | Counter   | `method`, `status`               | Total number of HTTP requests                                  |
| `directus_request_duration_seconds`       | Histogram | `method`, `status`               | Duration of HTTP requests                                      |
| `directus_items_request_count`            | Counter   | `method`, `status`, `collection` | HTTP requests to items endpoints (excludes system collections) |
| `directus_items_request_duration_seconds` | Histogram | `method`, `status`, `collection` | Duration of items requests                                     |

### Collection Metrics

| Metric                     | Type  | Labels       | Description                        |
|----------------------------|-------|--------------|------------------------------------|
| `directus_collection_size` | Gauge | `collection` | Number of items in each collection |

## Example Output

```
# HELP directus_request_count The total number of http requests
# TYPE directus_request_count counter
directus_request_count{status="200",method="GET"} 160
directus_request_count{status="200",method="POST"} 2

# HELP directus_request_duration_seconds The total duration of http requests
# TYPE directus_request_duration_seconds histogram
directus_request_duration_seconds_bucket{le="0.005",method="GET",status="200"} 10
directus_request_duration_seconds_bucket{le="0.01",method="GET",status="200"} 57
directus_request_duration_seconds_bucket{le="0.025",method="GET",status="200"} 141
directus_request_duration_seconds_sum{method="GET",status="200"} 2.239873104999999
directus_request_duration_seconds_count{method="GET",status="200"} 160

# HELP directus_collection_size The total number of items in each collection
# TYPE directus_collection_size gauge
directus_collection_size{collection="directus_users"} 4
directus_collection_size{collection="my_collection"} 150
```

## Adding Custom Metrics

You can add your own metrics by creating a separate hook extension and importing the `globalRegister` from this package:

```typescript
import { defineHook } from '@directus/extensions-sdk';
import { globalRegister } from '@stellartech/prometheus-directus';
import { Counter } from 'prom-client';

export default defineHook(({ init }) => {
    init('app.before', () => {
        const customCounter = new Counter({
            registers: [globalRegister],
            name: 'my_custom_metric',
            help: 'Description of my custom metric'
        });

        // Increment the counter based on your logic
        setInterval(() => {
            customCounter.inc();
        }, 1000);
    });
});
```

## Prometheus Configuration

Add a scrape config to your `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: 'directus'
    static_configs:
      - targets: ['your-directus-host:8055']
    metrics_path: '/metrics'
```

## Credits

Originally created by [Thomas Biesart](https://github.com/chappio).
Updated for Directus 11 compatibility by [StellarTech](https://github.com/stellartech).