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 with just a few lines of configuration! 🚀

• 🚀 Real-time API Metrics - Track HTTP request duration, payload sizes, and response codes with intelligent route normalization
• 📈 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 across environments 🌍
• 📊 Database Lifecycle Tracking - Monitor Strapi lifecycle events (create, update, delete) duration ⚡
• 🔌 Easy Integration - Simple configuration with sensible defaults - get started in minutes!
• 🆔 Version Tracking - Monitor Strapi version information for deployment tracking
• 🎯 Smart Path Normalization - Flexible normalization with regex patterns or custom functions to group similar routes for better metric cardinality 📊
• 📦 TypeScript Support - Built with TypeScript for better developer experience

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

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

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
      
      // 🎯 Path Normalization Rules
      normalize: [
        [/\/(?:[a-z0-9]{24,25}|\d+)(?=\/|$)/, '/:id'], // Document IDs or numeric IDs
        [/\/uploads\/[^\/]+\.[a-zA-Z0-9]+/, '/uploads/:file'], // Uploaded files with extensions
      ]
    }
  }
};

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'
      },
      
      // Custom normalization function (alternative to array rules)
      normalize: (ctx) => {
        let path = ctx.path;
        
        // Custom logic for your specific needs
        if (path.startsWith('/api/')) {
          path = path.replace(/\/\d+/g, '/:id'); // Replace numeric IDs
        }
        
        return path;
      }
    }
  }
};

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

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

The plugin features intelligent path normalization to ensure optimal metric cardinality by grouping similar routes together ✨

You can configure path normalization in two ways:

Use an array of [RegExp, replacement] tuples to define normalization patterns:

normalize: [
  [/\/(?:[a-z0-9]{24,25}|\d+)(?=\/|$)/, '/:id'], // Document IDs or numeric IDs
  [/\/uploads\/[^\/]+\.[a-zA-Z0-9]+/, '/uploads/:file'], // Uploaded files with extensions
  
  // Custom patterns
  [/\/users\/\d+/, '/users/:id'],                                   // /users/123
  [/\/orders\/ORD\d+/, '/orders/:orderCode']                        // /orders/ORD12345
]

Use a function for dynamic normalization logic:

normalize: (ctx) => {
  let path = ctx.path;
  
  // Custom normalization logic
  if (path.startsWith('/api/')) {
    path = path.replace(/\/\d+/g, '/:id');           // Replace numeric IDs
    path = path.replace(/\/[a-f0-9-]{36}/gi, '/:uuid'); // Replace UUIDs
  }
  
  // Multi-tenant example
  if (path.startsWith('/tenant/')) {
    path = path.replace(/^\/tenant\/[^\/]+/, '/tenant/:id');
  }
  
  return path;
}

The plugin includes pre-configured patterns for common Strapi routes:

• ✅ Low Cardinality - Groups similar routes to prevent metric explosion
• ✅ Prometheus-Friendly - Follows Prometheus best practices
• ✅ Flexible - Support both regex patterns and custom functions
• ✅ Performance - Efficient pattern matching with minimal overhead
• ✅ Strapi-Aware - Built-in knowledge of Strapi routing conventions

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

By default, metrics are served on a separate server:

curl http://localhost:9000/metrics

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/api/metrics

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

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.

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

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

• Dashboard 14565 - Comprehensive Strapi monitoring dashboard

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

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

• 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

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

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

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

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)
    }
  }
};

• 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

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

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

• 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

• 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

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

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

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 🔄

• Improve README documentation 📖
• Add code examples 💡
• Create tutorials or blog posts ✍️
• Share Grafana dashboards 📊

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

Xander Denecker (@XanderD99)

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

• 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!