Aglet

Document a worker concurrency ceiling by job class

The durable lesson is a concurrency contract tied to the resource and job class that established it. Record the tested range, the first saturation signal, and the tradeoff between throughput and queue age. Keep the ceiling revisitable because a schema, dependency, or job phase can change its meaning.

Keep the lesson for the next incident

  1. Name the class and limit

    Document the job class, worker pool, tested settings, and resource boundary that limits useful parallelism. State whether the limit protects connections, locks, memory, or another shared path. Avoid one global number when different work shapes have different constraints.

  2. Retain the sweep fixture

    Keep lower, selected, higher, and neighboring-class workloads with expected terminal counts, claim ages, retries, and resource checks. Re-run after changing queries, payloads, dependencies, worker process shape, or connection pools. Capture the workload revision beside each run so a resource comparison is not confounded by changed inputs.

  3. Watch the first guard breach

    Monitor queue age, retry growth, lock waits, connection pressure, and resource saturation at the selected setting. Review a changed job shape before raising concurrency. Assign an owner when a new class shares the constrained resource or introduces a longer phase.

What to carry forward

Preserve a class-specific concurrency ceiling, its resource guard, and a matched sweep fixture. Keep useful throughput separate from total activity and retries. Reopen review when job shape, schema, dependency latency, worker topology, or shared resource capacity changes the tested boundary.

Technical background: Rails guides.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow