Version: Next

UserDefinedMetrics Processor

Overview

The UserDefinedMetrics processor allows users to extract specific values from event payloads and record them as custom metrics. These metrics can be leveraged for monitoring, analytics, and operational insights. The processor supports multiple configuration options to provide flexibility in data extraction and transformation.

UserDefinedMetrics

Input and Output

This processor operates on both the request and response streams:

Input Stream: Request/Response – The processor listens to requests and responses, extracting relevant data based on user-defined rules.
Output Stream: Request/Response – The processor does not alter or block the flow; instead, it logs the extracted metrics and passes the event through unchanged.

This ensures that metrics are collected while allowing the request or response to continue through the processing pipeline without disruption.

Parameters

Each parameter is defined as a key-value pair inside the parameters section.

metric_name

Required: True
Type: string
Defines the name of the metric to be exposed. This can be any string.

Example:

- key: metric_name
  value: "total_tokens"

metric_type

Required: False
Type: string
Default: counter
Specifies the type of metric. Supported types: counter, up_down_counter, gauge, histogram.

Example:

- key: metric_type
  value: "histogram"

metric_value

Required: False
Type: string
Default: counter
Determines the value to track for the metric. Can be predefined values like api_call_count, api_call_size, or a JSON path to extract data from requests or responses (e.g., $.response.body.errors.count). If extracting matrics from a JSON path, the value must be numeric.

Example:

- key: metric_value
  value: "$.response.body.usage.total_tokens"

custom_metric_labels

Required: False
Type: map_of_strings
Defines a map of custom label name/value pairs for additional metric tagging. The value can be extracted from headers or payloads (e.g., $['headers']['lunar-custom-context']).

Example:

- key: custom_metric_labels
  value:
    "x-lunar-context": "$.response.body.x-lunar-temp-context"
    "x-lunar-special-context": "$.response.header.x-lunar-special-context" 

labels

Required: False
Type: list of strings (Default: [])
Defines a list of labels that can be used to add context to metrics. These labels can include predefined values or JSON paths to extract data from request bodies or headers.

Common labels include:

Label Name	Description
`http_method`	The HTTP method used in the request.
`url` ⚠️	The request URL.
`host`	The request host name.
`status_code`	The HTTP response status code.
`consumer_tag`	Identifier for the consuming entity.

URL

When using the label URL on a flow with multiple different urls the metrics exposed by Lunar.dev will be inflated.

Example:

- key: labels
  value:
    - "consumer_tag"
    - "$.response.body.error.type"

buckets

Required: False
Type: list of numbers (Default: [])
Defines threshold values for histogram metrics. This parameter is required if metric_type is set to histogram.

Example:

- key: buckets
  value: [0, 100, 250, 500, 1000, 2500, 5000, 10000]

Best Practices

Use a descriptive metric_name to simplify analysis.
Ensure metric_value accurately represents the data being measured.
Define meaningful labels to provide context for the metric.
When using histogram, carefully choose buckets to match expected data distributions.

For more details on configuring flows, visit the Lunar.dev Flows Documentation.