Rate

Stop any single log pattern from dominating its container's volume, on the forwarder, before that volume is billed downstream. Errors and warnings keep flowing, and patterns on a protection list are never touched.

The rate regulator watches each container's recent volume and trims back any one pattern that crosses a fixed share of it. That pattern is the same symbolMessage value a Reporter attributes cost to, so a top spender maps straight to what gets regulated. Nothing is sampled until a pattern actually dominates.

The cap

A pattern is left alone until it crosses maxSharePerFieldSet (default 20%) of its container's recent volume. At or below the cap every event is kept. Above it, the pattern is trimmed back toward the cap by dropping a fraction of its events.

Share is measured per container over a rolling window (resetIntervalMs, default 4 minutes): (pattern bytes + event) / (container bytes + event). The window is recent rather than all-time, so a pattern that spikes during a deploy and then goes quiet stops being trimmed on its own.

Severity floors

The cap never silences high-severity logs. severityFloors sets a minimum retention per level that beats the cap: even a pattern over its cap keeps at least Error 50%, Warn 30%, Info 10%. The floor reads the severity the level enrichment produced, so it applies whatever field the original log used.

Warmup

A container is left unregulated for warmupMs (default 5 minutes) after this regulator instance first sees its events. Lower for fast-starting apps that should be capped sooner after a restart, raise for slow-ramping JVMs or workloads with long init phases.

The warmup exists because the regulator's per-pattern sample counts start empty. Without a few minutes of accumulation, a low-volume pattern can look dominant purely because of ordering. Five minutes gives enough samples for typical Kubernetes traffic to tell a noisy pattern from a quiet one.

"First sees" is per regulator instance, not per container birth. A container that has been running for hours but whose events have only just started flowing through this regulator, after a regulator restart or a forwarder reconnect, restarts the warmup window. On a daemonset rolling restart the cap is therefore disabled for warmupMs per node as it cycles.

The first baselineCount events (default 5) of every pattern are also kept each window, so even a heavily-trimmed pattern leaves a sample to inspect.

Protection list

An optional mute file overrides the regulator for patterns an operator has declared. A listed, active pattern is decided by its entry, so the human declaration wins and the regulator is skipped for it; every other pattern is handled by the cap. The two run together rather than as separate modes.

File format, CSV with a header row, keyed by the joined fieldNames:

fieldSet,value
<fieldSetKey>,<sampleRate>:<untilEpochSec>[:<reason>]

• sampleRate retains that fraction: 1.0 is never sampled, 0.0 is a full mute.
• untilEpochSec expires the entry, which then self-heals to a no-op.
• reason is free text for audit.

The severity floor still applies, so a 0.0 mute never silences ERROR or FATAL. The file is typically committed to a repo and pulled via gitops, so each change carries a diff, a review, and a merge. The engine hot-reloads on in-place file writes (the gitops pattern); Kubernetes ConfigMap mounts don't reload because the CM swap is a symlink rename, not an in-place write.

Per-container caps

An optional cap file sets a byte cap for a specific container in priority over the fleet-wide absoluteCap. Listed containers get the file's cap; unlisted containers fall back to absoluteCap (or to no cap, when absoluteCap is 0).

File format, CSV with a header row, keyed by the containerField value (k8s container name by default):

container,cap
<container>,<bytes>[:<untilEpochSec>][:<reason>]

• bytes is the per-pattern per-window cap for the container. 0 exempts the container from the absolute cap.
• untilEpochSec expires the entry, which then self-heals to a no-op.
• reason is free text for audit. Must not contain commas (would break CSV parsing).

The cap value changes; the share guard and severity floor still apply. Intended use is via the log10x_configure_regulator MCP tool, which derives per-container caps from a monthly dollar budget and opens a PR against the file.

Same hot-reload contract as the mute file above: in-place writes only; Kubernetes ConfigMap mounts don't reload.

Containers

Share is scoped per container, named by containerField (default the k8s container name). That name is stable across replicas, so scaling from one pod to ten does not bypass the cap, and a sidecar never spends the application container's share. Use container, never pod.

Outside Kubernetes, or when no container field is present, the regulator falls back to a single node-wide bucket and caps each pattern across the node.

Savings

Drops are measured, not estimated. The receive-stage aggregators tally every event by pattern and container both before and after regulation, so the saving for a pattern is the volume seen minus the volume emitted. A dropped event still counts as seen, so the figure reflects exactly what the regulator removed.

Wiring

rateReceiver:
  fieldNames:
    - symbolMessage          # the pattern identity
  containerField: container  # scopes the cap denominator
  absoluteCap: 10485760      # 10 MB per pattern per container per window (optional; 0 = no fleet-wide cap)
  minSharePercent: 0.05      # share guard (sanity)
  severityFloors:
    - INFO=0.1
    - WARN=0.3
    - ERROR=0.5
  warmupMs: 300000           # 5m per-instance grace; raise for slow-ramping apps
  baselineCount: 5
  capLookup:
    # file: $=path("data/caps") + "/caps.csv"   # optional per-container overrides
    retain: $=parseDuration("10m")

Tune these values in this config block, not via container environment variables. Any rateReceiver: key set here resolves to a launch argument at engine init and shadows a same-named env var, so env-only overrides are silently ignored. Edit the config (via a gitops PR) to change a value at runtime.

Config Files

To configure the rate receiver module, Edit these files.

Below is the default configuration from: rate/config.yaml.

Edit Online Edit Locally

Edit config.yaml Locally

Download and save to:

• Linux / Docker / macOS
• Custom directory
  $TENX_CONFIG/run/receive/rate/config.yaml
• Within cloned repo
  ./pipelines/run/receive/rate/config.yaml

Download

# 🔟❎ 'run' rate regulator configuration

# The rate regulator prevents any single log pattern from dominating a container's
# volume. For each event it computes the pattern's share of its container's recent
# bytes and trims the pattern back once it crosses a fixed cap. Severity floors keep
# errors/warnings flowing; an optional mute file overrides the regulator for
# explicitly declared patterns.
# To learn more see https://doc.log10x.com/run/receive/rate/

# Set the 10x pipeline to 'run'
tenx: run

# =============================== Dependencies ================================

include: run/modules/receive/rate

# ============================== Rate Options =================================

rateReceiver:

  # 'fieldNames' identifies the log PATTERN (the numerator bucket). Usually the
  #  symbolMessage field from message enrichment. The container is configured
  #  separately via 'containerField' below -- it is the denominator and is keyed
  #  on its own, so a pattern's share is measured per container.
  fieldNames:
    - $=yield TenXEnv.get("symbolMessageField")

  # 'containerField' names the field whose value scopes the share denominator
  #  (the per-container total). Defaults to the k8s container name, which is
  #  stable across pod replicas (never the pod). When the field is absent on an
  #  event (non-k8s input), the regulator falls back to a single node-wide bucket.
  containerField: $=yield TenXEnv.get("k8sContainerNameField")

  # 'resetIntervalMs' is the window over which recent share is measured. The
  #  engine caps counter reset intervals at 255 seconds, so the effective maximum
  #  window is ~4.25 minutes.
  resetIntervalMs: $=parseDuration("4m")

  # 'absoluteCap' is the fleet-wide trigger (HEADLINE GUARANTEE): the maximum bytes
  #  of a single pattern that may accumulate per container within the current
  #  window. No single pattern can exceed this many bytes per container per window;
  #  customers can compute their worst-case per-pattern-per-container spend from
  #  this number directly.
  #
  #  Default 0 = disabled. Three customer configurations are first-class:
  #    - Per-container only: leave 'absoluteCap' unset, set 'capLookupFile' below.
  #      Listed containers get the file's cap; unlisted containers are
  #      unregulated by the absolute cap. Most selective.
  #    - Fleet-wide only: set 'absoluteCap' to a positive integer (e.g., 10485760
  #      for 10 MB). Applies to every container the regulator sees.
  #    - Both: per-container entries in 'capLookupFile' override the fleet-wide
  #      cap; unlisted containers fall back to the fleet-wide cap (safety floor).
  # absoluteCap: 10485760   # 10 MB

  # 'minSharePercent' is the sanity guard against false positives on legitimately
  #  high-volume containers. If a pattern is over `absoluteCap` BUT below this
  #  share of its container's volume, it is left alone -- the pattern is a small
  #  fraction of a chatty container, not an outlier.
  minSharePercent: 0.05

  # 'severityFloors' is the minimum retention per severity level, applied as an
  #  absolute floor that BEATS the share cap: even a pattern over its cap keeps at
  #  least this fraction of each level. Floor-map keys must match the level
  #  vocabulary emitted by the level enrichment.
  severityFloors:
    - TRACE=0.1
    - DEBUG=0.1
    - INFO=0.1
    - WARN=0.3
    - ERROR=0.5
    - CRITICAL=0.5   # the level enrichment maps fatal/critical -> CRITICAL
    - FATAL=0.5      # kept for forwarders whose level vocabulary emits FATAL

  # 'minRetentionThreshold' is the floor used for any level not present in
  #  'severityFloors'.
  minRetentionThreshold: 0.1

  # 'warmupMs' is the per-instance grace period before the regulator starts capping a
  #  newly-seen container, giving the per-pattern sample counts time to fill. Scope is
  #  per regulator instance, so a regulator restart restarts the window. See
  #  https://doc.log10x.com/run/receive/rate/#warmup for the operator guide.
  warmupMs: $=parseDuration("5m")

  # 'baselineCount' is the number of events of each pattern kept per window
  #  regardless of share, so even a heavily-capped pattern leaves a forensic sample.
  baselineCount: 5

  # 'ingestionCostPerGB' is used only to render savings metrics in dollars; it does
  #  not affect the keep/drop decision (the decision is share-based).
  ingestionCostPerGB: 1.5

  # ---------------------------- Mute File Options ----------------------------

  # Optional declarative mute file keyed by the joined 'fieldNames'. Unlike before,
  # the mute file COMPOSES with the regulator rather than replacing it: a listed,
  # active pattern is decided by its file entry (the human declaration wins), and
  # everything else is handled by the share-based regulator.
  #
  # File format (CSV; header row + one comma-separated entry per row):
  #   fieldSet,value
  #   <fieldSetKey>,<sampleRate>:<untilEpochSec>[:<reason>]
  #
  # sampleRate 1.0 = never sampled; <1.0 = retain at that rate. Entries self-heal
  # past 'untilEpochSec'. The severity floor still applies so a 0.0 mute never
  # silences ERROR/FATAL.
  #
  # Periodically pulling the mute file to keep it fresh is done via the gitops
  # configuration -- see https://doc.log10x.com/config/github/#config
  lookup:

    # 'file' specifies the mute file path. Hot-reloaded on in-place writes (the
    #  gitops pattern); Kubernetes ConfigMap mounts won't reload. Comment out to
    #  run the regulator alone (the default).
    # file: $=path("data/sample/mutes") + "/mutes.csv"

    # 'retain' specifies the period before the file is marked as stale.
    retain: $=parseDuration("10m")

  # ---------------------------- Cap File Options -----------------------------

  # Optional declarative per-container cap file keyed by the value of
  # 'containerField' (the k8s container name by default). Each entry assigns a
  # byte cap to a specific container; the file wins per-event over 'absoluteCap'
  # above. Listed containers get the file's cap; unlisted containers fall back
  # to 'absoluteCap' (or to no cap, when 'absoluteCap' is unset/0).
  #
  # File format (CSV; header row + one comma-separated entry per row):
  #   container,cap
  #   <container>,<bytes>[:<untilEpochSec>][:<reason>]
  #
  # Intended to be managed via GitOps + the log10x_configure_regulator MCP tool,
  # which derives per-container caps from a monthly dollar budget and opens a PR
  # against this file.
  capLookup:

    # 'file' specifies the per-container cap file path. Hot-reloaded on in-place
    #  writes (the gitops pattern); also hot-reloaded when the file is replaced
    #  via ATOMIC_MOVE (the kubernetes ConfigMap pull driver pattern).
    #
    # Default points at the stable destination written by the engine's
    # kubernetes ConfigMap pull driver:
    #   ${java.io.tmpdir}/tenx/kubernetes/<namespace>/<configMap>/caps.csv
    #
    # CAP_LOOKUP_FILE env var overrides this for non-k8s deployments or for
    # operators who prefer a fixed absolute path (gitops-managed file on disk).
    file: $=TenXEnv.get("CAP_LOOKUP_FILE", TenXEnv.get("java.io.tmpdir", "/tmp") + "/tenx/kubernetes/" + TenXEnv.get("K8S_NAMESPACE", "demo") + "/" + TenXEnv.get("K8S_CONFIGMAP", "log10x-action-intent") + "/caps.csv")

    # 'retain' specifies the period before the file is marked as stale.
    retain: $=parseDuration("10m")

  # --------------------------- Action File Options ---------------------------

  # Optional declarative per-SERVICE action file, keyed by the value of
  # 'containerField' (the k8s container name = the service). Each entry assigns
  # the disposition of that service's regulator-identified excess: 'drop'
  # (default), 'offload' (to customer S3), 'tier_down' (SIEM cheap tier),
  # 'compact' (lossless encode), 'sample', or 'pass'. The byte cap above still
  # bounds the excess; the action only decides what happens to it. Unlisted
  # services default to 'drop' (the original regulator behavior).
  #
  # File format (CSV; header row + one comma-separated entry per row):
  #   container,action
  #   <container>,<action>[:<untilEpochSec>][:<reason>]
  #
  # Managed via GitOps + the log10x_configure_engine MCP tool, which derives the
  # per-service action from the per-pattern action plan and opens a PR against
  # this file (a sibling of the cap file in the same ConfigMap).
  # 'actionLookupFile' is the per-service action file path. Declared as a FLAT
  #  key (like 'fieldNames' / 'minSharePercent') so it maps to the
  #  rateReceiverActionLookupFile option -- a new nested sub-group (e.g.
  #  actionLookup.file) is NOT recognized by the config-to-option mapper, even
  #  though capLookup.file is (capLookup is special-cased). Always set (default
  #  below, sibling to the cap file) so the cap-variant regulator can read it.
  #  ACTION_LOOKUP_FILE overrides for non-k8s / fixed-path deployments.
  actionLookupFile: $=TenXEnv.get("ACTION_LOOKUP_FILE", TenXEnv.get("java.io.tmpdir", "/tmp") + "/tenx/kubernetes/" + TenXEnv.get("K8S_NAMESPACE", "demo") + "/" + TenXEnv.get("K8S_CONFIGMAP", "log10x-action-intent") + "/actions.csv")

Options

Specify the options below to configure the rate receiver:

Name	Description
rateReceiverFieldNames	List of TenXObject fields to identify rate counter buckets
rateReceiverContainerField	Field whose value scopes the per-container share denominator
rateReceiverResetIntervalMs	Reset interval for rate counters in milliseconds
rateReceiverMinRetentionThreshold	Default retention floor for severity levels not listed in severityFloors
rateReceiverSeverityFloors	Minimum retention per severity level, applied as an absolute floor
rateReceiverLookupFile	Declarative mute file keyed by field-set
rateReceiverLookupRetain	Retention period for the lookup file containing global event type rates
rateReceiverActionLookupFile	Declarative per-service action file, keyed by the `rateReceiverContainerField` value; decides the disposition of each service's regulator excess
rateReceiverCapLookupFile	Declarative per-container byte cap file, keyed by the `rateReceiverContainerField` value
rateReceiverCapLookupRetain	Retention period for the per-container cap file before it is considered stale
rateReceiverWarmupMs	Per-container grace period before this regulator instance starts capping
rateReceiverBaselineCount	Events per pattern kept each window regardless of share
rateReceiverAbsoluteCap	Fleet-wide byte cap per pattern per container per window; `0` (default) disables the cap unless overridden per-container via `rateReceiverCapLookupFile`
rateReceiverMinSharePercent	Minimum share of container volume below which a pattern is exempt from sampling
rateReceiverIngestionCostPerGB	Vendor ingestion cost per GB in USD, for rendering savings in dollars

rateReceiverFieldNames

List of TenXObject fields to identify rate counter buckets.

Type	Default
List	[symbolMessage]

Defines the list of TenXObject field names extracted to identify which rate counter bucket an event belongs to. The list usually contains the symbolMessage field from the message enrichment module but can include additional fields like GeoIP, HTTP code, k8s container name, or custom enrichments for multi-dimensional rate tracking.

Common Use Cases:

Single-app receiving (per event type):

rateReceiverFieldNames:
  - symbolMessage

Multi-dimensional tracking (event type + geography + HTTP status):

rateReceiverFieldNames:
  - symbolMessage
  - country
  - httpCode

Multi-app receiving in Kubernetes:

Option A: Cap total spend per app (all event types combined):

rateReceiverFieldNames:
  - container  # Aggregates all event types for each app

Each app's total spend (across all event types and pods) gets one cap. Simple but loses event-type intelligence.

Option B: Cap spend per event type per app:

rateReceiverFieldNames:
  - symbolMessage  # Event type
  - container      # App identifier (same across all pods)

Each (event type × app) combo gets its own cap. Provides fairness within apps but allows apps with many event types to potentially exceed one total cap.

The container is configured separately via rateReceiverContainerField (it scopes the share denominator), so fieldNames identifies only the log pattern itself.

rateReceiverContainerField

Field whose value scopes the per-container share denominator.

Type	Default
String

Names the field whose value scopes the share denominator (the per-container total). A pattern's share is measured against the total volume of the container it belongs to, so the cap is enforced per (pattern, container).

Defaults to the k8s container name, which is stable across pod replicas, scaling from 1 to 10 pods does not bypass the cap, and a sidecar never consumes the application container's allowance. Use container, never pod.

When the field is absent on an event (non-k8s input, or no k8s extractor configured), the regulator falls back to a single node-wide bucket and enforces the cap per pattern across the node.

rateReceiverResetIntervalMs

Reset interval for rate counters in milliseconds.

Type	Default
Number	240000

Defines the window in milliseconds over which a pattern's recent share is measured. The counters reset every interval, so share reflects recent volume rather than all-time totals.

Shorter windows (e.g., 1 minute) are more reactive but noisier; longer windows are smoother but slower to adapt. The default of 4 minutes balances the two.

Validation: Must be at least 60000 milliseconds (1 minute). The engine caps counter reset intervals at 255 seconds, so the effective maximum window is ~4.25 minutes, values above that are clamped.

rateReceiverMinRetentionThreshold

Default retention floor for severity levels not listed in severityFloors.

Type	Default
Number	0.1

Defines the retention floor (0.0 to 1.0) used for any severity level not present in rateReceiverSeverityFloors. Ensures a pattern over its cap still retains at least this fraction of events whose level has no explicit floor, preventing complete data loss.

Validation: Must be greater than 0.01.

rateReceiverSeverityFloors

Minimum retention per severity level, applied as an absolute floor.

Type	Default
List	[]

defines a map of severity levels to a minimum retention fraction. The floor is absolute (not a multiplier) and beats the share cap: even a pattern over its cap keeps at least this fraction of each level, so high-severity events are never fully suppressed.

The floor also applies under a mute-file entry, so a 0.0 mute never silences ERROR/FATAL.

Floor-map keys must match the level vocabulary emitted by the level enrichment. Any level not listed uses rateReceiverMinRetentionThreshold.

For example:

severityFloors:
  - TRACE=0.1
  - DEBUG=0.1
  - INFO=0.1
  - WARN=0.3
  - ERROR=0.5
  - FATAL=0.5

rateReceiverLookupFile

Declarative mute file keyed by field-set.

Type	Default
String

Defines the path to a declarative mute file that caps specific log patterns by the joined field-set defined in rateReceiverFieldNames (e.g. symbolMessage, container, httpCode). The key format is the same one the local receiver uses for per-node counters.

When this option is set, the mute file composes with the regulator rather than replacing it: a listed, active pattern is decided by its file entry (the human declaration wins, and the regulator is skipped for that event), while every other pattern is handled by the share-based regulator.

File format (CSV; header row + one comma-separated entry per row):

fieldSet,value
<fieldSetKey>,<sampleRate>:<untilEpochSec>[:<reason>]

• fieldSetKey, the joined values of the fields named in rateReceiverFieldNames, separated by _. With rateReceiverFieldNames: [symbolMessage] the key is just the symbolMessage (e.g. Error_syncing_pod). With [symbolMessage, container] the key is symbolMessage_container (e.g. heartbeat_debug_frontend).
• sampleRate, probability in [0, 1.0] that a matching event is retained. 0 = full mute; 0.1 = keep 10%; 1.0 = no-op.
• untilEpochSec, mute expires at this Unix epoch (seconds). Past that, the entry becomes a no-op until someone edits or removes it. Self-healing by design.
• reason, optional free-text string for audit. Not used at runtime. Must not contain commas (would break CSV parsing).

Example (with rateReceiverFieldNames: [symbolMessage]):

fieldSet,value
Error_syncing_pod,0.10:1744848000:pod error spam OPS-4821
heartbeat_debug,0:1744416000:k8s liveness 200s
jwt_validated,0.25:1744502400:auth flood after deploy

The file is hot-reloaded on in-place writes (the gitops pattern); a Kubernetes ConfigMap mount won't reload because the CM swap is a symlink rename, not an in-place write.

Why this shape:

• Field-set keyed, not regex keyed → mute keys are the exact identifiers the Reporter attributes cost to (same rateReceiverFieldNames on both sides), so a "top spender" in the Reporter maps 1:1 to a mute entry.
• Git-friendly: the file is a human-readable declaration that can live in a config repo, reviewed via PR, git blame-d for who/why.
• Self-healing: every mute has an explicit expiry, so forgotten entries eventually stop filtering instead of silently dropping production data forever.
• AI-editable: an operator can ask an assistant (e.g., Claude Code via the Log10x MCP) to "mute Error_syncing_pod for 24 hours at 10%", the assistant reads the Reporter's cost attribution, appends the entry, and opens a PR. The mute file is the interface.

Severity floor still applies. Even a 0.0 mute will retain high-severity events at their rateReceiverSeverityFloors fraction. This prevents a poorly-scoped mute from silencing ERROR/FATAL traffic.

When rateReceiverLookupFile is unset, the regulator runs alone on every pattern.

rateReceiverLookupRetain

Retention period for the lookup file containing global event type rates.

Type	Default
Number	300000

Defines the retention period for the lookup file containing global event type frequency data.

If the file's last modified time is older than this period, the lookup is considered stale, and local counter rates are used. Used to make sampling decisions based on cluster-wide event patterns.

Validation: Must be greater than 60000 milliseconds.

rateReceiverActionLookupFile

Declarative per-service action file, keyed by the `rateReceiverContainerField` value; decides the disposition of each service's regulator excess.

Type	Default
String	""

Defines the path to a declarative per-service action file (sibling to the cap file). Each entry assigns the disposition of a service's regulator-identified excess: drop (default), offload (to customer S3), tier_down (SIEM cheap tier), compact (lossless encode), sample, or pass. The byte cap (rateReceiverCapLookupFile) still bounds the excess; the action only decides what happens to it. Unlisted services default to drop (the original regulator behavior). Read by the cap-variant regulator classes, which call route(action) at the over-budget decision point instead of a hardcoded drop.

File format (CSV; header row + one comma-separated entry per row):

container,action
<container>,<action>[:<untilEpochSec>][:<reason>]

• container, value of rateReceiverContainerField (the k8s container = the service).
• action, one of drop / offload / tier_down / compact / sample / pass.
• untilEpochSec, optional Unix-epoch (seconds) expiry; past it the entry is a no-op.
• reason, optional free-text for audit. Must not contain commas (would break CSV parsing).

Intended to be managed via GitOps + the log10x_configure_engine MCP tool, which derives per-service actions from the per-pattern action plan it already computes.

rateReceiverCapLookupFile

Declarative per-container byte cap file, keyed by the `rateReceiverContainerField` value.

Type	Default
String

Defines the path to a declarative per-container cap file. Each entry assigns a byte cap to a specific container (the value of rateReceiverContainerField, which defaults to the k8s container name). The file's cap wins per-event over rateReceiverAbsoluteCap: listed containers get the file's cap, unlisted containers fall back to the fleet-wide cap (or to no cap, if rateReceiverAbsoluteCap is 0).

File format (CSV; header row + one comma-separated entry per row):

container,cap
<container>,<bytes>[:<untilEpochSec>][:<reason>]

• container, value of rateReceiverContainerField for the events to cap. In k8s this is the k8s container name, stable across pod replicas.
• bytes, integer byte cap per pattern per container per window. 0 exempts the container from the absolute cap entirely (the over-cap branch is skipped for it).
• untilEpochSec, optional Unix-epoch (seconds) expiry. Past that, the entry becomes a no-op and the fallback cap applies.
• reason, optional free-text string for audit. Not used at runtime. Must not contain commas (would break CSV parsing).

Example:

container,cap
payment-service,4194304:1735689600:annual budget protection PAY-101
auth-service,2097152
istio-proxy,0:1735689600:exempt platform sidecar PLAT-42

Why this shape:

• Container-keyed, matching the regulator's container axis. The file's key is the same value the regulator's counters are bucketed by, so listed caps map 1:1 to counters without translation.
• Git-friendly: a human-readable declaration that lives in a config repo, reviewed via PR, git blame-d for who/why.
• Self-healing: every entry can carry an explicit expiry, so forgotten caps eventually stop filtering instead of silently dropping production data forever.
• AI-editable: an operator can ask an assistant (e.g., Claude Code via the Log10x MCP configure_regulator tool) to derive a cap from a monthly dollar budget, append the entry, and open a PR. The cap file is the interface.

Severity floor still applies. Even at a tight cap the regulator's rateReceiverSeverityFloors retain ERROR/CRITICAL events at their floor fraction, so a tight cap never fully silences high-severity traffic.

When rateReceiverCapLookupFile is unset, every container falls back to rateReceiverAbsoluteCap (which itself defaults to 0 = disabled).

The file is hot-reloaded on in-place writes (the gitops pattern); a Kubernetes ConfigMap mount won't reload because the CM swap is a symlink rename, not an in-place write.

rateReceiverCapLookupRetain

Retention period for the per-container cap file before it is considered stale.

Type	Default
Number	300000

Defines the retention period (in milliseconds) for the cap file (rateReceiverCapLookupFile). If the file's last modified time is older than this period, a warning is logged. The cap entries continue to apply; the staleness check is advisory so operators notice when an automated tooling pipeline has stopped updating the file.

Validation: Must be greater than 60000 milliseconds.

rateReceiverWarmupMs

Per-container grace period before this regulator instance starts capping.

Type	Default
Number	300000

Defines a per-container grace period in milliseconds. A container is left unregulated for this long after this regulator instance first sees its events. The default is 5 minutes.

Why it exists: the regulator's per-pattern sample counts start empty. Without a few minutes of accumulation, a low-volume pattern can look like the dominant one purely because of ordering. The warmup defers cap decisions until there are enough samples to tell a noisy pattern from a quiet one with confidence. This is a delay only; no learned baseline is built, and the only state that survives is the container's first-seen timestamp.

"First sees" is per regulator instance, not per container birth. A container that has been running for hours but whose events have only just started flowing through this regulator (e.g. after a regulator restart or forwarder reconnect) restarts the warmup window. On a daemonset rolling restart the cap is therefore disabled for warmupMs per node as it cycles.

Lower the value for fast-starting apps that should be capped sooner after a restart. Raise it for slow-ramping JVMs or workloads with long init phases. Patterns that are legitimately dominant in steady state belong on the mute file, not in a longer warmup.

rateReceiverBaselineCount

Events per pattern kept each window regardless of share.

Type	Default
Number	5

Defines how many events of each (pattern, container) are always kept per window, regardless of share, so even a heavily-capped pattern leaves a small forensic sample to inspect during an incident.

rateReceiverAbsoluteCap

Fleet-wide byte cap per pattern per container per window; `0` (default) disables the cap unless overridden per-container via `rateReceiverCapLookupFile`.

Type	Default
Number	0

Defines a fleet-wide byte cap: the maximum bytes of a single pattern (a unique combination of rateReceiverFieldNames values) that may be retained per container within the current window (rateReceiverResetIntervalMs). Applies to every container the regulator sees, unless that container has its own entry in rateReceiverCapLookupFile, which wins per-event.

At or below the resolved cap the pattern is kept untouched. Above it, the regulator engages: if the pattern is also above rateReceiverMinSharePercent (the sanity guard), the event is sampled at the severity floor probability.

0 (the default) disables the fleet-wide cap. With no fleet-wide cap and no per-container entry in rateReceiverCapLookupFile, the regulator's over-cap branch never engages for that container. Protection is strictly opt-in. Three configurations are first-class:

• Per-container only: set rateReceiverCapLookupFile. Listed containers get their cap; unlisted containers are unregulated by the absolute cap. Most selective.
• Fleet-wide only: set rateReceiverAbsoluteCap to a positive integer. Applies to every container.
• Both: per-container entries override the fleet-wide cap; unlisted containers fall back to the fleet-wide cap (safety floor).

Example: 10485760 (10 MB) means no single pattern can exceed 10 MB per container per 5-minute window. The maximum monthly spend per pattern per container can be computed from this cap and the vendor's per-GB rate.

rateReceiverMinSharePercent

Minimum share of container volume below which a pattern is exempt from sampling.

Type	Default
Number	0.05

Defines the share-of-container sanity guard (0.0 to 1.0): if a pattern is above the absolute cap BUT below this share of its container's total volume, the regulator skips it. The pattern is part of a legitimately high-volume container (busy API gateway, access log workload), not a noisy outlier.

Share is (pattern bytes + event) / (container bytes + event) over the current window.

Example: 0.05 means a pattern above the absolute cap is still retained if it represents less than 5% of its container's total volume. Prevents false positives on naturally chatty containers.

rateReceiverIngestionCostPerGB

Vendor ingestion cost per GB in USD, for rendering savings in dollars.

Type	Default
Number	1.5

Defines the cost per GB charged by your observability vendor for log ingestion. Used only to render savings metrics in dollars (dropped bytes × cost per GB); it does not affect the keep/drop decision, which is share-based.

Common vendor pricing (2025):

• Splunk Cloud: ~$1.50/GB (varies by contract, SKU)
• Datadog Logs: ~$0.10-$0.25/GB (depends on tier: standard, flex, online archives)
• Elastic Cloud: ~$0.109/GB (standard logging tier)
• New Relic: ~$0.30/GB (Data Plus)
• Sumo Logic: ~$1.50/GB (depends on plan)
• AWS CloudWatch Logs: ~$0.50/GB ingestion + $0.03/GB storage.

This module is defined in rate/module.yaml.