Policy Language Specification

The overload_confirmation port provides additional criteria to determine overload state which results in Flow throttling at the service.

setpoint

(InPort, required)

The setpoint input to the controller.

signal

(InPort, required)

The input signal to the controller.

AIADLoadSchedulerOuts

Output ports for the AIAD Load Scheduler.

desired_load_multiplier

Desired Load multiplier is the ratio of desired token rate to the incoming token rate.

is_overload

A Boolean signal that indicates whether the service is in overload state.

observed_load_multiplier

Observed Load multiplier is the ratio of accepted token rate to the incoming token rate.

AIADLoadSchedulerParameters

alerter

(AlerterParameters, required)

Configuration parameters for the embedded Alerter.

load_multiplier_linear_decrement

(float64, minimum: 0, default: 0.05)

Linear decrement to load multiplier every 10 seconds while the system is in the overloaded state, up until the min_load_multiplier is reached.

load_multiplier_linear_increment

(float64, minimum: 0, default: 0.025)

Linear increment to load multiplier every 10 seconds while the system is not in the overloaded state, up until the max_load_multiplier is reached.

load_scheduler

(LoadSchedulerParameters, required)

Parameters for the Load Scheduler.

max_load_multiplier

(float64, minimum: 0, default: 2)

The maximum load multiplier that can be reached during recovery from an overload state.

Helps protect the service from request bursts while the system is still recovering.
Once this value is reached, the scheduler enters the pass-through mode, allowing requests to bypass the scheduler and be sent directly to the service.
The pass-through mode gets disabled if the system enters the overload state again.

min_load_multiplier

(float64, minimum: 0, default: 0)

The minimum load multiplier that can be reached during an overload state.

AIMDLoadScheduler

AIMD Load Scheduler uses a Gradient Controller to throttle the token rate based on the deviation of the signal from the setpoint. It takes a signal and setpoint as inputs and reduces token rate proportionally (or any arbitrary power) based on deviation of the signal from setpoint. During recovery, it increases the token rate linearly until the system is not overloaded.

dry_run

(bool)

dry_run_config_key

(string)

Configuration key for setting dry run mode through dynamic configuration.

in_ports

(AIMDLoadSchedulerIns)

Input ports for the AIMD Load Scheduler.

out_ports

(AIMDLoadSchedulerOuts)

Output ports for the AIMD Load Scheduler.

parameters

(AIMDLoadSchedulerParameters, required)

Parameters for the AIMD Load Scheduler.

AIMDLoadSchedulerIns

Input ports for the AIMD Load Scheduler.

overload_confirmation

The overload_confirmation port provides additional criteria to determine overload state which results in Flow throttling at the service.

setpoint

(InPort, required)

The setpoint input to the controller.

signal

(InPort, required)

The input signal to the controller.

AIMDLoadSchedulerOuts

Output ports for the AIMD Load Scheduler.

desired_load_multiplier

Desired Load multiplier is the ratio of desired token rate to the incoming token rate.

is_overload

A Boolean signal that indicates whether the service is in overload state.

observed_load_multiplier

(AdaptiveLoadSchedulerOuts)

Observed Load multiplier is the ratio of accepted token rate to the incoming token rate.

AIMDLoadSchedulerParameters

alerter

(AlerterParameters, required)

Configuration parameters for the embedded Alerter.

gradient

(GradientControllerParameters, required)

Parameters for the Gradient Controller.

load_multiplier_linear_increment

(float64, minimum: 0, default: 0.025)

Linear increment to load multiplier every 10 seconds while the system is not in the overloaded state, up until the max_load_multiplier is reached.

load_scheduler

(LoadSchedulerParameters, required)

Parameters for the Load Scheduler.

max_load_multiplier

(float64, minimum: 0, default: 2)

The maximum load multiplier that can be reached during recovery from an overload state.

Helps protect the service from request bursts while the system is still recovering.
Once this value is reached, the scheduler enters the pass-through mode, allowing requests to bypass the scheduler and be sent directly to the service.
The pass-through mode gets disabled if the system enters the overload state again.

AdaptiveLoadScheduler

The Adaptive Load Scheduler adjusts the accepted token rate based on the deviation of the input signal from the setpoint. Deprecated: v3.0.0. Use AIMDLoadScheduler instead.

dry_run

(bool)

dry_run_config_key

(string)

Configuration key for setting dry run mode through dynamic configuration.

in_ports

(AdaptiveLoadSchedulerIns, required)

Collection of input ports for the Adaptive Load Scheduler component.

out_ports

Collection of output ports for the Adaptive Load Scheduler component.

parameters

(AdaptiveLoadSchedulerParameters, required)

Parameters for the Adaptive Load Scheduler component.

AdaptiveLoadSchedulerIns

Input ports for the Adaptive Load Scheduler component.

overload_confirmation

The overload_confirmation port provides additional criteria to determine overload state which results in Flow throttling at the service.

setpoint

(InPort, required)

The setpoint input to the controller.

signal

(InPort, required)

The input signal to the controller.

AdaptiveLoadSchedulerOuts

Output ports for the Adaptive Load Scheduler component.

desired_load_multiplier

Desired Load multiplier is the ratio of desired token rate to the incoming token rate.

is_overload

A Boolean signal that indicates whether the service is in overload state.

observed_load_multiplier

Observed Load multiplier is the ratio of accepted token rate to the incoming token rate.

AdaptiveLoadSchedulerParameters

Parameters for the Adaptive Load Scheduler component.

alerter

(AlerterParameters, required)

Configuration parameters for the embedded Alerter.

gradient

(GradientControllerParameters, required)

Parameters for the Gradient Controller.

load_multiplier_linear_increment

(float64, default: 0.0025)

Linear increment to load multiplier every 10 seconds while the system is not in the overloaded state, up until the max_load_multiplier is reached.

load_scheduler

(LoadSchedulerParameters, required)

Parameters for the Load Scheduler.

max_load_multiplier

(float64, default: 2)

The maximum load multiplier that can be reached during recovery from an overload state.

Helps protect the service from request bursts while the system is still recovering.
Once this value is reached, the scheduler enters the pass-through mode, allowing requests to bypass the scheduler and be sent directly to the service.
The pass-through mode gets disabled if the system enters the overload state again.

AddressExtractor

Display an Address as a single string, for example, <ip>:<port>

IP addresses in attribute context are defined as objects with separate IP and port fields. This is a helper to display an address as a single string.

caution

This might introduce high-cardinality flow label values.

Example:

from: "source.address # or destination.address"

from

(string, required)

Attribute path pointing to some string - for example, source.address.

Alerter

Alerter reacts to a signal and generates alert to send to alert manager.

in_ports

(AlerterIns)

Input ports for the Alerter component.

parameters

(AlerterParameters, required)

Alerter configuration

AlerterIns

Inputs for the Alerter component.

signal

Signal which Alerter is monitoring. If the signal greater than 0, Alerter generates an alert.

AlerterParameters

Alerter Parameters configure parameters such as alert name, severity, resolve timeout, alert channels and labels.

alert_channels

([]string)

A list of alert channel strings.

alert_name

(string, required)

Name of the alert.

labels

(map of string)

Additional labels to add to alert.

resolve_timeout

(string, default: "5s")

Duration of alert resolver. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

severity

(string, one of: info | warn | crit, default: "info")

Severity of the alert, one of 'info', 'warn' or 'crit'.

And

Logical AND.

Signals are mapped to Boolean values as follows:

Zero is treated as false.
Any non-zero is treated as true.
Invalid inputs are considered unknown.
note
Treating invalid inputs as "unknowns" has a consequence that the result might end up being valid even when some inputs are invalid. For example, unknown && false == false, because the result would end up false no matter if first signal was true or false. Conversely, unknown && true == unknown.

in_ports

(AndIns)

Input ports for the And component.

out_ports

(AndOuts)

Output ports for the And component.

AndIns

Inputs for the And component.

inputs

Array of input signals.

AndOuts

Output ports for the And component.

output

(ArithmeticCombinatorIns)

Result of logical AND of all the input signals.

Will always be 0 (false), 1 (true) or invalid (unknown).

ArithmeticCombinator

Type of Combinator that computes the arithmetic operation on the operand signals

in_ports

Input ports for the Arithmetic Combinator component.

operator

(string, one of: add | sub | mul | div | xor | lshift | rshift)

Operator of the arithmetic operation.

The arithmetic operation can be addition, subtraction, multiplication, division, XOR, right bit shift or left bit shift. In case of XOR and bit shifts, value of signals is cast to integers before performing the operation.

out_ports

(ArithmeticCombinatorOuts)

Output ports for the Arithmetic Combinator component.

ArithmeticCombinatorIns

Inputs for the Arithmetic Combinator component.

lhs

Left hand side of the arithmetic operation.

rhs

Right hand side of the arithmetic operation.

ArithmeticCombinatorOuts

Outputs for the Arithmetic Combinator component.

output

(AutoScalerScalingBackendKubernetesReplicasOuts)

Result of arithmetic operation.

AutoScale

AutoScale components are used to scale a service.

auto_scaler

(AutoScaler)

AutoScaler provides auto-scaling functionality for any scalable resource.

pod_scaler

(PodScaler)

PodScaler provides pod horizontal scaling functionality for scalable Kubernetes resources.

AutoScaler

AutoScaler provides auto-scaling functionality for any scalable resource. Multiple Controllers can be defined on the AutoScaler for performing scale-out or scale-in. The AutoScaler can interface with infrastructure APIs such as Kubernetes to perform auto-scale.

dry_run

(bool)

Dry run mode ensures that no scaling is invoked by this auto scaler. This is useful for observing the behavior of auto scaler without disrupting any real deployment. This parameter sets the default value of dry run setting which can be overridden at runtime using dynamic configuration.

dry_run_config_key

(string)

Configuration key for overriding dry run setting through dynamic configuration.

scale_in_controllers

([]ScaleInController)

List of Controllers for scaling in.

scale_out_controllers

([]ScaleOutController)

List of Controllers for scaling out.

scaling_backend

(AutoScalerScalingBackend, required)

scaling_parameters

(AutoScalerScalingParameters, required)

Parameters that define the scaling behavior.

AutoScalerScalingBackend

kubernetes_replicas: (AutoScalerScalingBackendKubernetesReplicas)

AutoScalerScalingBackendKubernetesReplicas

KubernetesReplicas defines a horizontal pod scaler for Kubernetes.

kubernetes_object_selector

(KubernetesObjectSelector, required)

The Kubernetes object on which horizontal scaling is applied.

max_replicas

(string, default: "9223372036854775807")

The maximum replicas to which the AutoScaler can scale-out.

min_replicas

(string, default: "0")

The minimum replicas to which the AutoScaler can scale-in.

out_ports

Output ports for Kubernetes Replicas.

AutoScalerScalingBackendKubernetesReplicasOuts

Outputs

actual_replicas: (OutPort)
configured_replicas: (OutPort)
desired_replicas: (OutPort)

AutoScalerScalingParameters

cooldown_override_percentage

(float64, default: 50)

Cooldown override percentage defines a threshold change in scale-out beyond which previous cooldown is overridden. For example, if the cooldown is 5 minutes and the cooldown override percentage is 10%, then if the scale-increases by 10% or more, the previous cooldown is canceled. Defaults to 50%.

max_scale_in_percentage

(float64, default: 1)

The maximum decrease of scale (for example, pods) at one time. Defined as percentage of current scale value. Can never go below one even if percentage computation is less than one. Defaults to 1% of current scale value.

max_scale_out_percentage

(float64, default: 10)

The maximum increase of scale (for example, pods) at one time. Defined as percentage of current scale value. Can never go below one even if percentage computation is less than one. Defaults to 10% of current scale value.

scale_in_alerter

(AlerterParameters, required)

Configuration for scale-in Alerter.

scale_in_cooldown

(string, default: "120s")

The amount of time to wait after a scale-in operation for another scale-in operation. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

scale_out_alerter

(AlerterParameters, required)

Configuration for scale-out Alerter.

scale_out_cooldown

(string, default: "30s")

The amount of time to wait after a scale-out operation for another scale-out or scale-in operation. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

BoolVariable

Component that emits a constant Boolean signal which can be changed at runtime through dynamic configuration.

config_key

(string)

Configuration key for overriding value setting through dynamic configuration.

constant_output

(bool)

The constant Boolean signal emitted by this component. The value of the constant Boolean signal can be overridden at runtime through dynamic configuration.

out_ports

(BoolVariableOuts)

Output ports for the BoolVariable component.

BoolVariableOuts

Outputs for the BoolVariable component.

output

(ConcurrencyLimiterRequestParameters)

The value is emitted to the output port.

Circuit

Circuit is graph of inter-connected signal processing components.

info

Classifier

Set of classification rules sharing a common selector

info

Component

Computational block that forms the circuit

info

ConcurrencyLimiter

in_ports

(ConcurrencyLimiterIns, required)

Input ports for the Concurrency Limiter component.

out_ports

(ConcurrencyLimiterOuts)

Output ports for the Concurrency Limiter component.

parameters

(ConcurrencyLimiterParameters, required)

Parameters for the Concurrency Limiter component.

request_parameters

RequestParameters for the component

selectors

([]Selector, required)

Selectors for the component.

ConcurrencyLimiterIns

Inputs for the Concurrency Limiter or Concurrency Scheduler component

max_concurrency

(InPort, required)

The maximum number of concurrent requests to be allowed.

pass_through

PassThrough port determines whether to accept all requests instantaneously

ConcurrencyLimiterOuts

Outputs for the Concurrency Limiter or Concurrency Scheduler component.

accept_percentage

The percentage of flows being accepted by the Concurrency Limiter.

ConcurrencyLimiterParameters

limit_by_label_key

(string)

Specifies which label the concurrency calculation should be keyed by.

Concurrency limiting is done independently for each value of the label with given key. For example, to give each API Key a separate limit, assuming you have a api_key flow label set up, set limit_by_label_key: "api_key". If no label key is specified, then all requests matching the selectors will be concurrency limited based on the global concurrency count.

max_idle_time

(string, default: "7200s")

Max idle time before concurrency count for a label is removed. If set to 0, the state is never removed. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

max_inflight_duration

(string, required)

The time duration after which flow is assumed to have ended in case the end call gets missed. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

ConcurrencyLimiterRequestParameters

denied_response_status_code

This field allows you to override the default HTTP status code (429 Too Many Requests) that is returned when a request is denied.

tokens_label_key

(string)

Flow label key that will be used to override the number of tokens for this request. This is an optional parameter and takes highest precedence when assigning tokens to a request. The label value must be a valid number.

ConcurrencyScheduler

Schedules the traffic based on in-flight request concurrency.

concurrency_limiter

(ConcurrencyLimiterParameters, required)

Parameter to configure concurrency limiting.

in_ports

(ConcurrencyLimiterIns, required)

Input ports for the Concurrency Scheduler component

out_ports

(ConcurrencyLimiterOuts)

Output ports for the Concurrency Scheduler component.

scheduler

(Scheduler)

Scheduler is used to schedule the requests when the concurrency limit is reached.

selectors

([]Selector, required)

Flow selection criteria.

ConstantSignal

Special constant input for ports and Variable component. Can provide either a constant value or special Nan/+-Inf value.

special_value

(string, one of: NaN | +Inf | -Inf)

A special value such as NaN, +Inf, -Inf.

value

(float64)

A constant value.

Decider

Type of Combinator that computes the comparison operation on LHS and RHS signals

The comparison operator can be greater-than, less-than, greater-than-or-equal, less-than-or-equal, equal, or not-equal.

This component also supports time-based response (the output) transitions between 1.0 or 0.0 signal if the decider condition is true or false for at least true_for or false_for duration. If true_for and false_for durations are zero then the transitions are instantaneous.

false_for

(string, default: "0s")

Duration of time to wait before changing to false state. If the duration is zero, the change will happen instantaneously. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

in_ports

(DeciderIns)

Input ports for the Decider component.

operator

(string, one of: gt | lt | gte | lte | eq | neq)

Comparison operator that computes operation on LHS and RHS input signals.

out_ports

(DeciderOuts)

Output ports for the Decider component.

true_for

(string, default: "0s")

Duration of time to wait before changing to true state. If the duration is zero, the change will happen instantaneously.``` This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

DeciderIns

Inputs for the Decider component.

lhs

Left hand side input signal for the comparison operation.

rhs

Right hand side input signal for the comparison operation.

DeciderOuts

Outputs for the Decider component.

output

(DecreasingGradientParameters)

Selected signal (1.0 or 0.0).

DecreasingGradient

Decreasing Gradient defines a controller for scaling in based on Gradient Controller.

in_ports

(DecreasingGradientIns)

Input ports for the Gradient.

parameters

Gradient parameters for the controller. Defaults and constraints:

slope = 1
min_gradient = -Inf (must be less than 1)
max_gradient = 1 (cannot be changed)

DecreasingGradientIns

Inputs for Gradient.

setpoint

The setpoint to use for scale-in.

signal

The signal to use for scale-in.

DecreasingGradientParameters

This allows subset of parameters with constrained values compared to a regular gradient controller. For full documentation of these parameters, refer to the GradientControllerParameters.

min_gradient: (float64, default: -1.7976931348623157e+308)
slope: (float64, default: 1)

Differentiator

Differentiator calculates rate of change per tick.

in_ports

(DifferentiatorIns)

Input ports for the Differentiator component.

out_ports

(DifferentiatorOuts)

Output ports for the Differentiator component.

window

(string, default: "5s")

The window of time over which differentiator operates. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

DifferentiatorIns

Inputs for the Differentiator component.

input: (InPort)

DifferentiatorOuts

Outputs for the Differentiator component.

output: (OutPort)

EMA

Exponential Moving Average (EMA) is a type of moving average that applies exponentially more weight to recent signal readings

At any time EMA component operates in one of the following states:

Warm up state: The first warmup_window samples are used to compute the initial EMA. If an invalid reading is received during the warmup_window, the last good average is emitted and the state gets reset back to beginning of warm up state.
Normal state: The EMA is computed using following formula.

The EMA for a series $Y$ is calculated recursively as:

\text{EMA} _t = \begin{cases} Y_0, &\text{for } t = 0 \\ \alpha Y_t + (1 - \alpha) \text{EMA}_{t-1}, &\text{for }t > 0 \end{cases}

The coefficient $\alpha$ represents the degree of weighting decrease, a constant smoothing factor between 0 and 1. A higher $\alpha$ discounts older observations faster. The $\alpha$ is computed using ema_window:

\alpha = \frac{2}{N + 1} \quad\text{where } N = \frac{\text{ema\_window}}{\text{evaluation\_period}}

in_ports

(EMAIns)

Input ports for the EMA component.

out_ports

(EMAOuts)

Output ports for the EMA component.

parameters

(EMAParameters, required)

Parameters for the EMA component.

EMAIns

Inputs for the EMA component.

input

Input signal to be used for the EMA computation.

max_envelope

Upper bound of the moving average.

When the signal exceeds max_envelope it is multiplied by correction_factor_on_max_envelope_violation once per tick.

note

If the signal deviates from max_envelope faster than the correction faster, it might end up exceeding the envelope.

min_envelope

Lower bound of the moving average.

Behavior is similar to max_envelope.

EMAOuts

Outputs for the EMA component.

output

Exponential moving average of the series of reading as an output signal.

EMAParameters

Parameters for the EMA component.

correction_factor_on_max_envelope_violation

(float64, minimum: 0, default: 1)

Correction factor to apply on the output value if its in violation of the max envelope.

correction_factor_on_min_envelope_violation

(float64, default: 1)

Correction factor to apply on the output value if its in violation of the min envelope.

ema_window

(string, required)

EMA window duration. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

valid_during_warmup

(bool, default: false)

Whether the output is valid during the warm-up stage.

warmup_window

(string, required)

Duration of EMA warming up window.

The initial value of the EMA is the average of signal readings received during the warm up window. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

EqualsExpression

Label selector expression of the equal form label == value.

label

(string, required)

Name of the label to equal match the value.

value

(string)

Exact value that the label should be equal to.

Expression

Expression has multiple variants, exactly one should be set.

Example:

all:
  of:
    - label_exists: foo
    - label_equals:
        label: app
        value: frobnicator

all

(ExpressionList)

The expression is true when all sub expressions are true.

any

(ExpressionList)

The expression is true when any sub expression is true.

label_equals

(EqualsExpression)

The expression is true when label value equals given value.

label_exists

(string)

The expression is true when label with given name exists.

label_matches

(MatchesExpression)

The expression is true when label matches given regular expression.

not

(Expression)

The expression negates the result of sub expression.

ExpressionList

List of MatchExpressions that is used for all or any matching

for example, {any: {of: [expr1, expr2]}}.

of

([]Expression)

List of sub expressions of the match expression.

Extractor

Defines a high-level way to specify how to extract a flow label value given HTTP request metadata, without a need to write Rego code

There are multiple variants of extractor, specify exactly one.

address

(AddressExtractor)

Display an address as a single string - <ip>:<port>.

from

(string)

Use an attribute with no conversion

Attribute path is a dot-separated path to attribute.

Should be either:

one of the fields of Attribute Context, or
a special request.http.bearer pseudo-attribute. For example, request.http.method or request.http.header.user-agent

Note: The same attribute path syntax is shared by other extractor variants, wherever attribute path is needed in their "from" syntax.

Example:

from: request.http.headers.user-agent

json

(JSONExtractor)

Parse JSON, and extract one of the fields.

jwt

(JWTExtractor)

Parse the attribute as JWT and read the payload.

path_templates

(PathTemplateMatcher)

Match HTTP Path to given path templates.

Extrapolator

Extrapolates the input signal by repeating the last valid value during the period in which it is invalid

It does so until maximum_extrapolation_interval is reached, beyond which it emits invalid signal unless input signal becomes valid again.

in_ports

(ExtrapolatorIns)

Input ports for the Extrapolator component.

out_ports

(ExtrapolatorOuts)

Output ports for the Extrapolator component.

parameters

(ExtrapolatorParameters, required)

Parameters for the Extrapolator component.

ExtrapolatorIns

Inputs for the Extrapolator component.

input

Input signal for the Extrapolator component.

ExtrapolatorOuts

Outputs for the Extrapolator component.

output

Extrapolated signal.

ExtrapolatorParameters

Parameters for the Extrapolator component.

max_extrapolation_interval

(string, required)

Maximum time interval to repeat the last valid value of input signal. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

FirstValid

Picks the first valid input signal from the array of input signals and emits it as an output signal

in_ports

(FirstValidIns)

Input ports for the FirstValid component.

out_ports

(FirstValidOuts)

Output ports for the FirstValid component.

FirstValidIns

Inputs for the FirstValid component.

inputs

Array of input signals.

FirstValidOuts

Outputs for the FirstValid component.

output

(RangeDrivenLoadScheduler)

First valid input signal as an output signal.

FlowControl

Flow Control encompasses components that manage the flow of requests or access to features within a service.

adaptive_load_scheduler

(AdaptiveLoadScheduler, DEPRECATED)

Adaptive Load Scheduler component does additive increase of load multiplier during non-overload state. During overload, the load multiplier is throttled based on the provided strategy. Deprecated: v3.0.0. Use AIMDLoadScheduler instead.

aiad_load_scheduler

(AIADLoadScheduler)

AIAD Load Scheduler.

aimd_load_scheduler

(AIMDLoadScheduler)

AIMD Load Scheduler.

concurrency_limiter

(ConcurrencyLimiter)

Concurrency Limiter provides service protection by limiting the number of concurrent requests to a service

concurrency_scheduler

(ConcurrencyScheduler)

Concurrency Scheduler provides service protection by limiting the number of concurrent requests to a service and scheduling requests when the limit is reached

load_ramp

(LoadRamp)

Load Ramp smoothly regulates the flow of requests over specified steps.

load_scheduler

(LoadScheduler)

Load Scheduler provides service protection by creating a prioritized workload queue in front of the service using Weighted Fair Queuing.

quota_scheduler

(QuotaScheduler)

range_driven_load_scheduler

Range Driven Load Scheduler.

rate_limiter

(RateLimiter)

Rate Limiter provides service protection by applying rate limits using the token bucket algorithm.

sampler

(Sampler)

Sampler is a component that regulates the flow of requests to the service by allowing only the specified percentage of requests or sticky sessions.

FlowControlResources

FlowControl Resources

classifiers

([]Classifier)

Classifiers are installed in the data-plane and are used to label the requests based on payload content.

The flow labels created by Classifiers can be matched by Flux Meters to create metrics for control purposes.

flux_meters

(map of FluxMeter)

Flux Meters are installed in the data-plane and form the observability leg of the feedback loop.

Flux Meter created metrics can be consumed as input to the circuit through the PromQL component.

FluxMeter

Flux Meter gathers metrics for the traffic that matches its selector. The histogram created by Flux Meter measures the workload latency by default.

info

FluxMeterExponentialBuckets

ExponentialBuckets creates count number of buckets where the lowest bucket has an upper bound of start and each following bucket's upper bound is factor times the previous bucket's upper bound. The final +inf bucket is not counted.

count

(int32, minimum: 0)

Number of buckets.

factor

(float64)

Factor to be multiplied to the previous bucket's upper bound to calculate the following bucket's upper bound.

start

(float64)

Upper bound of the lowest bucket.

FluxMeterExponentialBucketsRange

ExponentialBucketsRange creates count number of buckets where the lowest bucket is min and the highest bucket is max. The final +inf bucket is not counted.

count

(int32, minimum: 0)

Number of buckets.

max

(float64)

Highest bucket.

min

(float64)

Lowest bucket.

FluxMeterLinearBuckets

LinearBuckets creates count number of buckets, each width wide, where the lowest bucket has an upper bound of start. The final +inf bucket is not counted.

count

(int32, minimum: 0)

Number of buckets.

start

(float64)

Upper bound of the lowest bucket.

width

(float64)

Width of each bucket.

FluxMeterStaticBuckets

StaticBuckets holds the static value of the buckets where latency histogram will be stored.

buckets

([]float64, default: [5,10,25,50,100,250,500,1000,2500,5000,10000])

The buckets in which latency histogram will be stored.

GradientController

Gradient controller is a type of controller which tries to adjust the control variable proportionally to the relative difference between setpoint and actual value of the signal

The gradient describes a corrective factor that should be applied to the control variable to get the signal closer to the setpoint. It's computed as follows:

\text{gradient} = \left(\frac{\text{signal}}{\text{setpoint}}\right)^{\text{slope}}

gradient is then clamped to [min_gradient, max_gradient] range.

The output of gradient controller is computed as follows:

\text{output} = \text{gradient}_{\text{clamped}} \cdot \text{control\_variable} + \text{optimize}.

Note the additional optimize signal, that can be used to "nudge" the controller into desired idle state.

The output can be optionally clamped to desired range using max and min input.

in_ports

(GradientControllerIns)

Input ports of the Gradient Controller.

manual_mode

(bool)

In manual mode, the controller does not adjust the control variable. It emits the same output as the control variable input. This setting can be adjusted at runtime through dynamic configuration without restarting the policy.

manual_mode_config_key

(string)

Configuration key for overriding manual_mode setting through dynamic configuration.

out_ports

(GradientControllerOuts)

Output ports of the Gradient Controller.

parameters

(GradientControllerParameters, required)

Gradient Parameters.

GradientControllerIns

Inputs for the Gradient Controller component.

control_variable

Actual current value of the control variable.

This signal is multiplied by the gradient to produce the output.

max

Maximum value to limit the output signal.

min

Minimum value to limit the output signal.

setpoint

Setpoint to be used for the gradient computation.

signal

Signal to be used for the gradient computation.

GradientControllerOuts

Outputs for the Gradient Controller component.

output

Computed desired value of the control variable.

GradientControllerParameters

Gradient Parameters.

max_gradient

(float64, default: 1.7976931348623157e+308)

Maximum gradient which clamps the computed gradient value to the range, [min_gradient, max_gradient].

min_gradient

(float64, default: -1.7976931348623157e+308)

Minimum gradient which clamps the computed gradient value to the range, [min_gradient, max_gradient].

slope

(float64, required)

Slope controls the aggressiveness and direction of the Gradient Controller.

Slope is used as exponent on the signal to setpoint ratio in computation of the gradient (see the main description for exact equation). This parameter decides how aggressive the controller responds to the deviation of signal from the setpoint. for example:

$\text{slope} = 1$ : when signal is too high, increase control variable,
$\text{slope} = -1$ : when signal is too high, decrease control variable,
$\text{slope} = -0.5$ : when signal is too high, decrease control variable gradually.

The sign of slope depends on correlation between the signal and control variable:

Use $\text{slope} < 0$ if there is a positive correlation between the signal and the control variable (for example, Per-pod CPU usage and total concurrency).
Use $\text{slope} > 0$ if there is a negative correlation between the signal and the control variable (for example, Per-pod CPU usage and number of pods).

note

You need to set negative slope for a positive correlation, as you're describing the action which controller should make when the signal increases.

The magnitude of slope describes how aggressively should the controller react to a deviation of signal. With $|\text{slope}| = 1$ , the controller will aim to bring the signal to the setpoint in one tick (assuming linear correlation with signal and setpoint). Smaller magnitudes of slope will make the controller adjust the control variable gradually.

Setting $|\text{slope}| < 1$ (for example, $\pm0.8$ ) is recommended. If you experience overshooting, consider lowering the magnitude even more. Values of $|\text{slope}| > 1$ aren't recommended.

note

Remember that the gradient and output signal can be (optionally) clamped, so the slope might not fully describe aggressiveness of the controller.

Holder

Holds the last valid signal value for the specified duration then waits for next valid value to hold. If it is holding a value that means it ignores both valid and invalid new signals until the hold_for duration is finished.

hold_for

(string, default: "5s")

Holding the last valid signal value for the hold_for duration. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

in_ports

(HolderIns)

Input ports for the Holder component.

out_ports

(HolderOuts)

Output ports for the Holder component.

HolderIns

Inputs for the Holder component.

input

The input signal.

reset

Resets the holder output to the current input signal when reset signal is valid and non-zero.

HolderOuts

Outputs for the Holder component.

output

(IncreasingGradientParameters)

The output signal.

InPort

Components receive input from other components through InPorts

constant_signal

(ConstantSignal)

Constant value to be used for this InPort instead of a signal.

signal_name

(string)

Name of the incoming Signal on the InPort.

IncreasingGradient

Increasing Gradient defines a controller for scaling out based on Gradient Controller.

in_ports

(IncreasingGradientIns)

Input ports for the Gradient.

parameters

Gradient parameters for the controller. Defaults and constraints:

slope = 1
min_gradient = 1 (cannot be changed)
max_gradient = +Inf (must be greater than 1)

IncreasingGradientIns

Inputs for Gradient.

setpoint

The setpoint to use for scale-out.

signal

(InfraMeterMetricsPipeline)

The signal to use for scale-out.

IncreasingGradientParameters

This allows subset of parameters with constrained values compared to a regular gradient controller. For full documentation of these parameters, refer to the GradientControllerParameters.

max_gradient: (float64, default: 1.7976931348623157e+308)
slope: (float64, default: 1)

InfraMeter

InfraMeter is a resource that sets up OpenTelemetry pipelines. It defines receivers, processors, and a single metrics pipeline which will be exported to the configured Prometheus instance. Environment variables can be used in the configuration using format ${ENV_VAR_NAME}.

info

agent_group

(string, default: "default")

AgentGroup is the agent group to sync this InfraMeter with.

per_agent_group

(bool, default: false)

PerAgentGroup marks the pipeline to be instantiated only once per agent group. This is helpful for receivers that scrape for example, some cluster-wide metrics. When not set, pipeline will be instantiated on every Agent.

pipeline

Pipeline is an OTel metrics pipeline definition, which only uses receivers and processors defined above. Exporter would be added automatically.

If there are no processors defined or only one processor is defined, the pipeline definition can be omitted. In such cases, the pipeline will automatically use all given receivers and the defined processor (if any). However, if there are more than one processor, the pipeline must be defined explicitly.

processors

(map of any )

Processors define processors to be used in custom metrics pipelines. This should be in OTel format.

receivers

(map of any )

Receivers define receivers to be used in custom metrics pipelines. This should be in OTel format.

InfraMeterMetricsPipeline

MetricsPipelineConfig defines a custom metrics pipeline.

processors: ([]string)
receivers: ([]string)

Integrator

Accumulates sum of signal every tick.

evaluation_interval

(string)

The evaluation interval of the Integrator. This determines how often the Integrator is incremented. Defaults to the evaluation interval of the circuit. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

in_ports

(IntegratorIns)

Input ports for the Integrator component.

initial_value

(float64, default: 0)

Initial value of the integrator.

out_ports

(IntegratorOuts)

Output ports for the Integrator component.

IntegratorIns

Inputs for the Integrator component.

input

The input signal.

max

The maximum output.

min

The minimum output.

reset

Resets the integrator output to zero when reset signal is valid and non-zero. Reset also resets the max and min constraints.

IntegratorOuts

Outputs for the Integrator component.

output: (OutPort)

Inverter

Logical NOT.

See And component on how signals are mapped onto Boolean values.

in_ports

(InverterIns)

Input ports for the Inverter component.

out_ports

(InverterOuts)

Output ports for the Inverter component.

InverterIns

Inputs for the Inverter component.

input

Signal to be negated.

InverterOuts

Output ports for the Inverter component.

output

Logical negation of the input signal.

Will always be 0 (false), 1 (true) or invalid (unknown).

JSONExtractor

Parse JSON, and extract one of the fields

Example:

from: request.http.body
pointer: /user/name

from

(string, required)

Attribute path pointing to some strings - for example, request.http.body.

pointer

(string)

JSON pointer represents a parsed JSON pointer which allows to select a specified field from the payload.

Note: Uses JSON pointer syntax, for example, /foo/bar. If the pointer points into an object, it'd be converted to a string.

JWTExtractor

Parse the attribute as JWT and read the payload

Specify a field to be extracted from payload using json_pointer.

Note: The signature is not verified against the secret (assuming there's some other part of the system that handles such verification).

Example:

from: request.http.bearer
json_pointer: /user/email

from

(string, required)

JWT (JSON Web Token) can be extracted from any input attribute, but most likely you'd want to use request.http.bearer.

json_pointer

(string)

JSON pointer allowing to select a specified field from the payload.

Note: Uses JSON pointer syntax, for example, /foo/bar. If the pointer points into an object, it'd be converted to a string.

KubernetesObjectSelector

Describes which pods a control or observability component should apply to.

agent_group

(string, default: "default")

Which agent-group this selector applies to.

api_version

(string, required)

API version of Kubernetes resource

kind

(string, required)

Kubernetes resource type.

name

(string, required)

Kubernetes resource name.

namespace

(string, required)

Kubernetes namespace that the resource belongs to.

LabelMatcher

Allows to define rules whether a map of labels should be considered a match or not

It provides three ways to define requirements:

match labels
match expressions
arbitrary expression

If multiple requirements are set, they're all combined using the logical AND operator. An empty label matcher always matches.

expression

(Expression)

An arbitrary expression to be evaluated on the labels.

match_expressions

([]MatchRequirement)

List of Kubernetes-style label matcher requirements.

Note: The requirements are combined using the logical AND operator. Deprecated: v3.0.0. Use match_list instead.

match_labels

(map of string)

A map of {key,value} pairs representing labels to be matched. A single {key,value} in the match_labels requires that the label key is present and equal to value.

Note: The requirements are combined using the logical AND operator.

match_list

([]MatchRequirement)

List of label matching requirements.

Note: The requirements are combined using the logical AND operator.

LoadRamp

The Load Ramp produces a smooth and continuous traffic load that changes progressively over time, based on the specified steps.

Each step is defined by two parameters:

The target_accept_percentage.
The duration for the signal to change from the previous step's target_accept_percentage to the current step's target_accept_percentage.

The percentage of requests accepted starts at the target_accept_percentage defined in the first step and gradually ramps up or down linearly from the previous step's target_accept_percentage to the next target_accept_percentage, over the duration specified for each step.

in_ports

(LoadRampIns)

out_ports

(LoadRampOuts)

parameters

(LoadRampParameters, required)

pass_through_label_values

([]string)

Specify certain label values to be always accepted by the Sampler regardless of accept percentage.

pass_through_label_values_config_key

(string)

Configuration key for setting pass through label values through dynamic configuration.

LoadRampIns

Inputs for the Load Ramp component.

backward

Whether to progress the Load Ramp towards the previous step.

forward

Whether to progress the Load Ramp towards the next step.

reset

Whether to reset the Load Ramp to the first step.

LoadRampOuts

Outputs for the Load Ramp component.

accept_percentage

The percentage of flows being accepted by the Load Ramp.

at_end

A Boolean signal indicating whether the Load Ramp is at the end of signal generation.

at_start

A Boolean signal indicating whether the Load Ramp is at the start of signal generation.

LoadRampParameters

Parameters for the Load Ramp component.

sampler

(SamplerParameters, required)

Parameters for the Sampler.

steps

([]LoadRampParametersStep, required)

LoadRampParametersStep

duration

(string, required)

Duration for which the step is active. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

target_accept_percentage

(float64, minimum: 0, maximum: 100)

The value of the step.

LoadScheduler

Load Scheduler creates a queue for flows in front of a service to provide active service protection

info

LoadSchedulerIns

Input for the LoadScheduler component.

load_multiplier

Load multiplier is proportion of incoming token rate that needs to be accepted. The signal gets updated once every 10 seconds.

LoadSchedulerOuts

Output for the LoadScheduler component.

observed_load_multiplier

Observed load multiplier is the proportion of incoming token rate that is being accepted. The signal gets updated once every 10 seconds.

LoadSchedulerParameters

Parameters for Load Scheduler component

scheduler

(Scheduler)

Configuration of Weighted Fair Queuing-based workload scheduler.

Contains configuration of per-agent scheduler

selectors

([]Selector, required)

Selectors for the component.

workload_latency_based_tokens

(bool, default: false)

Automatically estimate the size of flows within each workload, based on historical latency. Each workload's tokens will be set to average latency of flows in that workload during the last few seconds (exact duration of this average can change). This setting is useful in concurrency limiting use-case, where the concurrency is calculated as (avg. latency \* in-flight flows) (Little's Law).

The value of tokens estimated takes a lower precedence than the value of tokens specified in the workload definition and tokens explicitly specified in the flow labels.

MatchRequirement

MatchRequirement. A requirement that the specified label should satisfy on a flow. The match requirement consists of the label key, its values and an operator that relates the key and values.

key

(string, required)

Label key that the selector applies to.

operator

(string, one of: In | NotIn | Exists | DoesNotExist, required)

Logical operator which represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.

values

([]string)

An array of string values that relates to the key by an operator. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty.

MatchesExpression

Label selector expression of the form label matches regex.

label

(string, required)

Name of the label to match the regular expression.

regex

(string, required)

Regular expression that should match the label value. It uses Go's regular expression syntax.

Max

Takes a list of input signals and emits the signal with the maximum value

Max: output = max([]inputs).

in_ports

(MaxIns)

Input ports for the Max component.

out_ports

(MaxOuts)

Output ports for the Max component.

MaxIns

Inputs for the Max component.

inputs

Array of input signals.

MaxOuts

Output for the Max component.

output

Signal with maximum value as an output signal.

Min

Takes an array of input signals and emits the signal with the minimum value Min: output = min([]inputs).

in_ports

(MinIns)

Input ports for the Min component.

out_ports

(MinOuts)

Output ports for the Min component.

MinIns

Inputs for the Min component.

inputs

Array of input signals.

MinOuts

Output ports for the Min component.

output

Signal with minimum value as an output signal.

NestedCircuit

Nested circuit defines a sub-circuit as a high-level component. It consists of a list of components and a map of input and output ports.

components

([]Component)

List of components in the nested circuit.

in_ports_map

(map of InPort)

Maps input port names to input ports.

out_ports_map

(map of OutPort)

Maps output port names to output ports.

NestedSignalEgress

Nested signal egress is a special type of component that allows to extract a signal from a nested circuit.

in_ports

(NestedSignalEgressIns)

Input ports for the NestedSignalEgress component.

port_name

(string)

Name of the port.

NestedSignalEgressIns

Inputs for the NestedSignalEgress component.

signal

(NestedSignalIngressOuts)

Egress signal.

NestedSignalIngress

Nested signal ingress is a special type of component that allows to inject a signal into a nested circuit.

out_ports

Output ports for the NestedSignalIngress component.

port_name

(string)

Name of the port.

NestedSignalIngressOuts

Outputs for the NestedSignalIngress component.

signal

Ingress signal.

Or

Logical OR.

See And component on how signals are mapped onto Boolean values.

in_ports

(OrIns)

Input ports for the Or component.

out_ports

(OrOuts)

Output ports for the Or component.

OrIns

Inputs for the Or component.

inputs

Array of input signals.

OrOuts

Output ports for the Or component.

output

Result of logical OR of all the input signals.

Will always be 0 (false), 1 (true) or invalid (unknown).

OutPort

Components produce output for other components through OutPorts

signal_name

(string)

Name of the outgoing Signal on the OutPort.

PIDController

PID Controller is a popular control mechanism for closed-loop feedback control. It takes a signal and a setpoint as inputs and uses the PID algorithm to compute proportional (proportional to the magnitude of error), integral (proportional to accumulation of error), and derivative (proportional to how fast the signal is changing) terms which are summed up to get a desired output.

error = setpoint - signal \\ integral_i = integral_{i-1} + k_i \cdot error \\ output_i = k_p \cdot error + k_d \cdot (signal_i - signal_{i-1}) + integral_i

in_ports: (PIDControllerIns)
out_ports: (PIDControllerOuts)
parameters: (PIDControllerParameters, required)

PIDControllerIns

max

Maximum allowed output

min

Minimum allowed output

setpoint

The desired setpoint for the signal

signal

The signal to be controlled

PIDControllerOuts

output

Output of the PID controller

PIDControllerParameters

evaluation_interval

(string)

The evaluation interval of the PID controller. This determines how often the PID output is computed. Defaults to the evaluation interval of the circuit. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

kd

(float64, minimum: 0, default: 0)

The derivative gain of the PID controller.

ki

(float64, minimum: 0, default: 0)

The integral gain of the PID controller.

kp

(float64, minimum: 0, default: 0)

The proportional gain of the PID controller.

reset_after_invalid_samples

(int32, minimum: 1, default: 4)

The integrator resets after the specified number of ticks if the signal or setpoint are continuously invalid. Defaults to 4 invalid samples.

PathTemplateMatcher

Matches HTTP Path to given path templates

HTTP path will be matched against given path templates. If a match occurs, the value associated with the path template will be treated as a result. In case of multiple path templates matching, the most specific one will be chosen.

template_values

(map of string)

Template value keys are OpenAPI-inspired path templates.

Static path segment /foo matches a path segment exactly
/{param} matches arbitrary path segment. (The parameter name is ignored and can be omitted ({}))
The parameter must cover whole segment.
Additionally, path template can end with /* wildcard to match arbitrary number of trailing segments (0 or more).
Multiple consecutive / are ignored, as well as trailing /.
Parametrized path segments must come after static segments.
*, if present, must come last.
Most specific template "wins" (/foo over /{} and /{} over /*).

Example:

/register: register
"/user/{userId}": user
/static/*: other

PeriodicDecrease

PeriodicDecrease defines a controller for scaling in based on a periodic timer.

period

(string, required)

The period of the timer. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

scale_in_percentage

(float64, minimum: 0, maximum: 100, required)

The percentage of scale to reduce.

PodScaler

Component for scaling pods based on a signal.

dry_run

(bool)

Dry run mode ensures that no scaling is invoked by this pod scaler. This is useful for observing the behavior of pod scaler without disrupting any real deployment. This parameter sets the default value of dry run setting which can be overridden at runtime using dynamic configuration.

dry_run_config_key

(string)

Configuration key for overriding dry run setting through dynamic configuration.

in_ports

(PodScalerIns)

Input ports for the PodScaler component.

kubernetes_object_selector

(KubernetesObjectSelector, required)

The Kubernetes object to which this pod scaler applies.

out_ports

(PodScalerOuts)

Output ports for the PodScaler component.

PodScalerIns

Inputs for the PodScaler component.

replicas

The number of replicas to configure for the Kubernetes resource

PodScalerOuts

Outputs for the PodScaler component.

actual_replicas

The number of replicas that are currently running.

configured_replicas

The number of replicas that are desired.

Policy

Policy expresses observability-driven control logic.

info

PolynomialRangeFunction

Curve Types by Degree:

Degree 1: Linear
Degree 2: Quadratic
Degree 3: Cubic
and so on.

in_ports: (PolynomialRangeFunctionIns)
out_ports: (PolynomialRangeFunctionOuts)
parameters: (PolynomialRangeFunctionParameters, required)

PolynomialRangeFunctionIns

input

The input signal.

PolynomialRangeFunctionOuts

output

(PolynomialRangeFunctionParametersClampToCustomValues)

The output signal.

PolynomialRangeFunctionParameters

clamp_to_custom_values

Clamp to custom values

clamp_to_datapoint

(bool)

Clamp to the nearest data-point

continue_curve

(bool)

Continue polynomial curve

degree

(float64)

Degree of the polynomial

end

(PolynomialRangeFunctionParametersDatapoint)

Ending data-point for the range function

start

(PolynomialRangeFunctionParametersDatapoint)

Starting data-point for the range function

PolynomialRangeFunctionParametersClampToCustomValues

post_end: (float64)
pre_start: (float64)

PolynomialRangeFunctionParametersDatapoint

input: (float64)
output: (float64)

PromQL

Component that runs a Prometheus query periodically and returns the result as an output signal

evaluation_interval

(string, default: "10s")

Describes the interval between successive evaluations of the Prometheus query. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

out_ports

(PromQLOuts)

Output ports for the PromQL component.

query_string

(string)

Describes the PromQL query to be run.

note

The query must return a single value either as a scalar or as a vector with a single element.

Usage with Flux Meter

Flux Meter metrics can be queried using PromQL. Flux Meter defines histogram type of metrics in Prometheus. Therefore, one can refer to flux_meter_sum, flux_meter_count and flux_meter_bucket. The particular Flux Meter can be identified with the flux_meter_name label. There are additional labels available on a Flux Meter such as valid, flow_status, http_status_code and decision_type.

Usage with OpenTelemetry Metrics

Aperture supports OpenTelemetry metrics. See reference for more details.

PromQLOuts

Output for the PromQL component.

output

(RangeDrivenLoadSchedulerIns)

The result of the Prometheus query as an output signal.

PulseGenerator

Generates 0 and 1 in turns.

false_for

(string, default: "5s")

Emitting 0 for the false_for duration. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

out_ports

(PulseGeneratorOuts)

Output ports for the PulseGenerator component.

true_for

(string, default: "5s")

Emitting 1 for the true_for duration. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

PulseGeneratorOuts

Outputs for the PulseGenerator component.

output: (OutPort)

Query

Query components that are query databases such as Prometheus.

promql

(PromQL)

Periodically runs a Prometheus query in the background and emits the result.

QuotaScheduler

Schedules the traffic based on token-bucket based quotas.

in_ports

(RateLimiterIns, required)

Input ports for the Quota Scheduler component

out_ports

(RateLimiterOuts)

Output ports for the Quota Scheduler component.

rate_limiter

(RateLimiterParameters, required)

Parameter to configure rate limiting quotas.

scheduler

(Scheduler)

Scheduler is used to schedule the requests when the quota is exhausted.

selectors

([]Selector, required)

Flow selection criteria.

RangeDrivenLoadScheduler

Range Load Scheduler uses the polynomial range function to throttle the token rate based on the range of the signal.

dry_run

(bool)

dry_run_config_key

(string)

Configuration key for setting dry run mode through dynamic configuration.

in_ports

Input ports for the Range Load Scheduler.

out_ports

(RangeDrivenLoadSchedulerOuts)

Output ports for the Range Load Scheduler.

parameters

(RangeDrivenLoadSchedulerParameters, required)

Parameters for the Range Load Scheduler.

RangeDrivenLoadSchedulerDatapoint

load_multiplier: (float64, minimum: 0, maximum: 1)
signal_value: (float64)

RangeDrivenLoadSchedulerIns

Input ports for the Range Load Scheduler.

overload_confirmation

The overload_confirmation port provides additional criteria to determine overload state which results in Flow throttling at the service.

signal

(InPort, required)

The input signal to the controller.

RangeDrivenLoadSchedulerOuts

Output ports for the Range Load Scheduler.

desired_load_multiplier

Desired Load multiplier is the ratio of desired token rate to the incoming token rate.

is_overload

A Boolean signal that indicates whether the service is in overload state.

observed_load_multiplier

Observed Load multiplier is the ratio of accepted token rate to the incoming token rate.

RangeDrivenLoadSchedulerParameters

alerter

(AlerterParameters, required)

Configuration parameters for the embedded Alerter.

degree

(float64, required)

Degree determines shape of the throttling curve. degree=1: linear degree=2: quadratic degree=3: cubic

high_throttle_threshold

(RangeDrivenLoadSchedulerDatapoint, required)

Ending data-point of the throttling range

load_scheduler

(LoadSchedulerParameters, required)

Parameters for the Load Scheduler.

low_throttle_threshold

(RangeDrivenLoadSchedulerDatapoint, required)

Starting data-point of the throttling range

RateLimiter

Limits the traffic on a control point to specified rate

info

RateLimiterIns

Inputs for the Rate Limiter or Quota Scheduler component

bucket_capacity

(InPort, required)

Capacity of the bucket to allow for bursty traffic.

fill_amount

(InPort, required)

Number of tokens to fill within an interval.

pass_through

PassThrough port determines whether to accept all requests instantaneously

RateLimiterOuts

Outputs for the Rate Limiter or Quota Scheduler component.

accept_percentage

(RateLimiterParametersLazySync)

The percentage of flows being accepted.

RateLimiterParameters

continuous_fill

(bool, default: true)

Continuous fill determines whether the token bucket should be filled continuously or only on discrete intervals.

delay_initial_fill

(bool, default: false)

Delays the initial filling of the token bucket. If set to false, the token bucket will start filling immediately after the first request is received. This can potentially lead to more requests being accepted than the specified rate limit during the first interval. When set to true, the token bucket will be given a chance to empty out before the filling starts. The delay is equal to the time it takes to fill the bucket.

interval

(string, required)

Interval defines the time interval in which the token bucket will fill tokens specified by fill_amount signal. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

label_key

(string, DEPRECATED)

Specifies which label the rate limiter should be keyed by.

Rate limiting is done independently for each value of the label with given key. For example, to give each user a separate limit, assuming you have a user flow label set up, set label_key: "user". If no label key is specified, then all requests matching the selectors will be rate limited based on the global bucket. Deprecated: v3.0.0. Use limit_by_label_key instead.

lazy_sync

Configuration of lazy-syncing behavior of rate limiter

limit_by_label_key

(string)

Specifies which label the rate limiter should be keyed by.

Rate limiting is done independently for each value of the label with given key. For example, to give each user a separate limit, assuming you have a user flow label set up, set limit_by_label_key: "user". If no label key is specified, then all requests matching the selectors will be rate limited based on the global bucket.

max_idle_time

(string, default: "7200s")

Max idle time before token bucket state for a label is removed. If set to 0, the state is never removed. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

RateLimiterParametersLazySync

enabled

(bool, default: false)

Enables lazy sync

num_sync

(int64, minimum: 0, default: 4)

Number of times to lazy sync within the interval.

RateLimiterRequestParameters

denied_response_status_code

This field allows you to override the default HTTP status code (429 Too Many Requests) that is returned when a request is denied.

tokens_label_key

(string)

Rego

Rego define a set of labels that are extracted after evaluating a Rego module.

info

You can use the live-preview feature to first preview the input to the classifier before writing the labeling logic.

Example of Rego module which also disables telemetry visibility of label:

rego:
  labels:
    user:
      telemetry: false
  module: |
    package user_from_cookie
    cookies := split(input.attributes.request.http.headers.cookie, "; ")
    user := user {
        cookie := cookies[_]
        startswith(cookie, "session=")
        session := substring(cookie, count("session="), -1)
        parts := split(session, ".")
        object := json.unmarshal(base64url.decode(parts[0]))
        user := object.user
    }

labels

(map of RegoLabelProperties, required)

A map of {key, value} pairs mapping from flow label keys to queries that define how to extract and propagate flow labels with that key. The name of the label maps to a variable in the Rego module. It maps to data.<package>.<label> variable.

module

(string, required)

Source code of the Rego module.

note

Must include a "package" declaration.

RegoLabelProperties

telemetry

(bool, default: true)

Decides if the created flow label should be available as an attribute in OLAP telemetry and propagated in baggage

note

The flow label is always accessible in Aperture Policies regardless of this setting.

caution

When using FluxNinja extension, telemetry enabled labels are sent to Aperture Cloud for observability. Telemetry should be disabled for sensitive labels.

Resources

Resources that need to be setup for the policy to function

info

Rule

Rule describes a single classification Rule

Example of a JSON extractor:

extractor:
  json:
    from: request.http.body
    pointer: /user/name

extractor

(Extractor)

High-level declarative extractor.

telemetry

(bool, default: true)

Decides if the created flow label should be available as an attribute in OLAP telemetry and propagated in baggage

note

The flow label is always accessible in Aperture Policies regardless of this setting.

caution

When using FluxNinja extension, telemetry enabled labels are sent to Aperture Cloud for observability. Telemetry should be disabled for sensitive labels.

SMA

Simple Moving Average (SMA) is a type of moving average that computes the average of a fixed number of signal readings.

in_ports

(SMAIns)

Input ports for the SMA component.

out_ports

(SMAOuts)

Output ports for the SMA component.

parameters

(SMAParameters, required)

Parameters for the SMA component.

SMAIns

input

Signal to be used for the moving average computation.

SMAOuts

output

Computed moving average.

SMAParameters

sma_window

(string, required)

Window of time over which the moving average is computed. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

valid_during_warmup

(bool, default: false)

Whether the output is valid during the warm-up stage.

Sampler

Sampler is a component that regulates the load at a Control Point by allowing only a specified percentage of flows at random or by sticky sessions.

info

SamplerIns

accept_percentage

The percentage of requests to accept.

SamplerParameters

denied_response_status_code

(SchedulerWorkloadParameters)

This field allows you to override the default HTTP status code (403 Forbidden) that is returned when a request is denied.

ramp_mode

(bool, default: false)

Ramp component can accept flows with ramp_mode flag set.

selectors

([]Selector, required)

Selectors for the component.

session_label_key

(string)

The flow label key for identifying sessions.

When label key is specified, Sampler acts as a sticky filter. The series of flows with the same value of label key get the same decision provided that the accept_percentage is same or higher.
When label key is not specified, Sampler acts as a stateless filter. Percentage of flows are selected randomly for rejection.

ScaleInController

alerter

(AlerterParameters, required)

Configuration for embedded Alerter.

controller

(ScaleInControllerController, required)

Controller

ScaleInControllerController

gradient: (DecreasingGradient)
periodic: (PeriodicDecrease)

ScaleOutController

alerter

(AlerterParameters, required)

Configuration for embedded Alerter.

controller

(ScaleOutControllerController, required)

Controller

ScaleOutControllerController

gradient: (IncreasingGradient)

Scheduler

Weighted Fair Queuing-based workload scheduler

note

Each Agent instantiates an independent copy of the scheduler, but output signals for accepted and incoming token rate are aggregated across all agents.

decision_deadline_margin

(string, default: "0.01s")

Decision deadline margin is the amount of time that the scheduler will subtract from the request deadline to determine the deadline for the decision. This is to ensure that the scheduler has enough time to make a decision before the request deadline happens, accounting for processing delays. The request deadline is based on the gRPC deadline or the grpc-timeout HTTP header.

Fail-open logic is use for flow control APIs, so if the gRPC deadline reaches, the flow will end up being unconditionally allowed while it is still waiting on the scheduler. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

default_workload_parameters

Parameters to be used if none of workloads specified in workloads match.

denied_response_status_code

(SchedulerWorkloadParameters)

This field allows you to override the default HTTP status code (503 Service Unavailable) that is returned when a request is denied.

fairness_label_key

(string)

Key for a flow label that is used to enforce fairness among requests in a workload. If not specified, requests within a workload of the same priority are admitted in a FIFO manner.

priority_label_key

(string)

Key for a flow label that can be used to override the default priority for this flow. The value associated with this key must be a valid number. Higher numbers means higher priority. If this parameter is not provided, the priority for the flow will be determined by the matched workload's priority.

tokens_label_key

(string)

Key for a flow label that can be used to override the default number of tokens for this request. The value associated with this key must be a valid number. If this parameter is not provided, the number of tokens for the flow will be determined by the matched workload's token count.

workload_label_key

(string)

Key for a flow label that can be used to provide workloads for this request. If this parameter is not provided, the workloads for the flow will be determined by the matched workload's name in the policy.

workloads

([]SchedulerWorkload)

List of workloads to be used in scheduler.

Categorizing flows into workloads allows for load throttling to be "intelligent" instead of queueing flows in an arbitrary order. There are two aspects of this "intelligence":

Scheduler can more precisely calculate concurrency if it understands that flows belonging to different classes have different weights (for example, insert queries compared to select queries).
Setting different priorities to different workloads lets the scheduler avoid dropping important traffic during overload.

Each workload in this list specifies also a matcher that is used to determine which flow will be categorized into which workload. In case of multiple matching workloads, the first matching one will be used. If none of workloads match, default_workload will be used.

info

SchedulerWorkload

Workload defines a class of flows that preferably have similar properties such as response latency and desired priority.

label_matcher

(LabelMatcher, required)

Label Matcher to select a Workload based on flow labels.

name

(string)

Name of the workload.

parameters

Parameters associated with flows matching the label matcher.

SchedulerWorkloadParameters

Parameters such as priority and tokens that are applicable to flows within a workload.

priority

(float64, minimum: 0, default: 1)

Describes priority level of the flows within the workload. Priority level is unbounded and can be any positive number. Higher numbers means higher priority level. The following formula is used to determine the position of a flow in the queue based on virtual finish time:

inverted\_priority = {\frac {1} {priority}}

virtual\_finish\_time = virtual\_time + \left(tokens \cdot inverted\_priority\right)

queue_timeout

(string)

Timeout for the flow in the workload. If timeout is provided on the Check call as well, the minimum of the two is picked. If this override is not provided, the timeout provided in the check call is used. 0 timeout value implies that the request will not wait in the queue and will be accepted or dropped immediately. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.

tokens

(float64, minimum: 0, default: 1)

Tokens determines the cost of admitting a single flow in the workload, which is typically defined as milliseconds of flow latency (time to response or duration of a feature) or simply equal to 1 if the resource being accessed is constrained by the number of flows (3rd party rate limiters). This override is applicable only if tokens for the flow aren't specified in the flow labels.

Selector

Selects flows based on control point, flow labels, agent group and the service that the flow control component will operate on.

info

SignalGenerator

The Signal Generator component generates a smooth and continuous signal by following a sequence of specified steps. Each step has two parameters:

target_output: The desired output value at the end of the step.
duration: The time it takes for the signal to change linearly from the previous step's target_output to the current step's target_output.

The output signal starts at the target_output of the first step and changes linearly between steps based on their duration. The Signal Generator can be controlled to move forwards, backwards, or reset to the beginning based on input signals.

in_ports

(SignalGeneratorIns)

out_ports

(SignalGeneratorOuts)

parameters

(SignalGeneratorParameters, required)

Parameters for the Signal Generator component.

SignalGeneratorIns

Inputs for the Signal Generator component.

backward

Whether to progress the Signal Generator towards the previous step.

forward

Whether to progress the Signal Generator towards the next step.

reset

Whether to reset the Signal Generator to the first step.

SignalGeneratorOuts

Outputs for the Signal Generator component.

at_end

A Boolean signal indicating whether the Signal Generator is at the end of signal generation.

at_start

A Boolean signal indicating whether the Signal Generator is at the start of signal generation.

output

The generated signal.

SignalGeneratorParameters

Parameters for the Signal Generator component.

steps: ([]SignalGeneratorParametersStep, required)

SignalGeneratorParametersStep

duration

(string, required)

target_output

(ConstantSignal)

The value of the step.

StatusCode

HTTP response codes. For more details: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

Empty: Empty - This code not part of the HTTP status code specification, but it is needed for enum type.

Property	Type	Default	Constraints	Description
`StatusCode`	string	Default: `"Empty"`		- Empty: Empty - This code not part of the HTTP status code specification, but it is needed for `enum` type.

Switcher

Type of Combinator that switches between on_signal and off_signal signals based on switch input

on_signal will be returned if switch input is valid and not equal to 0.0 , otherwise off_signal will be returned.

in_ports

(SwitcherIns)

Input ports for the Switcher component.

out_ports

(SwitcherOuts)

Output ports for the Switcher component.

SwitcherIns

Inputs for the Switcher component.

off_signal

Output signal when switch is invalid or 0.0.

on_signal

Output signal when switch is valid and not 0.0.

switch

Decides whether to return on_signal or off_signal.

SwitcherOuts

Outputs for the Switcher component.

output

Selected signal (on_signal or off_signal).

TelemetryCollector

TelemetryCollector defines the telemetry configuration to be synced with the agents. Deprecated: v3.0.0. Use InfraMeter instead. It consists of two parts:

Agent Group: Agent group to sync telemetry configuration with
Infra Meters: OTel compatible metrics pipelines

agent_group

(string, default: "default")

infra_meters

(map of InfraMeter)

Example:

 telemetry_collectors:
   - agent_group: default
     infra_meters:
          rabbitmq:
            processors:
              batch:
                send_batch_size: 10
                timeout: 10s
            receivers:
              rabbitmq:
                collection_interval: 10s
                endpoint: http://<rabbitmq-svc-fqdn>:15672
                password: secretpassword
                username: admin
            per_agent_group: true

caution

Validate the OTel configuration before applying it to the production cluster. Incorrect configuration will get rejected at the agents and might cause shutdown of the agent(s).

UnaryOperator

Takes an input signal and emits the output after applying the specified unary operator

\text{output} = \unary_operator{\text{input}}

in_ports

(UnaryOperatorIns)

Input ports for the UnaryOperator component.

operator

Unary Operator to apply.

The unary operator can be one of the following:

abs: Absolute value with the sign removed.
acos: arccosine, in radians.
acosh: Inverse hyperbolic cosine.
asin: arcsine, in radians.
asinh: Inverse hyperbolic sine.
atan: arctangent, in radians.
atanh: Inverse hyperbolic tangent.
cbrt: Cube root.
ceil: Least integer value greater than or equal to input signal.
cos: cosine, in radians.
cosh: Hyperbolic cosine.
erf: Error function.
erfc: Complementary error function.
erfcinv: Inverse complementary error function.
erfinv: Inverse error function.
exp: The base-e exponential of input signal.
exp2: The base-2 exponential of input signal.
expm1: The base-e exponential of input signal minus 1.
floor: Greatest integer value less than or equal to input signal.
gamma: Gamma function.
j0: Bessel function of the first kind of order 0.
j1: Bessel function of the first kind of order 1.
lgamma: Natural logarithm of the absolute value of the gamma function.
log: Natural logarithm of input signal.
log10: Base-10 logarithm of input signal.
log1p: Natural logarithm of input signal plus 1.
log2: Base-2 logarithm of input signal.
round: Round to nearest integer.
roundtoeven: Round to nearest integer, with ties going to the nearest even integer.
sin: sine, in radians.
sinh: Hyperbolic sine.
sqrt: Square root.
tan: tangent, in radians.
tanh: Hyperbolic tangent.
trunc: Truncate to integer.
y0: Bessel function of the second kind of order 0.
y1: Bessel function of the second kind of order 1.

out_ports

(UnaryOperatorOuts)

Output ports for the UnaryOperator component.

UnaryOperatorIns

Inputs for the UnaryOperator component.

input

Input signal.

UnaryOperatorOuts

Outputs for the UnaryOperator component.

output

Output signal.

Variable

Component that emits a constant signal which can be changed at runtime through dynamic configuration.

config_key

(string)

Configuration key for overriding value setting through dynamic configuration.

constant_output

(ConstantSignal, required)

The constant signal emitted by this component. The value of the constant signal can be overridden at runtime through dynamic configuration.

out_ports

(VariableOuts)

Output ports for the Variable component.

VariableOuts

Outputs for the Variable component.

output