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.
• Labeled Endpoints: Select specific endpoints for more granular metrics extraction.

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    
    - status_code
    - host
    - consumer_tag

  metric_value:
    - name: api_call_count
      description: Number of API calls
    - name: api_call_size
      description: Average size of API calls
    - name: transaction_duration 
      description: Transaction total duration (gateway time + provider time), ms
      buckets: [100, 200, 500, 750, 1000, 2000, 5000, 10000]
    - name: provider_transaction_duration  
      description: Provider time (the round trip time from gateway to provider), ms
      buckets: [10, 20, 50, 100, 200, 500, 750, 1000, 2000, 5000, 10000]

system_metrics:
  - name: active_flows
    description: Number of active flows
  - name: flow_invocations
    description: Number of flow invocations
  - name: requests_through_flows
    description: Number of requests through flows
  - name: avg_flow_execution_time
    description: Average flow execution time
  - name: avg_processor_execution_time
    description: Average processor execution time

labeled_endpoints:       
  - api.github.com/endpoint/{with-without-lunar}
  - api.salesforce.com/services/{param}/{param}
  - api.anthropic.com/{v1}/{messages}/{with-lunar} 

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, GenerateResponse, CountLLMTokens, or RetryProcessor. 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
CountLLMTokens	lunar_llm_tokens_count

Processors' 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, RetryProcessor, CountLLMTokens):

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