Rate Control Policies

A rate control policy caps how much data Kloudfuse ingests for one telemetry stream. Each stream — Metrics, Logs, Traces, Events, and RUM — has at most one policy. A policy sets an ingestion cap for the whole stream, a rate for the default class, and optionally custom classes that give matching subsets of traffic their own rate.

How rate control works

Each policy has three parts:

Ingestion cap

The Rate is the total budget for the stream, in data points per second, that the default class and custom classes share. The Burst is the total headroom for short spikes; each class gets a part of it in proportion to its share of the Rate.

Default class

The rate for all traffic that does not match a custom class.

Custom classes

Named rate buckets for subsets of traffic. Each class has its own rate and one or more label matchers. Data that matches all of a class’s matchers is counted against that class instead of the default class.

Each data point counts against one class: the first custom class whose matchers all match, or the default class. When traffic in a class exceeds its rate, the ingester drops the excess. Drop is the only supported action. For the full data flow and how burst is divided, see Rate Control Architecture.

Rates are in the stream’s own units:

Stream Unit

Metrics

samples/sec

Logs

lines/sec

Traces

spans/sec

Events

events/sec

RUM

events/sec

Keep these behaviors in mind when you size a policy:

  • The default class and custom classes share the ingestion cap. The sum of the default rate and all custom class rates cannot exceed the stream’s Rate; a policy that exceeds it is rejected. Classes do not borrow unused capacity from each other. The policy editor shows how much of the cap the default class holds and how much is left for custom classes.

  • Each ingester enforces its own share. A class’s rate is divided evenly across the ingester pods, and each pod enforces its share independently. When load is uneven across ingesters, a class can be throttled before its total traffic reaches the configured rate.

  • Small classes get very little burst. Each ingester’s burst for a class is proportional to the class’s whole-percent share of the stream’s rate. A class with less than 1% of the stream’s rate gets a burst of 1, so it can drop data even when its average traffic is well under its rate.

  • A class with a rate of 0 drops everything it matches. Use this deliberately to filter traffic out at ingestion.

  • A class without label matchers routes no traffic. The UI marks these classes as unrouted.

  • Kloudfuse’s own telemetry is never rate limited.

To see how a policy behaves against real traffic, use the Rate Control dashboard.

View rate control policies

  1. In the top navigation, hover over Admin and select Rate Control under Data Management.

    The Rate Control page lists one row per stream, with its Ingestion cap, Burst, the number of custom Classes, and sparklines of traffic for the Last 1h, Last 24h, and Last 7d. A count of unrouted classes appears next to the class count when some classes have no label matchers. A stream without a policy shows Not configured.

  2. Click the arrow at the start of a row to expand it.

    The expanded row lists each class with its Rate, its Matchers, and the data Ingested, Dropped, and Allowed (the share of data that was not dropped). Select 1h, 24h, or 7d to change the time range for these figures.

Configure a rate control policy

  1. On the Rate Control page, click the … menu at the end of the stream’s row and select Edit. Use the same menu whether or not the stream already has a policy.

    The policy editor opens. For a stream that is Not configured, the editor starts with an ingestion Rate of 10000, a Burst of 10000, and a default class Rate of 1000, in the stream’s units; nothing is applied until you save. Use the Metrics, Logs, Traces, Events, and RUM tabs at the top of the editor to switch between streams.

  2. Under Ingestion cap:

    1. In Rate, enter the sustained ingestion ceiling for the stream, in the stream’s units per second.

    2. In Burst, enter the maximum number of data points the stream can accept in a single burst. See Choose a burst size.

  3. Under Default class, in Rate, enter the rate for traffic that does not match any custom class. When exceeded is always Drop.

  4. Optional: add custom classes. For each class:

    1. Under Custom classes, click Add class.

    2. Enter a Class name, for example team-payments.

    3. In Rate, enter the class’s rate. Enter 0 to drop all traffic the class matches.

    4. Under Label matchers, click + Add matcher, then enter a label key, for example kube_namespace, and a regex value, for example payments-.*. Values are matched as regular expressions (=~) against the whole label value: payments matches only payments, not payments-api. For metrics, traces, events, and RUM, matchers see the labels after relabel rules have run.

    5. To narrow the class further, click + Add matcher again. All matchers must match for traffic to enter the class.

      To remove a matcher, click × next to it. To remove a class, click × next to its name.

  5. Check the messages under Custom classes:

    • The blue message shows how much of the ingestion cap the default class holds and how much is left for custom classes. If the custom classes need more, lower the default rate or raise the ingestion cap.

    • The orange message lists classes without label matchers. These classes route no traffic until you add a matcher.

  6. Click Save policy.

Choose a burst size

The burst lets an ingester absorb short spikes without dropping data. To allow bursts while keeping the average rate, size the burst relative to the rate:

  • burst = rate lets through up to 1 second’s worth of traffic at once.

  • burst = rate × N lets through up to N seconds' worth of traffic at once.

The burst is divided between ingesters and classes. A class with less than 1% of the Rate gets almost no burst; see How burst works.

Classes created from ingestion API keys

When you create an ingestion API key with Enable rate control selected, Kloudfuse creates a rate control class for that key in each stream you select, with a rate of 0 and a matcher on the key’s api_key label.

A class with a rate of 0 drops all traffic it matches. Until you set a rate for these classes, all data sent with that API key to the selected streams is dropped. Edit the policy for each stream and set the class’s Rate right after you create the key.

Delete a rate control policy

Deleting a policy removes rate control from that stream: the stream is no longer capped, and all of its classes are removed.

  1. On the Rate Control page, click the … menu at the end of the stream’s row and select Delete. Delete appears only for streams that have a policy.

  2. Confirm the deletion.

Next steps