checkId: check.core.env.memory plugin: stellaops.doctor.core severity: warn tags: [quick, environment, resources]

Memory Usage

Doctor check check.core.env.memory — for operators watching a Stella Ops service’s working set so they can catch leaks and right-size limits before the runtime gets OOM-killed.

What It Checks

Verifies that the application process memory usage is within acceptable limits. The check reads the current process metrics and applies two thresholds:

Evidence collected includes:

• WorkingSet: physical memory currently allocated to the process.
• PrivateBytes: total private memory allocated.
• GCHeapSize: managed heap size reported by the GC.
• GCMemory: total managed memory from GC.GetTotalMemory().
• Gen0/Gen1/Gen2 Collections: garbage collection counts for each generation.

Why It Matters

Excessive memory usage leads to out-of-memory kills (OOM), especially in containerized deployments where memory limits are enforced. When a Stella Ops service is OOM-killed:

• In-flight requests are dropped.
• Evidence writes may be incomplete, compromising the audit trail.
• Scan results in progress are lost.
• The container restarts, causing a brief outage and potential data corruption.

High Gen2 GC counts can also indicate a memory leak, where objects are promoted to the long-lived generation faster than they can be collected.

Common Causes

• Memory leak in application code (undisposed resources, growing caches)
• Large data sets loaded entirely into memory (SBOM graphs, scan results)
• Insufficient memory limits configured for the container
• Normal operation with high load (many concurrent scans or requests)
• Memory-intensive operations in progress (large SBOM diff, graph analysis)

How to Fix

Docker Compose

Set memory limits for the service in docker-compose.yml:

services:
  platform:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

Analyze memory usage:

# Check container memory stats
docker stats --no-stream <container>

# Capture a memory dump for analysis
docker compose exec <service> dotnet-dump collect -p 1

Bare Metal / systemd

Set memory limits in the systemd unit:

[Service]
MemoryMax=2G
MemoryHigh=1536M

Analyze memory:

# Install diagnostics tools
dotnet tool install -g dotnet-gcdump

# Capture GC dump
dotnet-gcdump collect -p <pid>

# Analyze with dotnet-dump
dotnet-dump analyze <dump-file>

Kubernetes / Helm

Set resource limits in Helm values:

resources:
  limits:
    memory: "2Gi"
  requests:
    memory: "512Mi"

Monitor memory:

kubectl top pods -l app=stellaops-platform

Verification

stella doctor run --check check.core.env.memory

Related Checks

• check.core.env.diskspace — checks available disk space
• check.core.services.health — overall service health which can degrade under memory pressure

See the Doctor reference for the full check catalog, CLI usage, and export bundles.