medicines.fyi
Field guide for broken systems

Treatments for recurring technical problems

Symptoms. Diagnosis. Treatment. Side effects. Prevention. A practical reference for engineers dealing with systems that fail in annoyingly familiar ways.

Categories

Start with the system that hurts.

View all categories →
K8s

Kubernetes

Known remedies for recurring cluster and workload failures.

→
PG

Postgres

Known remedies for recurring database and query failures.

→
SP

Spark

Known remedies for recurring jobs, skew, and executor pain.

→
RD

Redis

Known remedies for recurring cache and latency failures.

→
aws

AWS

Known remedies for recurring cloud, cost, and infrastructure failures.

→
CI

CI/CD

Known remedies for recurring pipeline and deployment failures.

→
TM

Team Problems

Known remedies for recurring ownership and coordination failures.

→
↗

Career

Known remedies for recurring visibility and leverage problems.

→
Featured treatment

A failure mode, fully dissected.

≈ Symptom
  • Pods restart with OOMKilled.
  • Exit code 137 (SIGKILL).
  • Memory climbs before restart.
  • Events report memory pressure.
! Likely causes
  • Container memory limit too low.
  • JVM heap exceeds cgroup headroom.
  • Memory leak or unbounded cache.
  • Burst traffic or skewed workload.
⌕ Diagnosis
  • Inspect pod events and restart reason.
  • Compare RSS, cache, heap, and limits.
  • Check workload concurrency.
  • Inspect heap dump when practical.
+ Treatments
  • Increase memory limit deliberately.
  • Right-size JVM heap and overhead.
  • Reduce concurrency or batch size.
  • Fix leaks or unbounded retention.
△ Side effects
  • Higher memory cost.
  • Lower node density.
  • Potentially reduced throughput.
  • Different GC characteristics.
✓ Prevention
  • Set sane requests and limits.
  • Load test with realistic data.
  • Alert on memory saturation early.
  • Design for backpressure.
Popular treatments

The failures people keep meeting.

View all treatments →
PG

Postgres slow query

Queries taking too long and blocking real work.

Postgres 🔥 12.4k
RD

Redis hot key

A single key is causing CPU or latency spikes.

Redis 🔥 9.8k
SP

Spark data skew

Uneven distribution creates slow stragglers.

Spark 🔥 8.7k
aws

NAT gateway cost spike

Unexpected egress cost from architecture choices.

AWS 🔥 6.1k
TM

Invisible work at job

High effort, low visible impact, weak leverage.

Team 🔥 5.3k
Programmatic access

Structured knowledge for automation.

Every treatment can eventually be modeled, versioned, queried, and consumed by tools. Humans get readable guidance. Machines get structured fields.

Consistent schema Predictable fields across treatments.
Search & filter Find by symptoms, causes, or tags.
Built for builders JSON-friendly by design.
GET /api/v1/treatments/OOMKilled Response 
{
  "problem": "OOMKilled",
  "category": "Kubernetes",
  "tags": ["pods", "memory", "oom"],
  "symptoms": [
    "Pods restart with OOMKilled",
    "Exit code 137"
  ],
  "causes": [
    "Memory limit too low",
    "JVM heap > container headroom"
  ],
  "treatments": [
    "Increase memory limit",
    "Right-size JVM heap"
  ],
  "prevention": [
    "Set sane requests & limits",
    "Monitor memory early"
  ],
  "version": "0.1.0-preview"
}
Coming soon.