📊 Strapi Prometheus Plugin

A powerful middleware plugin that adds comprehensive Prometheus metrics to your Strapi application using prom-client. Monitor your API performance, track system resources, and gain valuable insights into your application's behavior.

✨ Features

• 🚀 Real-time API Metrics - Track HTTP request duration, payload sizes, and response codes
• 📈 System Monitoring - Collect Node.js process metrics as recommended by Prometheus
• 🔒 Secure by Default - Dedicated metrics server (port 9000) isolated from your main application
• 🏷️ Custom Labels - Add custom labels to categorize and filter your metrics
• 📊 Lifecycle Tracking - Monitor Strapi lifecycle events duration
• 🔌 Easy Integration - Simple configuration with sensible defaults
• 🆔 Version Tracking - Monitor Strapi version information

⏳ Installation

1. Install the package

npm install strapi-prometheus
# or
yarn add strapi-prometheus
# or
pnpm add strapi-prometheus

2. Install peer dependencies

npm install prom-client
# or
yarn add prom-client
# or
pnpm add prom-client

3. Configure the plugin

Create or update your config/plugins.js (or config/plugins.ts for TypeScript):

// config/plugins.js
module.exports = {
  // ...other plugins
  prometheus: {
    enabled: true,
    config: {
      // Optional: Collect Node.js default metrics
      // See collectDefaultMetricsOption of prom-client for all options
      collectDefaultMetrics: false, // or { prefix: 'my_app_' }

      // Optional: Add custom labels to all metrics
      labels: { 
        app: "my-strapi-app",
        environment: "production"
      },

      // Server configuration
      // Set to false to expose metrics on your main Strapi server (not recommended)
      server: {
        port: 9000,           // Metrics server port
        host: '0.0.0.0',      // Metrics server host
        path: '/metrics'      // Metrics endpoint path
      }
      // OR disable separate server (use with caution):
      // server: false
    }
  }
};

For TypeScript projects:

// config/plugins.ts
export default {
  prometheus: {
    enabled: true,
    config: {
      collectDefaultMetrics: false,
      labels: { 
        app: "my-strapi-app",
        environment: process.env.NODE_ENV || "development"
      },
      server: {
        port: parseInt(process.env.METRICS_PORT || '9000'),
        host: process.env.METRICS_HOST || '0.0.0.0',
        path: '/metrics'
      }
    }
  }
};

📊 Available Metrics

The plugin automatically collects the following HTTP metrics with intelligent route pattern detection:

🎯 Smart Route Labeling

The plugin uses intelligent route pattern detection to ensure low cardinality metrics:

Route Pattern Examples:

/api/articles/123        → /api/articles/:id
/uploads/image.jpg       → /uploads/:file
/admin/users/uuid-here   → /admin/users/:uuid

Benefits:

• ✅ Low cardinality - Groups similar requests together
• ✅ Consistent aggregation - Easy to analyze API performance patterns
• ✅ Prometheus-friendly - Prevents metric explosion
• ✅ Automatic normalization - Handles IDs, UUIDs, file names automatically

📊 Metric Buckets

Request Duration Buckets: 1ms, 5ms, 10ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s, 5s, 10s

Content Length Buckets: 256KB, 512KB, 1MB, 2MB, 4MB, 8MB, 16MB, 32MB, 64MB, 128MB, 256MB, 512MB, 1GB

Optional System Metrics

When collectDefaultMetrics is enabled, you'll also get Node.js process metrics:

• process_cpu_user_seconds_total - CPU time spent in user mode
• process_cpu_system_seconds_total - CPU time spent in system mode
• process_start_time_seconds - Process start time
• process_resident_memory_bytes - Resident memory size
• nodejs_heap_size_total_bytes - Total heap size
• nodejs_heap_size_used_bytes - Used heap size
• nodejs_external_memory_bytes - External memory usage
• And more...

� Configuration Options

collectDefaultMetrics

Controls collection of Node.js process metrics:

// Disable default metrics (default)
collectDefaultMetrics: false

// Enable with default settings
collectDefaultMetrics: true

// Enable with custom prefix
collectDefaultMetrics: { 
  prefix: 'my_app_',
  register: undefined, // Uses default registry
  gcDurationBuckets: [0.001, 0.01, 0.1, 1, 2, 5], // Custom GC buckets
  eventLoopMonitoringPrecision: 10 // Event loop precision
}

labels

Global labels added to all metrics:

labels: {
  app: 'my-app',
  environment: 'production',
  version: '1.0.0',
  datacenter: 'us-east-1'
}

server

Metrics server configuration:

// Dedicated server (recommended)
server: {
  port: 9000,
  host: '0.0.0.0',
  path: '/metrics'
}

// Disable dedicated server (adds /metrics to main Strapi server)
server: false

🚀 Quick Start

1. Install and configure the plugin (see Installation)
2. Start your Strapi application
3. Metrics will be available at http://localhost:9000/metrics
4. Configure Prometheus to scrape this endpoint

📊 Accessing Metrics

Dedicated Server (Default & Recommended)

By default, metrics are served on a separate server:

curl http://localhost:9000/metrics

Main Strapi Server (Not Recommended)

If you set server: false, metrics will be available on your main Strapi server:

# Requires authentication token
curl -H "Authorization: Bearer YOUR_API_TOKEN" http://localhost:1337/metrics

👮‍♀️ Security Considerations

[!CAUTION] Metrics can contain sensitive information about your application's usage patterns, performance characteristics, and potentially user behavior. Always secure your metrics endpoint appropriately.

Recommended: Dedicated Server (Default)

The plugin starts a separate server on port 9000 by default, isolated from your main application:

• ✅ Secure by design - No external access to your main application
• ✅ Simple firewall rules - Block port 9000 from external access
• ✅ Performance - No impact on your main application
• ✅ Monitoring-specific - Dedicated to metrics collection

Alternative: Main Server Integration

You can expose metrics on your main Strapi server by setting server: false:

• ⚠️ Authentication required - Protected by Strapi's auth middleware
• ⚠️ API token needed - Must create and manage API tokens
• ⚠️ Potential exposure - Metrics endpoint on your main application
• ⚠️ Performance impact - Additional load on main server

We strongly recommend using the dedicated server approach.

🖐 Compatibility

Note: For new projects, we recommend using Strapi v5.x with the latest plugin version.

📊 Prometheus Configuration Example

[!NOTE] This plugin only exposes metrics - you need to set up your own Prometheus instance to collect them.

Here's a basic Prometheus configuration to scrape metrics from the dedicated server:

# prometheus.yml
global:
  scrape_interval: 15s     # How frequently to scrape targets
  evaluation_interval: 15s # How frequently to evaluate rules

rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

scrape_configs:
  - job_name: "strapi-app"
    static_configs:
      - targets: ["localhost:9000"]  # Metrics server endpoint
    scrape_interval: 10s             # Override global interval
    metrics_path: /metrics           # Metrics endpoint path

    # Optional: Add additional labels to all metrics from this job
    relabel_configs:
      - target_label: 'app'
        replacement: 'my-strapi-app'

Docker Compose Example

If you're running Strapi in Docker, here's a complete example:

version: '3.8'
services:
  strapi:
    image: my-strapi-app
    ports:
      - "1337:1337"  # Strapi app
      - "9000:9000"  # Metrics (expose only to monitoring network)

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/etc/prometheus/console_libraries'
      - '--web.console.templates=/etc/prometheus/consoles'

📊 Grafana Dashboards

Ready-to-use Grafana dashboards for visualizing your Strapi metrics:

Official Dashboards

• Dashboard 14565 - Comprehensive Strapi monitoring dashboard

Custom Dashboard Examples

You can create custom dashboards using queries like:

# Average request duration by route
rate(http_request_duration_seconds_sum[5m]) / rate(http_request_duration_seconds_count[5m])

# Request rate by route pattern
sum(rate(http_request_duration_seconds_count[5m])) by (route)

# Request rate by method and status
sum(rate(http_request_duration_seconds_count[5m])) by (method, status)

# Error rate by route
sum(rate(http_request_duration_seconds_count{status=~"5.."}[5m])) by (route) / sum(rate(http_request_duration_seconds_count[5m])) by (route)

# Active requests by route
sum(http_active_requests) by (route)

# Top slowest API endpoints
topk(10, histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) by (route))

# Request throughput by origin
sum(rate(http_request_duration_seconds_count[5m])) by (origin)

# Response size distribution
histogram_quantile(0.95, rate(http_response_content_length_bytes_bucket[5m])) by (route)

# Memory usage (when collectDefaultMetrics is enabled)
nodejs_heap_size_used_bytes / nodejs_heap_size_total_bytes

Contributing Dashboards

Have a great dashboard? We'd love to feature it! Please open a pull request with your dashboard JSON.

🔍 Troubleshooting

Common Issues

Metrics server not starting

• Check if port 9000 is already in use
• Verify firewall settings
• Check Strapi logs for error messages

No metrics appearing

• Ensure the plugin is properly enabled in config/plugins.js
• Verify that prom-client is installed
• Check that requests are being made to your Strapi application

Memory usage increasing

• Consider disabling collectDefaultMetrics if not needed
• Review custom labels - avoid high-cardinality labels
• Monitor Prometheus scrape interval

Debug Mode

Enable debug logging to troubleshoot issues:

// config/plugins.js
module.exports = {
  prometheus: {
    enabled: true,
    config: {
      // ... your config
    }
  }
};

Getting Help

• 🐛 Report bugs
• 💡 Request features
• 📖 Read the documentation
• ☕ Buy me a coffee

🏗️ v1 → v2 Migration Guide

🏗️ Migration Guide (v1 → v2)

Version 2.0 brings significant improvements and Strapi v5 support. Here's what you need to know:

🔧 Configuration Changes

Old (v1):

module.exports = {
  'strapi-prometheus': {
    enabled: true,
    config: {
      // v1 config
    }
  }
};

New (v2):

module.exports = {
  prometheus: {  // ← Plugin name simplified
    enabled: true,
    config: {
      // v2 config (see configuration section above)
    }
  }
};

🚀 New Features in v2

• Dedicated metrics server - Default behavior for better security
• Simplified configuration - Easier setup and maintenance
• Strapi v5 support - Future-ready compatibility
• Enhanced metrics - More comprehensive monitoring
• Improved performance - Optimized for production use

📊 Metric and Label Changes

🏷️ Enhanced Label Strategy

v2 Improvements:

• Smart route detection - Uses _matchedRoute when available for accurate patterns
• Consistent normalization - /api/articles/123 → /api/articles/:id
• Low cardinality - Prevents metric explosion from dynamic paths
• Added origin label - Track requests by source

🔄 Migration Steps

1. Update plugin name in your configuration
2. Review new configuration options (especially server settings)
3. Update Prometheus scrape config if using custom settings
4. Update Grafana dashboards with new metric names
5. Test thoroughly in development before production deployment

⚠️ Breaking Changes

• Apollo metrics removed - If you were using Apollo GraphQL metrics, you'll need to implement them separately
• Custom registry removed - Now uses the default prom-client registry (this actually gives you more flexibility!)
• Configuration structure changed - Follow the new configuration format

💡 Recommendations

• Start with default settings and customize as needed
• Use the dedicated metrics server (default behavior)
• Monitor your Prometheus targets after migration
• Consider this a good time to review your monitoring setup

🤝 Contributing

We welcome contributions! Here's how you can help:

🐛 Reporting Issues

• Use the issue tracker
• Search existing issues before creating new ones
• Provide clear reproduction steps
• Include environment details (Strapi version, Node.js version, OS)

💻 Development

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests if applicable
5. Commit with clear messages: git commit -m 'Add amazing feature'
6. Push to your branch: git push origin feature/amazing-feature
7. Open a Pull Request

📝 Documentation

• Improve README documentation
• Add code examples
• Create tutorials or blog posts
• Share Grafana dashboards

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author & Maintainer

Xander Denecker (@XanderD99)

• 🐙 GitHub: XanderD99
• ☕ Buy me a coffee: buymeacoffee.com/xanderd

🙏 Acknowledgments

• Prometheus - The monitoring system that makes this all possible
• prom-client - The Node.js Prometheus client library
• Strapi - The leading open-source headless CMS
• All contributors who have helped improve this plugin

⭐ If this plugin helps you, please consider giving it a star on GitHub!

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.3.0] - 2025-06-27

Added

• Intelligent route pattern extraction using _matchedRoute for low-cardinality metrics
• Advanced path normalization for consistent metric grouping
• Support for Strapi API routes, UUIDs, ObjectIds, and file uploads in route patterns
• Enhanced bucket configurations for better metric granularity

Changed

• BREAKING: Metric label path renamed to route for consistency
• Improved route labeling strategy to reduce metric cardinality
• Updated request duration buckets for better performance monitoring (removed 20s and 30s buckets)
• Enhanced content length bucket sizing (256KB to 1000MB range)
• Route pattern extraction now happens after routing middleware for accurate matched routes

Fixed

• Route pattern extraction timing issue - now correctly uses _matchedRoute after routing
• Consistent label usage across all HTTP metrics
• Better handling of dynamic route segments (IDs, UUIDs, file names)

[2.2.2] - 2025-06-27

Added

• Enhanced HTTP metrics collection with improved labels
• http_requests_total counter metric
• http_active_requests gauge metric
• lifecycle_duration_seconds histogram for Strapi lifecycle events
• Comprehensive README documentation with examples
• TypeScript configuration examples
• Docker Compose setup examples
• Troubleshooting guide and common issues section

Changed

• Improved plugin configuration structure and validation
• Enhanced security recommendations and documentation
• Better error handling and logging
• Updated Grafana dashboard examples with PromQL queries

Fixed

• Configuration syntax corrections in documentation
• Markdown formatting issues in README
• Link references and badge URLs

[2.1.0] - 2024-12-15

Added

• Support for custom labels on all metrics
• Enhanced server configuration options
• Better integration with Strapi v5 lifecycle events

Changed

• Improved performance for high-traffic applications
• Updated dependencies to latest versions

Fixed

• Memory leak issues with metric collection
• Server startup race conditions

[2.0.0] - 2024-06-01

Added

• Strapi v5 support - Full compatibility with the latest Strapi version
• Dedicated metrics server - Runs on separate port (9000) by default for better security
• New HTTP metrics:
  • http_requests_total - Total request counter
  • http_active_requests - Active requests gauge
• Enhanced configuration options - Simplified and more flexible setup
• TypeScript support - Full TypeScript definitions included

Changed

• Plugin name - Changed from strapi-prometheus to prometheus in configuration
• Default behavior - Separate metrics server is now the default (more secure)
• Metric names - Renamed for clarity and consistency:
  • http_request_duration_s → http_request_duration_seconds
  • http_request_size_bytes → http_request_content_length_bytes
  • http_response_size_bytes → http_response_content_length_bytes
• Registry handling - Now uses default prom-client registry for better flexibility
• Configuration structure - Simplified and more intuitive setup

Removed

• Apollo GraphQL metrics - Removed built-in Apollo support (use apollo-prometheus-exporter instead)
• Custom registry option - Now uses default registry for better ecosystem compatibility
• Legacy metric names - Old metric names are no longer supported

Migration

• See the Migration Guide for detailed upgrade instructions
• Configuration changes required for existing installations
• Prometheus scrape configuration may need updates for new metric names

[1.5.0] - 2023-01-31

Fixed

• Fixed GraphQL metrics always appearing in +inf bucket
• Resolved timing calculation issues for GraphQL operations

[1.4.0] - 2023-01-15

Added

• Options for extra registry configuration
• Default registry option support
• Apollo GraphQL metrics integration
• Enhanced metric collection capabilities

Changed

• Improved enabled metrics configuration options
• Updated metric collection strategies

[1.3.0] - 2022-12-12

Added

• Number of open connections metric for monitoring active connections
• Configurable interval settings for metric collection
• Enhanced connection tracking capabilities

[1.2.0] - 2022-11-27

Changed

• Automatic middleware registration when plugin is enabled (no manual setup required)
• Improved request/response content length calculation for better accuracy
• Enhanced middleware integration with Strapi's request lifecycle

[1.1.1] - 2022-11-17

Changed

• Updated allowed Node.js engines for better compatibility
• Improved package.json engine specifications

[1.1.0] - 2022-11-04

Changed

• Single metric endpoint now correctly uses registry and handles errors properly
• Improved error handling and response formatting for metrics endpoints

Removed

• Authentication restrictions that previously forced API key usage
• Simplified access to metrics endpoints

[1.0.0] - 2022-11-04

Added

• Initial release of strapi-prometheus plugin
• Basic HTTP metrics collection for Strapi applications
• Endpoint to retrieve individual metrics
• Integration with Prometheus monitoring ecosystem
• Support for Strapi v4.x applications