Skip to main content
Version: 1.1.x

Custom Metrics Collection Flow

The Custom Metrics Collector Flow tracks user-defined metrics for API requests and responses, such as request size or rate limits. This flow helps monitor API performance and usage patterns in real-time, offering flexibility with histograms, gauges, and other metric types.

Once this flow is running your metrics will be written to Prometheus which can be accessed directly at localhost:9090 or accessing Grafana at localhost:3000.

Flow Diagram

Scenarios​

  1. Track API Call Sizes: Monitor API payload sizes to identify performance-impacting requests.
  2. Monitor Rate Limit Usage: Track remaining rate limits from responses to manage API consumption.
  3. Analyze Request Trends: Use custom labels to analyze traffic based on HTTP methods, URLs, or headers.
  4. Performance Metrics: Measure performance of API endpoints to optimize response times and reduce overhead.

Flow Configuration Template​

/etc/lunar-proxy/flows/flow.yaml
name: <FlowName> # The name of the flow, e.g., ClientSideLimitingFlow

filter:
  url: <URLPattern> # Define the URL pattern for the filter, e.g., api.example.com/*
  method: ["<HTTPMethod>"] # Optional: List of HTTP methods, e.g., GET, POST
  headers:
    - key: <HeaderKey> # Optional: Header key, e.g., 'X-API-Key'
      value: <HeaderValue> # Optional: header value, e.g., '12345', '67890'
processors:
  RequestMetrics: # Collect custom metrics for API requests
    processor: UserDefinedMetrics
    parameters:
      - key: metric_name
        value: "call_size" # Name of the metric to track
      - key: metric_type
        value: "histogram" # Metric type (e.g., histogram)
      - key: metric_value
        value: "api_call_size" # Metric value based on request size
      - key: custom_metric_labels #Map of custom label name/value pairs used as label for the metric specified     
        value:
          "x-lunar-context": "$[\"headers\"][\"x-lunar-temp-context\"]"
          "x-lunar-special-context": "$[\"headers\"][\"x-lunar-special-context\"]"  
      - key: labels
        value:
          - "http_method" # Label for HTTP method
          - "url" # Label for URL
          - "consumer_tag" # Label for consumer tag
      - key: buckets
        value: # Define the histogram buckets
          - 0
          - 100
          - 250
          - 500
          - 1000
          - 2500
          - 5000
          - 10000
  ResponseMetrics: # Collect custom metrics for API responses
    processor: UserDefinedMetrics
    parameters:
      - key: metric_name
        value: "call_size" # Name of the metric to track
      - key: metric_type
        value: "histogram" # Metric type (e.g., histogram)
      - key: metric_value
        value: "api_call_size" # Metric value based on request size
      - key: custom_metric_labels #Map of custom label name/value pairs used as label for the metric specified     
        value:
          "x-lunar-context": "$[\"headers\"][\"x-lunar-temp-context\"]"
          "x-lunar-special-context": "$[\"headers\"][\"x-lunar-special-context\"]"  
      - key: labels
        value:
          - "http_method" # Label for HTTP method
          - "url" # Label for URL
          - "consumer_tag" # Label for consumer tag
      - key: buckets
        value: # Define the histogram buckets
          - 0
          - 100
          - 250
          - 500
          - 1000
          - 2500
          - 5000
          - 10000
flow:
  request:
    - from:
        stream:
          name: globalStream
          at: start # Start of the request flow
      to:
        processor:
          name: RequestMetrics # Apply custom request metrics

    - from:
        processor:
          name: RequestMetrics # After collecting metrics
      to:
        stream:
          name: globalStream
          at: end # End of the request flow

  response:
    - from:
        stream:
          name: globalStream
          at: start # Start of the response flow
      to:
        processor:
          name: ResponseMetrics # Apply custom response metrics

    - from:
        processor:
          name: ResponseMetrics # After collecting response metrics
      to:
        stream:
          name: globalStream
          at: end # End of the response flow

Flow Example​

In this configuration:

  • API Request Metrics: The flow captures the size of each API call (api_call_size) and categorizes the data into histogram buckets. Metrics are labeled with http_method, url, and consumer_tag to allow detailed tracking.
  • API Response Metrics: The flow collects the remaining rate limits from API responses using the X-Ratelimit-Remaining header, stored as a gauge metric with the url as a label.
/etc/lunar-proxy/flows/flow.yaml
name: CustomMetricsCollector
filter:
  url: "*" # Capture metrics for all URLs
processors:
  RequestMetrics: # Collect custom metrics for API requests
    processor: UserDefinedMetrics
    parameters:
      - key: metric_name
        value: "call_size" # Name of the metric to track
      - key: metric_type
        value: "histogram" # Metric type (e.g., histogram)
      - key: metric_value
        value: "api_call_size" # Metric value based on request size
      - key: labels
        value:
          - "http_method" # Label for HTTP method
          - "url" # Label for URL
          - "consumer_tag" # Label for consumer tag
      - key: buckets
        value: # Define the histogram buckets
          - 0
          - 100
          - 250
          - 500
          - 1000
          - 2500
          - 5000
          - 10000
  ResponseMetrics: # Collect custom metrics for API responses
    processor: UserDefinedMetrics
    parameters:
      - key: metric_name
        value: "rate_limit_remaining" # Metric to track remaining rate limits
      - key: metric_type
        value: "gauge" # Metric type (e.g., gauge)
      - key: metric_value
        value: "$[\"headers\"][\"X-Ratelimit-Remaining\"]" # JSON path for rate limit from headers
      - key: labels
        value:
          - "url" # Label for URL
      - key: custom_metric_labels
        value:
          "x-lunar-context": "$[\"headers\"][\"x-lunar-temp-context\"]"
          "x-lunar-special-context": "$[\"headers\"][\"x-lunar-special-context\"]" 
      - key: buckets
        value: [] # No buckets needed for gauge
flow:
  request:
    - from:
        stream:
          name: globalStream
          at: start # Start of the request flow
      to:
        processor:
          name: RequestMetrics # Apply custom request metrics
    - from:
        processor:
          name: RequestMetrics # After collecting metrics
      to:
        stream:
          name: globalStream
          at: end # End of the request flow
  response:
    - from:
        stream:
          name: globalStream
          at: start # Start of the response flow
      to:
        processor:
          name: ResponseMetrics # Apply custom response metrics
    - from:
        processor:
          name: ResponseMetrics # After collecting response metrics
      to:
        stream:
          name: globalStream
          at: end # End of the response flow

Flow Components​