Metrics Setup

The Metrics Setup page provides guidance on configuring and monitoring metrics within Lunar.dev’s API Consumption Gateway. Lunar.dev supports exporting these metrics to popular monitoring tools like Datadog, Grafana, and Prometheus for real-time tracking and analysis of API traffic and system performance.

Why Metrics Matter

Tracking and analyzing API traffic and system performance metrics is essential for optimizing API usage, ensuring system health, and diagnosing issues. Lunar.dev offers a comprehensive view of your API operations and system health, enabling quick action when necessary.

Default Metrics Configuration

Metrics are exposed via the /metrics endpoint on port 3000, configured in the metrics.yaml file located at /etc/lunar-proxy/metrics.yaml. Metrics are organized into two main categories:

• General Metrics: Track API traffic with labels such as http_method, url, status_code, and consumer_tag.
• System Metrics: Monitor internal flow efficiency and performance with metrics like active_flows and flow_invocations.

note

If a custom metrics.yaml file is not provided, a default file will be loaded.

Template metrics.yaml File

general_metrics:
  label_value:
    - http_method
    - url
    - status_code
    - consumer_tag  # Enables tracking of consumer-specific API usage

  metric_value:
    - name: api_call_count
      type: counter  # Counts the number of all API calls running through the gateway
    - name: api_call_size
      type: gauge    # Measures API request size that running through the gateway flows engine

system_metrics:
  - name: active_flows
    type: gauge      # Active flows count
  - name: flow_invocations
    type: counter    # Flow invocation count
  - name: requests_through_flows
    type: counter    # Total requests processed
  - name: avg_flow_execution_time
    type: gauge      # Average flow execution time
  - name: avg_processor_execution_time
    type: gauge      # Average processor execution time

Configuring Processor Metrics

In addition to default system and general metrics, you can enable metrics for each flow processor to monitor specific performance metrics. Supported processors include:

• Filter: Applies conditional logic to requests.
• Limiter: Enforces quotas on resource usage.
• Queue: Introduces priority-based request queuing.
• GenerateResponse: Generates custom responses, often for rate limits.

Each processor can be assigned a unique ProcessorName (any string), with ProcessorType set to Filter, Limiter, Queue, or GenerateResponse. Each type has its own set of associated metrics:

Processor	Metric
Filter	lunar_filter_processor_hit_count, lunar_filter_processor_miss_count
Limiter	lunar_limiter_processor_below_count, lunar_limiter_processor_above_count
Queue	lunar_processor_queue_requests_in_queue, lunar_processor_queue_requests_handled
GenerateResponse	lunar_generated_response_count

Example Processor Metrics Configuration

The following example shows how to enable metrics for any processor. Use this configuration template for Filter, Limiter, Queue, and GenerateResponse processors, substituting [ProcessorName] with a unique name and [ProcessorType] with the specific processor type (e.g., Filter, Limiter, Queue, GenerateResponse).

processors:
  [ProcessorName]:  # Any unique identifier, e.g., "RateLimiter", "AccessFilter"
    processor: [ProcessorType]  # Processor type: Limiter, GenerateResponse, Filter, or Queue
    parameters:
      # Add parameters specific to each processor type
    metrics:
      enabled: true
      labels:
        - flow_name
        - processor_key
        - http_method
        - url
        - status_code
        - consumer_tag  # Enables consumer tracking on a per-processor basis

This template configures metrics with labels to track usage and performance metrics for the processor.

Integrating with Monitoring Tools

After configuring processor metrics, you can integrate them with monitoring tools like Grafana, Prometheus, or Datadog for real-time visualization and analysis.

For Prometheus Integration, refer to the Prometheus Integration page for details on configuring Prometheus to scrape metrics from Lunar.dev’s /metrics endpoint.