Implement Memory Limiter prototype

[dashpole]

Prometheus Memory Limiter: Implementation Plan & Design Document

This document defines the architectural specification, component design, integration points, and rollout for the Prometheus Memory Limiter (prometheus/proposals#76).

---

1. System Architecture Overview

The Memory Limiter acts as a centralized runtime circuit breaker. It periodically evaluates memory pressure using Go's runtime metrics (runtime/metrics) and coordinates load-shedding mitigations across Prometheus subsystems without modifying Go runtime tuning parameters (GOMEMLIMIT / GOGC are treated strictly as read-only inputs).

                               ┌───────────────────────────┐
                               │     Go Runtime Metrics    │
                               │  (/memory/classes/total,  │
                               │   /memory/classes/heap/   │
                               │    released, /gc/gomem-   │
                               │       limit:bytes)        │
                               └─────────────┬─────────────┘
                                             │ Poll (default 100ms)
                                             ▼
                               ┌───────────────────────────┐
                               │   Memory Limiter Engine   │
                               │   (pkg/memorylimiter)     │
                               │  - Pressure Calculation   │
                               │  - Transitions Tracking   │
                               │  - State Machine (OK,     │
                               │    SOFT_LIMIT, HARD_LIMIT)│
                               └─────────────┬─────────────┘
                                             │ State / Predicates
             ┌───────────────────────────────┼───────────────────────────────┐
             ▼                               ▼                               ▼
    ┌─────────────────┐             ┌─────────────────┐             ┌─────────────────┐
    │  Scrape Manager │             │   TSDB Engine   │             │   Web Handlers  │
    │  (Hard Limit)   │             │  (Soft Limit)   │             │  (Soft & Hard)  │
    │ - Skip scrapes  │             │ - Pause on-disk │             │ - 503 OTLP/RW   │
    │ - 0 WAL Appends │             │   compaction    │             │ - 503 Remote Rd │
    │ - No up=0 write │             │ - Keep Head/WAL │             │   & Federation  │
    └─────────────────┘             └─────────────────┘             └─────────────────┘
             │                                                               │
             ▼                                                               ▼
    ┌─────────────────┐                                             ┌─────────────────┐
    │  Rules Manager  │                                             │   Prometheus    │
    │  (Hard Limit)   │                                             │   Telemetry     │
    │ - Pause indep.  │                                             │ - State gauges  │
    │   rec. rules    │                                             │ - Seconds total │
    │ - Keep alerts   │                                             │ - Transitions   │
    └─────────────────┘                                             └─────────────────┘

---

2. Core Controller Engine (pkg/memorylimiter)

2.1 Package Interface and Data Types

package memorylimiter

import (
	"context"
	"log/slog"
	"sync"
	"time"
)

type LimiterState int

const (
	StateOK LimiterState = iota
	StateSoftLimit
	StateHardLimit
)

type MemoryLimiter interface {
	// State returns the current evaluation state.
	State() LimiterState

	// Granular mitigation predicates for zero-lock checking:
	AllowScrape() bool
	AllowOTLP() bool
	AllowRemoteWrite() bool
	AllowRemoteRead() bool
	AllowFederation() bool
	AllowBlockCompaction() bool
	AllowRecordingRules() bool

	// Dynamic config updates on SIGHUP
	ApplyConfig(cfg *Config) error
	
	// Lifecycle
	Start(ctx context.Context)
	Stop()
}

2.2 Memory Pressure Sensor & GC Pacer Accounting

The limiter queries runtime/metrics on a background ticker (default 100ms) with zero allocations.

// In-use calculation:
// Total mapped memory minus memory released back to the OS.
// in_use = /memory/classes/total:bytes - /memory/classes/heap/released:bytes
// gomemlimit = /gc/gomemlimit:bytes
// gc_limiter_enabled = /gc/limiter/last-enabled:gc-cycle

Sensor Derivation:

1. In-Use Memory: Captures active heap objects, stack allocations, metadata, chunk allocations, and unreleased GC arenas without double-counting scavenged pages.
2. GOMEMLIMIT Validation:
   • If /gc/gomemlimit:bytes returns math.MaxInt64 (unconfigured) when --enable-feature=memory-limiter is set, Prometheus fails fast at startup with an explicit error: memory limiter requires GOMEMLIMIT or --auto-gomemlimit to be configured.
3. GC CPU Limiter Override:
   • If /gc/limiter/last-enabled:gc-cycle advanced in the last evaluation window, Go's GC CPU limiter has engaged (meaning Go is spending >50% CPU in GC trying to stay under GOMEMLIMIT). In this state, the memory limiter immediately escalates to StateHardLimit, regardless of whether in_use / GOMEMLIMIT has crossed hard_limit_ratio.

2.3 State Transitions & Flapping Observability

As specified in the proposal, state transitions are evaluated directly against the configured ratios:

• Soft Limit: Reached when in_use / GOMEMLIMIT >= soft_limit_ratio (default 0.70).
• Hard Limit: Reached when in_use / GOMEMLIMIT >= hard_limit_ratio (default 0.85) OR gc_limiter_active.
• Transitions Tracking: Every transition increments prometheus_memory_limiter_transitions_total{from, to} and records time in prometheus_memory_limiter_engaged_seconds_total{limit}. This enables direct measurement of transition frequency and duty cycles to evaluate the impact of flapping under sustained boundary load.

---

3. Subsystem Integrations & Mitigations

3.1 Scrape Loop (scrape/scrape.go)

When AllowScrape() is false:

1. Scrape Bypass: Skip network HTTP request, decompression, and body parsing entirely.
2. Fast Failure & Zero WAL Write:
   • Return immediately with errScrapeMemoryLimitExceeded.
   • Update target status (for UI/API).
   • Do NOT append up=0 or staleness markers to the WAL. The transaction is bypassed, ensuring $0$ heap allocation and $0$ WAL I/O during memory exhaustion. Values carry forward under the standard 5-minute lookback.
3. Telemetry: Increment prometheus_target_scrapes_skipped_total{job, instance}.

3.2 TSDB Compaction (tsdb/db.go, tsdb/compact.go)

Mitigation level: Soft Limit.

1. Paused Component: DB.compactBlocks() (on-disk block merging). Pausing block compaction carries zero risk of data loss and does not affect ingestion capacity.
2. Preserved Component: DB.CompactHead() and WAL truncation MUST continue running. Active Head memory and WAL disk size remain bounded.
3. Implementation: An atomic boolean flag blockCompactionPaused checked before acquiring the block compaction lock in tsdb.DB.run().

3.3 HTTP Handlers (web/api/v1/api.go, web/web.go, otlp/receiver.go)

When respective limiters are active:

1. OTLP Ingestion (/api/v1/otlp) & Remote Write Receiver (/api/v1/write):
   • Mitigation level: Hard Limit.
   • Checked at HTTP handler entry, before reading the request body or decompressing protobuf.
   • Return HTTP 503 Service Unavailable with header Retry-After: 5.
2. Remote Read (/api/v1/read) & Federation (/federate):
   • Mitigation level: Soft Limit.
   • Checked at HTTP handler entry before initiating series postings queries.
   • Return HTTP 503 Service Unavailable with Retry-After: 5.

3.4 Rules Engine (rules/manager.go)

Mitigation level: Hard Limit.

1. Alerting Rules: Never paused. Safety invariant: alerts must fire even under resource pressure.
2. Recording Rules:
   • Parse PromQL expressions in rule groups to identify independent vs dependent recording rules.
   • Any recording rule whose output series name is not referenced in an alerting rule or downstream recording rule is skipped during Hard Limit.
   • Increment prometheus_rule_group_iterations_skipped_total{rule_group}.

---

4. Configuration Schema (config/config.go)

runtime:
  gogc: 100
  memory_limiter:
    # Evaluation interval for memory pressure
    check_interval: 100ms

    # Soft limit threshold (non-destructive mitigations)
    soft_limit_ratio: 0.70

    # Hard limit threshold (destructive mitigations)
    hard_limit_ratio: 0.85

    enforcement:
      # Soft Limit mitigations
      pause_block_compaction: true
      reject_remote_read: true
      reject_federation: true

      # Hard Limit mitigations
      fail_scrapes: true
      reject_otlp: true
      reject_remote_write: true
      pause_recording_rules: true

---

5. Exported Telemetry Specification

Metric Name	Type	Labels	Description
prometheus_memory_limiter_active	Gauge	limit="soft|hard"	1 if the mitigation limit is currently engaged, 0 otherwise.
prometheus_memory_limiter_engaged_seconds_total	Counter	limit="soft|hard"	Cumulative seconds spent in soft/hard mitigation states (for exact duty cycle calculation).
prometheus_memory_limiter_transitions_total	Counter	from, to	Number of state machine transitions (for flapping detection).
prometheus_memory_limiter_limit_bytes	Gauge	limit="soft|hard"	Absolute byte threshold computed from ratio and GOMEMLIMIT.
prometheus_memory_limiter_in_use_bytes	Gauge	—	In-use memory measured by controller (total - released).
prometheus_target_scrapes_skipped_total	Counter	job, instance	Total scrapes skipped due to memory limits.
prometheus_tsdb_block_compaction_paused	Gauge	—	1 if on-disk block compaction is paused by memory limiter.
prometheus_rule_group_iterations_skipped_total	Counter	rule_group	Number of independent recording rule group iterations skipped.