DEV Community: Davi Orlandi

Atlas Online Archive for Large Collections: Keep Hot Data Hot

Davi Orlandi — Mon, 05 Oct 2026 14:37:56 +0000

Look at almost any production cluster and you will find the same shape. A thin slice of recent data gets nearly all reads and writes. Everything older is rarely touched but still sits on premium storage, inflates indexes, and eventually forces a bigger tier. You pay hot prices to store silence.

I have lived that bill. Compliance forbade TTL deletion. A handmade export pipeline meant owning a second query path forever. Atlas Online Archive became the managed middle ground: move eligible documents to MongoDB-managed object storage and keep them queryable through federation. The personal stake is not "cool feature." It is whether you can stop buying CPU and disks for data nobody opens.

How it works in practice

You define an archive rule, usually a date age, optionally a custom filter. Atlas runs background jobs that copy matching documents to object storage using the partition fields you chose. After a confirmed copy, documents leave the cluster. Federated connection strings query archive-only or cluster-plus-archive under the same namespace.

A few properties matter more than the marketing blurbs. Dedicated clusters (M10+) only. Archived data is read-oriented; do not treat it as your OLTP write plane. Jobs are asynchronous and consume cluster resources while they run. Your normal URI sees only the live cluster; historical access needs the federated endpoint. That last sentence is where teams get surprised.

Good candidates versus poor ones

Good candidates	Poor candidates
Event logs and audit trails	User profiles that keep changing
Orders older than a stable hot window	Tiny reference collections
IoT readings and metrics	Data that must stay low-latency forever
Closed tickets past the edit window	Documents refunded or edited indefinitely

Ask: once a document is old, is it effectively immutable? If not, push the archive age past the last realistic edit, or filter on a terminal status. Also ask whether anyone needs the data at all. If the answer is no, a TTL index is simpler than archiving.

Designing the rule without painting yourself into a corner

Date-based rules are the common case:

Archive documents where createdAt is older than 90 days

Index the predicate fields so the job does not scan forever:

db.orders.createIndex({ createdAt: 1 })

Custom filters help when coldness is not pure age (status in terminal states and closedAt old enough). Prefer moving windows over hard-coded calendar dates that rot. Start conservative (365 days) and ratchet hotter as confidence grows. Prefer an immutable date field. Archiving on updatedAt surprises you when batch jobs touch old rows and suddenly nothing looks cold enough.

Partition fields decide archive query cost

Partitions let federation skip irrelevant object-storage slices. The date field is typically one partition. Add a small number of extra fields ordered by how often historical queries filter on them (customerId, region). Moderate cardinality helps. Unique-per-document fields help little. Partitions are hard to change later. List the three real archive queries your team runs before you click save. That conversation has prevented more regret than any checklist I own.

Application patterns that keep history honest

Keep two clients when history matters: a live URI for writes and hot reads, and a federated URI for legitimate historical access. Time-route in the API: recent windows hit the cluster; older windows accept slower federation. For huge pulls, prefer async export over interactive scans. Set UI expectations honestly ("older than 90 days may load slower"). Users forgive slower history. They do not forgive silent empty results because the app still uses the live URI.

What Online Archive is not

It is not a backup or point-in-time restore substitute. It is not a free analytics lakehouse for arbitrary heavy joins. It is not writable storage for casual corrections (plan rehydrate flows). It is not worth the complexity on tiny collections. If historical access depends on stages unsupported against archived data, redesign that path before enabling the feature.

Cost sanity check

Savings come from smaller disks, smaller backups, and sometimes a lower cluster tier. You pay archive storage and federation processing instead. The win is largest when most bytes are cold and rarely queried.

const cutoff = new Date(Date.now() - 180 * 24 * 60 * 60 * 1000)
const total = await db.collection('orders').estimatedDocumentCount()
const eligible = await db.collection('orders').countDocuments({ createdAt: { $lt: cutoff } })
console.log(`${((eligible / total) * 100).toFixed(1)}% eligible`)

If most of the collection is eligible and those documents are rarely read, archiving is likely worth it. If eligibility is tiny, you are adding operational surface for theater.

Rollout checklist and common pitfalls

Confirm tier support and permissions. Measure first-month archive volume. Pilot on a low-risk collection during a quiet window. Prove a known archived id is readable through federation. Monitor job success, lag, and cluster CPU during backlog drain. Document rehydrate steps for the rare "make this hot again" case. Align retention and residency with compliance.

Common pitfalls stay boring and expensive: archiving data that still changes, missing indexes on rule fields, poor partition choices you cannot cheaply revise, forgetting that the app URI never sees archive rows, using archive where TTL deletion would do, and putting latency-sensitive features on federated reads.

Closing

Online Archive shines when collections are large because of age, not because of an active working set. Define crisp hot windows, archive with indexed predicates, query cold data with slower-SLO honesty, and keep writes on the live cluster. That is how you stop paying premium prices to store silence.

Walking Hierarchies with MongoDB $graphLookup (Without Melting Memory)

Davi Orlandi — Mon, 05 Oct 2026 14:37:53 +0000

The first time $graphLookup melted a primary for me, I was not trying to be clever. We had a category tree. We wanted descendants for an admin screen. Someone omitted maxDepth, the index story on parentId was weak, and a catalog import suddenly gave a root tens of thousands of children. The operator did exactly what we asked. We asked for too much on the wrong path. Latency spiked. Memory followed. The personal stake of this essay is that recursive convenience is not free.

Can MongoDB walk a hierarchy without a closure table? Yes, with guardrails. $graphLookup recursively follows parent and child links into an as array. Keep maxDepth, index connectToField, prune with restrictSearchWithMatch, and keep unbounded walks off customer-facing p99 paths. For hot reads on stable trees, materialized paths or closure tables still win.

How `$graphLookup` behaves when you respect it

For each input document, MongoDB starts from startWith, matches that value to connectToField in the from collection, then repeatedly follows connectFromField to connectToField until matches stop or maxDepth says stop. Results land in the array named by as. That array is not a guaranteed sorted path. Add depthField if you need levels.

{
  $graphLookup: {
    from: "categories",
    startWith: "$_id",
    connectFromField: "_id",
    connectToField: "parentId",
    as: "descendants",
    maxDepth: 6,
    depthField: "depth",
    restrictSearchWithMatch: { active: true }
  }
}

A minimal hierarchy that makes the direction obvious

db.categories.insertMany([
  { _id: "root", name: "Catalog" },
  { _id: "elec", name: "Electronics", parentId: "root" },
  { _id: "phones", name: "Phones", parentId: "elec" },
  { _id: "android", name: "Android", parentId: "phones" }
])

db.categories.aggregate([
  { $match: { _id: "android" } },
  {
    $graphLookup: {
      from: "categories",
      startWith: "$parentId",
      connectFromField: "parentId",
      connectToField: "_id",
      as: "ancestors",
      depthField: "depth"
    }
  }
])

Flip the connect fields (and start from a parent id) to walk downward into descendants. The direction is a modeling choice. The cost is not.

Guardrails that would have saved that admin screen

Always set maxDepth when cycles or huge fan-out are possible. Index connectToField and the fields you prune on. Prune early with restrictSearchWithMatch (active, tenant, region). Respect memory: wide graphs are hungry, so prefer shallow selective walks. Sort yourself with depthField plus $sortArray or client-side ordering. Keep writes simple and reads intentional: parent pointers for writes, $graphLookup for rare deep views, cache or materialize for hot paths.

When not to use it

Need	Prefer
One level of children	`$lookup` or embedded kids
Frequent ancestor checks on a stable tree	Materialized path (`root/elec/phones`)
Hot "all descendants" reads, rare reparents	Closure table
Heavy graph algorithms at huge scale	Specialized graph store

{ _id: "android", path: "root/elec/phones/android" }

That path string looks humble until you realize it turns a recursive read into a prefix query. Humble often wins.

A debugging recipe I trust more than optimism

Run explain("executionStats") on the aggregation. Confirm index use on connectToField. Measure documents landing in as for a worst-case seed. Lower depth or tighten the prune filter. Precompute a closure for the hottest roots if the UI must stay interactive. A useful product trick: return one level first and lazy-load children. Most users never need the entire tree in one payload, and most outages start by pretending they do.

Closing

$graphLookup is safe when bounded, indexed, and pruned. It is unsafe as an unbounded "recurse the catalog" button on a hot endpoint. Use it as a sharp tool for admin and ad hoc hierarchy walks, not as a substitute for a read model you should have materialized. The operator is powerful. Power without a depth limit is just a future incident report.

Lessons I Still Use from MongoDB in Action (Without Rewriting the Book)

Davi Orlandi — Mon, 05 Oct 2026 14:37:50 +0000

I am not going to retell Kyle Banker's MongoDB in Action chapter by chapter. Read the book for that. What follows are field notes: the subset of ideas that still change how I model services, especially now that Atlas makes it easy to treat MongoDB like a broken relational database with friendlier braces.

The personal stake is quieter than an outage story and just as expensive. Most MongoDB pain I see is still mismatched modeling wearing a scaling costume. Teams buy bigger tiers to paper over documents shaped like leftover ER diagrams. These rules of thumb are how I try to stop myself from doing that.

Rule 1: Model for queries, not for your ER diagram

Documents are not normalized tables. Start from the questions your API asks. If you always fetch a user with prefs, embedding often wins. If addresses are updated independently and shared, references often win. If you need both, embed a summary and reference the full document.

// Embed when the access pattern is one read
{
  _id: userId,
  email: "a@b.com",
  prefs: { locale: "pt-BR", marketingOptIn: false }
}

// Reference when the child set is unbounded
{
  _id: orderId,
  userId: userId,
  total: 1200
}

Cardinality matters. One-to-few, one-to-many, and one-to-squillions deserve different shapes. Huge embedded arrays that grow forever invent document-size pain, and then someone discovers the 16MB limit the hard way.

Rule 2: Atomicity lives at the document boundary

Single-document updates are atomic. Multi-document workflows need transactions or an outbox you designed on purpose. Prefer invariants that fit in one document. Use multi-document transactions when you must, not on every write out of fear. Pair state changes with outbox rows in the same transaction when you publish events. That last habit has saved me from more "eventual inconsistency" debates than any schema lecture.

Rule 3: Indexes are part of the schema

Do not treat indexes as a DBA afterthought. Write the filter plus sort shape first, then the index. Avoid an index-per-field shotgun that only creates write amplification. Prefer partial or sparse indexes when only a subset of documents need the path. Watch working set versus RAM. If you cannot read an explain plan on a hot path, you are guessing, and guessing is how "flexible schema" becomes "mysterious latency."

Rule 4: Aggregation is a product feature

The pipeline is not a party trick. Match early. Project away fat fields before heavy stages. Respect memory limits; spill to disk only when needed and safe. Do not reinvent joins with application-side N+1 if a better schema removes the need. Knowing when not to recurse in the database is modeling maturity, not a lack of ambition.

Rule 5: Favor embedding until a compelling reason appears

Useful compelling reasons still look the same years later. The child must stand alone in queries. The array would grow without bound. The read/write ratio makes denormalization too expensive to maintain. Application-level joins are allowed. With correct indexes and projections they are rarely the villain beginners fear. Denormalize only fields that are read often and updated rarely.

Rule 6: Flexible schema is not "no schema"

Dumping arbitrary JSON without ownership is an application smell. Share types in the application. Add server-side validation where it pays off. Keep an explicit schemaVersion when shapes evolve in place. Own field names across services. Flexibility without ownership is just entropy with nicer query syntax.

Patterns that still surprise teammates

Cached rollups: store comment counts near the parent instead of counting on every list read. Bucketing: time-series style buckets beat millions of tiny documents when telemetry arrives fast. Hot/cold honesty: separate cold data before the cluster becomes a museum of unread history.

What I leave to the book

Deep historical storage-engine lore and exhaustive admin tours belong in the text. The durable lessons I still carry are query-first modeling, index-as-schema, and respect for document atomicity.

Closing

Design the document around the query and the invariant, not around a relational habit. If that sounds obvious, good. The hard part is keeping the habit when a sprint pressure wants a quick collection "just like the SQL table." The book taught me the vocabulary. Production taught me why the vocabulary matters.

Consul Service Discovery That Does Not Lie: Health Checks First

Davi Orlandi — Mon, 05 Oct 2026 14:37:47 +0000

Service discovery without honest health checks is a catalog of corpses. I learned that the expensive way: a payments instance that answered 200 on / while its worker pool was deadlocked. Consul kept advertising it. Customers timed out. Dashboards looked fine. The personal stake was simple and humiliating. Discovery had done exactly what we configured it to do. We had configured a lie.

This essay is about making Consul return instances that can do useful work. The quality of payments.service.consul is not determined by how pretty the catalog looks. It is determined by how you define healthy.

Registration is a readiness story

Define the service and nested check blocks (or a checks array). Register with the local agent. Reload if the service was already registered. Confirm clients filter to the statuses you intend. Initial check status defaults to critical until the first success. That prevents newborns from receiving traffic before they are ready. Override with status = "passing" only when you understand the trade, because starting green is how you advertise an unfinished boot.

Prefer HTTP and TCP checks over shell folklore

If you are curling an endpoint from a script check, use an HTTP check. If you are probing a port with netcat, use a TCP check. Native checks avoid shell sprawl and reduce remote-execution risk compared with broadly enabled script checks.

service {
  name = "payments"
  port = 8080

  check {
    id       = "payments-http"
    name     = "HTTP /health/ready"
    http     = "http://127.0.0.1:8080/health/ready"
    method   = "GET"
    interval = "10s"
    timeout  = "2s"
    failures_before_critical = 3
  }
}

Probe 127.0.0.1 so you evaluate the local process, not a load balancer illusion. Keep timeouts short. Use failure thresholds to avoid removing capacity on a single blip. Consul's HTTP mapping is worth memorizing: 2xx is passing, 429 is warning, anything else is critical.

check {
  id       = "payments-tcp"
  name     = "TCP 8080"
  tcp      = "127.0.0.1:8080"
  interval = "10s"
  timeout  = "1s"
}

Design `/health` on purpose

Separate concerns before you wire Consul to them.

Endpoint	Purpose	Typical Consul use
`/health/live`	Process is up	Orchestrator restarts
`/health/ready`	Can accept traffic	Consul check target

Avoid marking every instance critical when a shared database hiccups unless evacuating everyone is truly safer than serving degraded. Mass critical status amplifies outages. Readiness should prove the instance can accept work: for example a cheap in-process slot acquire with a timeout that returns 503 when saturated. Liveness should answer a smaller question.

Other check types and when they earn their complexity

TTL checks let the application heartbeat Consul. Useful when only the app knows readiness. Missed heartbeat becomes critical. gRPC checks fit services that expose the standard health protocol. Alias checks mirror another service or node health for sidecars. Script checks are powerful and dangerous; prefer enable_local_script_checks over broadly enabling remote script checks.

You may attach several checks to one service. Keep the set small. Three flaky checks create a jittery pool that looks like network chaos and trains operators to ignore status changes.

Client discovery only becomes trustworthy after checks are honest

After checks tell the truth, clients can resolve Consul DNS with local caching, use health HTTP APIs with blocking queries, or use Connect when you need mTLS and intentions. DNS detail matters: by default warning statuses may still appear in DNS answers. Set dns_config.only_passing = true (or filter explicitly in the HTTP API) when only passing instances should receive traffic. I have seen teams "debug networking" for hours when the real bug was DNS still answering for warning.

Registration hygiene that keeps the catalog adult

Give each instance a unique id (payments-i-0abc). Tag for version or canary. Deregister on shutdown, or keep intervals short enough that dead boxes disappear. Enable maintenance mode before disruptive node work so discovery stops advertising without pretending the process crashed. Pair Consul readiness with orchestrator readiness gates during deploys so both systems tell the same story.

Closing

Consul discovery is only as trustworthy as your checks. Prefer native HTTP, TCP, or gRPC probes. Separate liveness from readiness. Configure DNS and API clients to honor the statuses you actually want. Healthy discovery is less about the catalog and more about refusing to advertise lies. The day I stopped pointing readiness at a decorative / endpoint was the day discovery started feeling like infrastructure again instead of theater.

Go Test Coverage Is a Smoke Alarm, Not a Quality Certificate

Davi Orlandi — Mon, 05 Oct 2026 14:37:43 +0000

I used to feel proud when a Go service crossed a high coverage number. Pull requests celebrated 87.3%. Gates refused merges below 80%. The bar looked meaningful. Then production taught me what the metric never promised: that executed lines are not the same as protected behavior.

The failure that stuck with me was not exotic. A repeated request with the same idempotency key created two payment attempts. The suite had touched the code. Coverage looked healthy. The business rule that mattered most had never been asserted. That is the personal stake behind this essay. Coverage can tell you which statements ran. It cannot tell you whether the tests understood the risk.

Deceptive green

Coverage tells you which statements ran. It does not tell you whether assertions were meaningful, whether races exist, or whether the API still matches the product.

Consider a tiny function with two independent conditions. One carefully chosen input can execute every line while leaving whole combinations of behavior untested. Statement coverage reports 100%. Path coverage would still be incomplete. Go's default tooling measures statements. That is useful. It is not a proof.

Worse: a test that calls a function and ignores the result still paints lines green. Happy-path suites that never touch err != nil branches look healthy until production finds the branch. So when someone asks for an "80% gate," ask a follow-up: 80% of what risk?

What coverage is good for

Coverage earns its keep as a flashlight. It finds untouched packages before a release. It spots dead error paths nobody exercises. It guides "what should I test next?" during a refactor.

go test ./... -coverprofile=cover.out
go tool cover -html=cover.out

Open the HTML report. Hunt red in money, auth, and data-loss code. Ignore vanity in main wiring and generated protobufs. The value is not the percentage at the top. The value is which dangerous lines never ran.

What coverage lies about

Assertion-free tests are theater: execution without checks. Happy-path bias is fragile: high coverage with zero failure cases. Concurrency is invisible: coverage does not prove race freedom; -race does. Integration reality still bites: mocks can give 100% while SQL breaks in staging.

I have seen projects with 95% coverage that still ship production bugs in the untested 5% of error handling. I have also seen quieter suites near 40% that felt more trustworthy because every tested line mattered.

Table-driven tests beat a percentage

If you copy-paste cases, you probably want a table. Tables amortize careful assertions and make gaps obvious.

func TestParseDuration(t *testing.T) {
    tests := []struct {
        name    string
        in      string
        want    time.Duration
        wantErr bool
    }{
        {"seconds", "30s", 30 * time.Second, false},
        {"invalid", "abc", 0, true},
        {"empty", "", 0, true},
        {"negative", "-1s", -time.Second, false},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := ParseDuration(tt.in)
            if tt.wantErr {
                if err == nil {
                    t.Fatalf("expected error for %q", tt.in)
                }
                return
            }
            if err != nil {
                t.Fatalf("unexpected err: %v", err)
            }
            if got != tt.want {
                t.Fatalf("got %v want %v", got, tt.want)
            }
        })
    }
}

Use t.Run so failures name the case. Keep error-path tables separate when assertion logic diverges. Capture loop variables correctly if you mark subtests parallel, and do not share mutable state across parallel cases.

A workflow without the cult

Write behavior tests first, edges included. Implement until they pass. Run coverage and only add tests for surprising red in risky code. Stop when residual red is glue or unreachable defense-in-depth. Chasing the last five percent often couples tests to implementation details. Those tests punish refactors without catching bugs.

Recommendations I actually follow

Identify critical packages. Business logic yes. Logger setup and server wiring usually no (cover them in integration). Aim high on the testable core, but do not worship 100%. Prefer risk conversations over global gates. Soft floors on business packages beat a blanket 95% rule that invents empty tests. Do not treat "coverage must never decrease" as sacred. Sometimes deleting bad tests is progress. Unit coverage is never enough: integration, contract tests, fuzzing, and -race catch classes of failure a percentage will not mention.

test:
  script:
    - go test ./... -race -count=1
    - go test ./... -coverprofile=cover.out -covermode=atomic
    - go tool cover -func=cover.out | tee coverage.txt

Fail builds for selected packages when coverage drops and the diff touches those packages. Blanket gates encourage people to delete hard-to-cover defenses or add hollow tests. Also treat flaky tests as defects. A suite that is green nine times out of ten trains the team to ignore red builds, which destroys more quality than a low number ever will.

Closing

Until critical code is covered, you definitely have untested risk. Once it is covered, you might still have untested risk. Treat coverage as a smoke alarm, not a certificate. Shine it on dangerous packages, invest in sharp table-driven cases, and keep race detection in CI. Good Go testing is not about making a report look impressive. It is about enough confidence that the important behaviors survive real traffic, repeated requests, and the strange timing problems that only appear after deploy.

Rate Limiting Is Not Back Pressure: Layering Protection in Go Services

Davi Orlandi — Mon, 05 Oct 2026 14:37:39 +0000

I used to treat rate limiting and back pressure as synonyms people swapped in design reviews for variety. Then an afternoon that should have been quiet melted a service I cared about, and the difference stopped being academic.

We had an ingestion API capped at 5,000 requests per second. That number came from an old benchmark with margin. A migration slowed the database from roughly 4ms writes to 90ms. The rate limiter kept admitting 5,000 rps because nothing about the database was visible to it. The internal queue between HTTP and the writer grew. Latency climbed from tens of milliseconds to tens of seconds. The pod died on memory. The rate limiter did its job. Its job was never this.

That story is why I write this essay. Rate limiting enforces a fixed ceiling chosen in advance. Back pressure is a signal travelling backwards from the component that is actually struggling. Load shedding is what you do when acceptance would make everything worse. The thing that defeats all three is an unbounded queue: it converts a fast rejection into unbounded latency and then a memory failure.

Two mechanisms, two failures

Rate limiting answers: is this caller allowed to send this much? The number comes from a contract, a tier, or last year's load test.

Back pressure answers: can this system absorb more right now? The answer moves when a dependency slows, a node disappears, or a noisy neighbor steals CPU.

The direction of the arrow is the whole distinction. Rate limiting pushes a constraint at the entrance. Back pressure pushes information upstream from wherever the bottleneck currently lives. You usually want both. Pretending one replaces the other is how you get green policy dashboards next to a dying process.

The unbounded queue is what makes overload fatal

jobs := make(chan Job) // unbounded in practice if you keep spawning senders

func Submit(j Job) error {
    select {
    case jobs <- j:
        return nil
    default:
        return ErrOverloaded // only works if the channel is buffered and full
    }
}

jobs = make(chan Job, 256) // capacity is an explicit decision

An unbounded buffer does not remove overload. It hides it until latency and memory become the outage. Export queue depth everywhere you have a queue. Depth usually moves before the error rate does. That single habit has saved me more times than any clever token-bucket tweak.

A practical layering order in Go

At the HTTP edge I want a boring sequence:

Identify the caller (limits need a key)
Rate limit per API key, IP, or tenant
Cap in-flight work with a semaphore or buffered channel
Run the handler with deadlines
Bound concurrency on outbound clients too

type Gate struct {
    lim   *rate.Limiter
    slots chan struct{}
}

func (g *Gate) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if !g.lim.Allow() {
            http.Error(w, "rate limit", http.StatusTooManyRequests)
            return
        }
        select {
        case g.slots <- struct{}{}:
            defer func() { <-g.slots }()
            next.ServeHTTP(w, r)
        default:
            w.Header().Set("Retry-After", "1")
            http.Error(w, "overloaded", http.StatusServiceUnavailable)
        }
    })
}

Use 429 for policy. Use 503 for overload. Clients should treat them differently: 429 means slow to the agreed rate; 503 means back off harder, with jitter, and consider opening a circuit. Collapsing both into one generic "retry later" response trains clients to stampede.

Load shedding is back pressure with a decision attached

Reject at the entrance before work starts. Prefer dropping low-regret traffic first: batch jobs, scrapers, expensive exports. Protect login and checkout longer. Check deadlines on queued work so you do not spend capacity on results nobody will read. Shedding is not cruelty. It is choosing which failures you can explain.

What I look for in reviews

Every queue should have a bound and a full policy. 429 and 503 should be intentional, not interchangeable. Shed rate should be on a dashboard, not only error rate. Retries should be budgeted at each layer. Clients should honor Retry-After. If those five lines are missing, the service is polite until it is catastrophic.

Closing

Rate limiting is a configured ceiling. Back pressure is a live capacity signal. One encodes what you believed last year. The other encodes what is true this minute. Bound every queue, fail fast when full, layer a token bucket in front of a concurrency gate, and teach clients to listen. That is not a research project. It is the difference between a graceful slow-down and a chain-reaction outage that starts with a number you once thought was safe.

Bloom Filters for Username Checks: The Case Study (and When to Walk Away)

Davi Orlandi — Mon, 05 Oct 2026 14:37:36 +0000

The signup form that taught me to care about Bloom filters was not glamorous. People typed. We checked. Most answers were "available." Indexed database lookups are cheap one at a time. They are not free when every keystroke across a growing product becomes a read against the authoritative store. At some point the question stops being "can the database answer?" and becomes "should the database be the first system we ask every time?"

A Bloom filter sits in front of that path as a fast pre-check. It does not replace the database. It does not replace a UNIQUE constraint. It answers one useful question quickly: is this username definitely not in the set? If the filter says absent, skip the read. If it says maybe, confirm with the source of truth.

The personal stake is trust. Get the semantics wrong and you block free names, open ticket storms, and teach users that your product lies about availability.

Why direct username checks get expensive

SELECT 1 FROM users WHERE username = $1 LIMIT 1;

Caches help for popular names. They help less for random new strings nobody has typed before. That is the awkward traffic mix of a signup box: mostly negatives, often unique, always latency-sensitive in the UI.

What the filter actually promises

Filter result	Meaning	Next step
Absent	Definitely not inserted	Treat as available for the read path
Present	Probably inserted	Confirm with the database
False positive	Present in filter, absent in DB	One extra lookup (acceptable)
False negative for inserted values	Should not happen if the filter was updated	Almost always means the filter is stale

False positives are the trade. For username checks they are cheap. False negatives for names you already inserted are not acceptable on this path, which is why the write path must keep the filter honest.

Building the availability check as a story, not a party trick

func (s *Signup) Available(ctx context.Context, username string) (bool, error) {
    u := normalize(username)

    maybe, err := s.bloom.Exists(ctx, u)
    if err != nil {
        return s.db.UsernameFree(ctx, u) // Redis down → DB, never invent availability
    }
    if !maybe {
        return true, nil
    }
    return s.db.UsernameFree(ctx, u)
}

On successful registration the sequence matters more than the data structure:

INSERT with a UNIQUE constraint (the real guardian)
BF.ADD the username, or emit an event a worker applies

Skip step 2 and the filter drifts. Drift raises false positives (extra database hits). It does not invent false negatives for names that were correctly added earlier, unless you never added them at all.

The bug that looks like flaky signup

if bloom.Exists(username) {
    return "already taken"  // wrong
}

A false positive now blocks a free name. Users open tickets. Logs show Bloom hits with no matching row. Trust evaporates. The rule I write in every review is blunt: a Bloom "present" is a hint, never a verdict. The insert's unique constraint still prevents races when two clients check the same free name at once.

Production considerations that decide whether this stays elegant

Keep the database as authority. The filter speeds reads. The database decides writes. Always.

Keep the filter synchronized. Update on every successful signup. Rebuild periodically from a snapshot into a new key (bf:usernames:v2), dual-write briefly, then flip readers.

Plan for deletes and renames. Classic Bloom filters do not delete cleanly. Counting Bloom or Cuckoo filters exist, but complexity jumps. If renames are common, budget rebuilds or pick another structure.

Size for tomorrow. Estimate cardinality 18 to 24 months out. Pick a target false-positive rate (around 1% is common for pre-checks). Alert when fill factor climbs. Undersizing quietly kills the optimization as the fallback rate rises.

Normalize once. Lowercase, trim, and apply the same Unicode normalization everywhere. A filter cannot fix inconsistent identity rules.

When you should walk away

Walk away when exact answers are the product and there is no cheap confirmation path. Walk away when deletes dominate and rebuilds are not operationally owned. Walk away when the set is small enough that a Redis SET or the database alone is fine. Walk away when nobody owns metrics, rebuilds, or cutovers. Walk away when a false positive is user-visible and expensive, such as checkout lockouts or access denials.

Closing

Use a Bloom filter as a performance shield in front of a unique constraint, never as the authority. For username checks, "filter fast, confirm with DB" is the whole architecture. If your case cannot tolerate that confirmation step, choose a different tool. The structure is clever. Cleverness is not the same as correctness under concurrency.

Watermill Pitfalls I Wish I Knew Before Shipping EDA in Go

Davi Orlandi — Mon, 05 Oct 2026 14:37:33 +0000

Watermill made event-driven Go feel almost as ergonomic as an HTTP router. That comfort is a gift. It is also how I talked myself into shipping consistency bugs that did not show up until a quiet Sunday night, when a DNS blip and a partial deploy collided.

I already wrote about getting started elsewhere. This essay is about the physics that remain after the boilerplate disappears. Dual writes. Ordering surprises inside handler groups. Duplicate delivery that everyone "knows about" until money is involved. Middleware that looks complete until one poison payload pins a consumer forever.

The personal stake is simple. Event-driven architecture does not fail loudly the way a 500 does. It fails by drifting: the database believes something happened, and the rest of the world never heard.

The outage that is not a bug

A pod eviction. A rebalance. A process stopped between two steps that both needed to happen. The program did not "have a bug" in the usual sense. The execution simply ended. Durable design accepts interruptions and recovers to a correct state anyway. Watermill will not invent that durability for you. It will make durable patterns easier to express once you decide they matter.

Publish inside the same transaction, or admit you did not

The classic race looks innocent.

Insert the order in Postgres
Publish OrderCreated
Crash between 1 and 2

The database believes the order exists. Downstream services never saw the fact. Support tickets arrive days later, and the on-call engineer stares at two systems that are both "correct" in isolation.

Watermill's Forwarder (outbox) pattern exists for this. Write domain state and the outbound message in one database transaction. A Forwarder process later moves outbox rows to Kafka, Redis Streams, or whatever broker you chose.

Command handler
  └─ BEGIN
       ├─ mutate domain tables
       └─ insert outbox row
     COMMIT
Forwarder
  └─ read outbox → publish → mark forwarded

If you skip the outbox, document the publish as best-effort and design compensations on purpose. Silent dual-write is how event-driven architecture earns a bad name inside a company that then refuses to try again.

Handler groups change the meaning of "this message"

By default, CQRS-style processors often create one subscriber per handler. That is fine when each topic carries one event type. When many event types share a topic and order matters, handler groups put those handlers behind one subscriber so the stream is processed sequentially.

The sharp edge caught me later than it should have. If handler A succeeds and handler B fails inside the same group, redelivery runs A again. So keep one handler per event type per group when you can, make every handler idempotent anyway, and treat AckOnUnknownEvent as a loaded gun. Silence is not the same as correctness.

Exactly-once is a wish; idempotency is a design

Most brokers Watermill wraps deliver at-least-once. Rebalances, retries, and partial failures will replay messages. Plan for it on day one, not after the first double charge.

Practical options that have held up for me:

Store message.UUID or a business key in a processed-events table with a unique index
Prefer naturally idempotent writes (UPSERT, conditional updates)
Use a short TTL cache only for soft dedupe, never for money

func (h *MarkPaid) Handle(ctx context.Context, e *OrderPaid) error {
    ok, err := h.dedupe.TryOnce(ctx, e.EventID)
    if err != nil {
        return err
    }
    if !ok {
        return nil
    }
    return h.orders.MarkPaid(ctx, e.OrderID)
}

Retries without a poison path are optional self-harm

Retry middleware is mandatory. Infinite retries without a dead-letter path are how one bad payload pins a consumer forever. Wire three layers: backoff retries for transient errors, poison or dead-letter after a capped budget, and a circuit breaker in front of fragile dependencies.

Separate handler bugs from dependency outages. A nil pointer should not share the same budget as a 503 from payments. Alert on dead-letter depth the moment the first message lands. A quiet DLQ is a forgotten one.

Request-reply is not your default hop

Watermill supports request-reply. Used everywhere, it reintroduces the coupling events were meant to remove. Prefer async facts for things that already happened, and plain RPC when you truly need an immediate answer. Keep request-reply for the rare case where a client is waiting and the command must be processed now.

Topics that mean everything age badly

One domain-events topic with forty payload types feels convenient in week one. By month three it becomes an ordering, ACL, and schema-evolution mess. Prefer one aggregate type or bounded context per topic family. Version payloads deliberately. Pass correlation and causation ids in metadata so a cascade is greppable when someone asks "what started this?"

Prove the hard parts

Before calling a service done, I want a short checklist that is not theater:

State and event publish are atomic (outbox) or explicitly best-effort
Handlers survive duplicate delivery
Retry plus dead-letter are configured and alerted
Ordering needs map to subscriber topology
Lag, error class, and DLQ depth are on a dashboard

A surprising number of "Watermill bugs" are schema bugs wearing a messaging costume. Add fields carefully. Keep consumers tolerant of unknowns. Contract-test critical events in CI.

Closing

Watermill removes boilerplate. It does not remove distributed-systems physics. Treat the outbox as default for anything money-adjacent, design for at-least-once, and be intentional about handler groups. The library will happily help you build a resilient backbone, or a very fast way to spread inconsistency. The difference is almost never the import path. It is whether you respected the gaps between steps.

Redis Queues in Practice: Lists, Streams, and When Each One Wins

Davi Orlandi — Mon, 05 Oct 2026 14:37:30 +0000

The first Redis queue I shipped looked almost too good to be true. We already had Redis for sessions. Someone pasted two commands into a design doc: LPUSH on the producer, BRPOP on the worker. Reviewers nodded. The first week felt like a small miracle. Jobs flowed. Dashboards stayed green. I remember telling a teammate that we had "solved" background work without introducing another broker.

Then a worker pod got OOM-killed mid-send. Redis had already removed the job from the list. The email never went out. Nobody noticed until a customer asked, days later, why the receipt never arrived. Over the next month we found a thin trail of vanished reconciliations: not catastrophic, just enough to make me distrust every green latency chart.

That is the personal stake behind this essay. Lists are wonderful and Lists are incomplete. Streams are more ceremony and Streams remember what you asked them to remember. Choosing between them is less about microbenchmarks and more about whether you can sleep when a pod dies at the wrong millisecond.

What BRPOP actually promises

BRPOP is honest about one thing: it removes the element and returns it in a single step. After that handoff, the job lives only in the worker's memory. If the process dies before the side effect finishes, Redis has already forgotten the work. That is at-most-once delivery. It is fine for warming a cache. It is the wrong contract for billing, outbound email, or anything a human will notice missing.

payload, err := rdb.BRPop(ctx, 5*time.Second, "jobs:email").Result()
if err != nil {
    return err
}
return sendEmail(payload[1]) // die here and the job is gone

I used to treat that snippet as "simple Redis." It is simple. It is also a silent hole in the floor.

Making Lists honest without leaving Redis

You can keep Lists and still recover from crashes. The pattern is familiar once you have lived through the first lost job: move each item atomically into a processing list, finish the side effect, then remove it. A reaper returns stale processing entries when a worker disappears.

moved, err := rdb.BLMove(ctx,
    "jobs:email", "jobs:email:processing",
    "RIGHT", "LEFT", 5*time.Second).Result()
if err != nil {
    return err
}
if err := sendEmail(moved); err != nil {
    return err // leave it for the reaper, or push back to ready
}
return rdb.LRem(ctx, "jobs:email:processing", 1, moved).Err()

This works. You now own heartbeats, per-worker keys, reaper timing, and awkward edge cases like identical payloads (LREM matches by value, so every job needs a unique id). For a single service with a moderate backlog and one worker pool, that trade can be rational. You stay on familiar commands. You accept that reliability is application code.

Streams as bookkeeping you stop reinventing

Streams change the story. XADD appends. A consumer group tracks deliveries in the Pending Entries List. XACK clears a pending entry. XAUTOCLAIM reassigns work that sat idle too long. The crash recovery you would otherwise write by hand lives closer to Redis itself.

streams, err := rdb.XReadGroup(ctx, &redis.XReadGroupArgs{
    Group:    "workers",
    Consumer: "worker-1",
    Streams:  []string{"jobs:email", ">"},
    Count:    10,
    Block:    5 * time.Second,
}).Result()

for _, msg := range streams[0].Messages {
    if err := handle(msg); err != nil {
        continue // no XACK; reclaim will retry
    }
    rdb.XAck(ctx, "jobs:email", "workers", msg.ID)
}

The production habits that matter are not exotic. Cap retries, then copy poison messages to a dead-letter stream. Treat delivery as at-least-once and make handlers tolerate duplicates. Trim with MAXLEN ~ so the stream cannot grow forever. Alert on PEL size and oldest pending idle time. Those are the difference between "we use Streams" and "we understand Streams."

The comparison that actually decides the rewrite

Aspect	List + BLMOVE + reaper	Stream + consumer group
Crash recovery	You build it	PEL + `XAUTOCLAIM`
In-flight visibility	Scan processing keys	`XPENDING`
Replay / audit	Gone after ack	Until trimmed
Multiple consumer groups	Awkward fan-out copies	Native
Ops complexity	Low until the reaper	Medium

Throughput for small payloads is usually similar. Redis's single-threaded command path dominates. The decision is correctness tooling, not microseconds. If two subsystems need the same message independently, Streams with separate groups win immediately. If a worker crash after receive is acceptable, Lists may still be enough. If Redis is already the shared critical path for everything in the company, consider whether messaging deserves a dedicated broker while Redis stays on cache and sessions.

The gotchas I keep writing down

Trimming unacked stream entries with MAXLEN follows position, not acknowledgement. Size the bound above your largest backlog. Ack after the durable side effect, never before. Prefer stable consumer names; pod names as consumer ids litter the group until someone cleans them up. And please do not use Pub/Sub as a job queue. Offline consumers lose messages. Live fan-out is a different problem.

Closing

I still reach for Lists when the queue is small, owned by one service, and the team understands the processing-list pattern. I reach for Streams when disappearance is unacceptable, when multiple groups need the same log, or when I am tired of reinventing the reaper. The painful lesson from that first lost receipt was not "Redis is bad at queues." It was that a queue without acknowledgement is a delayed apology waiting for the right crash.

How I Use SDD (Spec-Driven Development)

Davi Orlandi — Mon, 05 Oct 2026 13:17:04 +0000

If you follow tech the way I do, you've probably already felt lost with the flood of innovations launching every week since AI took off (or at least opened Twitter/LinkedIn and thought "okay, I became obsolete in 3 days"). Today I'll share a bit of my experience with one of them: Spec-Driven Development.

What is SDD?

SDD, or Spec-Driven Development, is a software development framework where the specification comes before the code. Instead of generating code unchecked, we define functional and technical specifications that guide development, serve as documentation and history, and help enrich the context LLMs use throughout the process.

There are many ways to use SDD. You can rely on ready-made setups like cc-sdd for Claude Code, or Spec Kit Command for Cursor, which already ship with ready-to-use commands. You can also build your own commands on top of these setups to fit your day-to-day workflow. It's common to have agents, skills, or commands specialized for each company's workflows — "How to deploy the backend", "Security acceptance criteria", and so on.

Workflow

SDD implementations vary by use case, but most go through these phases:

Functional Spec

This is where we describe requirements functionally. Use as little technical language as possible (yes, that's harder than it sounds).

You can start from an idea, a task from tools like Jira via MCP, or even a bug. Example:

Users complete onboarding but receive no follow-up. That reduces engagement and doesn't guide them through the next steps inside the platform.

Since this is a discovery moment, the AI starts asking questions:

AI: Which users should we implement this for?

You: All newly registered users who finished onboarding.

AI: Exactly when should the email be sent?

You: Immediately after confirming that onboarding completed successfully.

AI: What are the functional requirements?

You:

Detect the moment onboarding completes

Trigger the email only once per user

Personalize the email with basic data (name, etc.)

Implement retry if the email service fails

Log successes and errors

These refinements produce a Functional Spec — everything needed to describe the technical details of the implementation.

That document should also include clear acceptance criteria, which serve as the validation baseline throughout the flow.

The spec must be editable and have an approval mechanism. In almost every case, you'll iterate with the LLM until you land on something satisfactory.

This phase can be started with commands like:

/sdd.spec functional Envio de email de onboarding

Some setups use flags such as:

--clarify when something isn't clear
--approve when you consider the spec ready

Technical Spec

With the functional specification defined, translate the business requirements into technical details. You can start with:

/sdd.spec technical

Example:

AI: What technology stack will you use?

You: Node.js with Express for the service, integration with an email provider (e.g. SES or similar), and a queue (e.g. SQS or PubSub) for asynchronous processing.

AI: What API design approach?

You: Event-driven architecture. The trigger will be based on the user.onboarding.completed event, with asynchronous communication.

AI: Which services or platforms will be integrated?

You: An email service for sending, a messaging system for the queue, and possibly a template service. Also integration with the auth system to keep data consistent.

AI: What are the performance requirements?

You:
Event processing latency under 5 seconds
Ability to handle spikes without losing events
Failure rate under 1 percent with automatic retry

AI: How will reliability be ensured?

You:
Use a queue to decouple processing
Retry with exponential backoff
Dead-letter queue for unprocessed events
Idempotency to avoid duplicates

Just like in the functional phase, this step produces a technical document that should be reviewed and approved.

Don't let technical details rewrite the functional requirements — though in the real world, technology often ends up shaping business specs anyway.

Tasks

By now we've turned an idea into two clear things: what to do and how to do it. Next comes execution.

Translate the spec into clear, actionable tasks — exactly what the LLM or the developer should do, with no ambiguity. Start with:

/sdd.plan

The AI then generates something like:

AI: Here are the suggested tasks:

TASK-001: Implement consumer for the user.onboarding.completed event

TASK-002: Create email-sending service with provider integration

TASK-003: Implement idempotency logic to avoid duplicates

TASK-004: Create email template with personalization

TASK-005: Wire the full flow from event to send

TASK-006: Add logs and metrics

AUTO-TASK-001: Create unit tests

AUTO-TASK-002: Create integration tests

These tasks can be saved in files such as tasks.json or individually as TASK-001.md, containing:

Status such as wip, done, or canceled
Assignee
Dependencies
Possibility of parallelization

You can refine with:

/sdd.plan --refine

And then approve with:

/sdd.plan --approve

This phase matters because it turns the spec into something executable. There should be no ambiguity here — only clear tasks.

Implementation

With everything approved, enter the implementation phase:

/sdd.build

During this phase, the AI executes the tasks and continuously validates the acceptance criteria from the functional spec, keeping the implementation aligned with the plan.

Because the tasks are already well defined and decoupled, some tools let you parallelize executions that have no dependencies.

One example is Claude Agent Teams, which let you run multiple agents in parallel, each responsible for part of the system. Instead of a single AI doing everything sequentially, you can have:

One agent implementing services
Another writing tests
Another handling integration

All at the same time, respecting the dependencies defined in the tasks.

This works especially well with SDD because the tasks are already well scoped — you don't need to manually coordinate who does what; the structure of the spec enables that split.

Following the flow:

AI: Creating branch feature/email-onboarding

AI: Starting task execution.

AI: Running TASK-001: Event consumer

AI: Consumer created successfully. Want to validate with tests?

You: Yes.

AI: Tests ran successfully.

AI: Running TASK-002: Email-sending service

AI: Provider integration complete. Retry implemented.

AI: Tests passing.

This process continues until all tasks are done.

Finish

After implementation, wrap up the feature: make sure everything defined in the specs was delivered, validated, and is ready for production.

You can start with:

/sdd.finish

The AI then runs final validations:

AI: Checking task status...

AI: All tasks are complete.

AI: Validating tests...

AI: All tests are passing with adequate coverage.

AI: Validating consistency between specs and implementation...

AI: No divergences found.

AI: Do you want to finish the feature?

You: Yes.

At that point, a few things usually happen:

Mark the feature as complete
Ensure all specs are up to date
Consolidate documentation
Prepare for deploy or merge

Tips & tricks

Don't limit yourself to ready-made setups — you can integrate this flow with day-to-day tools using MCPs like Jira or Linear to generate specs from tasks, GitHub to manage issues, branches, and comments, or Playwright to test a generated frontend.

It's also common to have specialized agents for specific stages — code review, security validation, performance analysis. That makes the flow safer without adding manual complexity for the developer.

Conclusion

You're no longer deciding what to do while writing code. That was already settled in the earlier phases. In a world where LLMs take an active part in development, this shrinks scope, improves delivery quality, and makes the process far more reproducible.

In the end, it isn't about writing more code. It's about thinking better before you code (and letting the AI suffer a bit more in your place).

GO profiling using pprof

Davi Orlandi — Mon, 15 Dec 2025 02:07:42 +0000

Have you ever spent nights trying to understand why your application is using so many resources? Your CPU is on fire, memory keeps growing, latency goes up… and the code looks fine. Probably, you're guessing instead of verifying.

Here's how to verify memory leaks, unused resources, and poorly optimized code with Go's built-in profiling tool pprof.

What is pprof?

pprof is Go's built-in profiling tool for collecting and analyzing runtime data — CPU usage, memory allocations, goroutines, and blocking operations.

In simple terms, pprof answers questions like:

Why is my application slow?
Where is CPU time being spent?
What is allocating so much memory?
Are goroutines leaking?

Spoiler: pprof does not magically optimize your code. It just tells you where you messed up.

How pprof works

pprof works in two steps: collect metrics from your application, then analyze them with go tool pprof.

At runtime, Go samples execution and records metrics. These samples are aggregated into profiles that you can explore with pprof commands.

You might think this is a lot like traces, but under the hood Go does statistical profiling: your program is periodically interrupted and the runtime records what was running at that exact moment. Over time these snapshots form an accurate picture of resource use.

A simple way to enable profiling in your app is using an HTTP server:

This exposes profiling endpoints under /debug/pprof/, such as /debug/pprof/profile (CPU), /debug/pprof/heap (Memory), etc.

Collecting profiles

When you hit a pprof endpoint like /debug/pprof/profile, what you get back is not a report — it's a binary blob. If you try to open it in the browser, you'll download a file and see what looks like complete garbage.

That's expected: this endpoint returns a serialized pprof profile (a protobuf, usually gzip-compressed) with raw sampled data from the Go runtime — stack traces, counters, timestamps. Not charts. Not tables. Not answers. This binary mess is not meant for humans.

And that's where pprof comes in.

pprof takes this raw, unreadable data and decodes, aggregates, and correlates it into human-readable output.

Analyzing profiles

First, install the pprof CLI:

go install github.com/google/pprof@latest

You should see something like that:

With the web server running, collect a CPU profile (10 seconds):

go tool pprof http://localhost:8080/debug/pprof/profile?seconds=10

If everything worked and you waited 10 seconds, you get an interactive shell. This is where the raw profile data becomes actionable. Once inside pprof, you can run commands like top, list, web, etc. (check the options here)

The Big Bad Boy

Imagine we have an endpoint using a lot of CPU — the "Big Bad Boy." For study purposes, I'll use a /work endpoint.

With the app running, hit /work from another terminal to trigger some CPU load:

curl http://localhost:8080/work

You can repeat it a few times or use a load tool like hey or ab to generate more pressure.

Now collect a 10-second CPU profile from the running server:

go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10

Inside the pprof shell, show the top functions consuming CPU with top.

You'll see an output like:

(pprof) top 
Showing nodes accounting for 7470ms, 92.45% of 8080ms total
Dropped 2 nodes (cum <= 40.40ms)
Showing top 10 nodes out of 35
      flat  flat%   sum%        cum   cum%
    2030ms 25.12% 25.12%     2030ms 25.12%  math.archExp
    1570ms 19.43% 44.55%     1570ms 19.43%  math.IsInf (inline)
    1500ms 18.56% 63.12%     2830ms 35.02%  math.log
     560ms  6.93% 70.05%     5800ms 71.78%  math.pow
     430ms  5.32% 75.37%     1050ms 13.00%  math.sin
     330ms  4.08% 79.46%      330ms  4.08%  runtime.pthread_cond_signal
     320ms  3.96% 83.42%     1560ms 19.31%  math.frexp
     290ms  3.59% 87.00%      290ms  3.59%  math.Float64frombits (inline)
     220ms  2.72% 89.73%      220ms  2.72%  math.IsNaN (inline)
     220ms  2.72% 92.45%      230ms  2.85%  math.normalize (inline)

We can see a lot of math package operations, but we don't know where those operations are used. Run top again with the -cum (cumulative) flag:

(pprof) top -cum
Showing nodes accounting for 2170ms, 26.86% of 8080ms total
Dropped 2 nodes (cum <= 40.40ms)
Showing top 10 nodes out of 35
      flat  flat%   sum%        cum   cum%
     110ms  1.36%  1.36%     7750ms 95.92%  main.heavyComputation
         0     0%  1.36%     7750ms 95.92%  main.main.func1
         0     0%  1.36%     7750ms 95.92%  net/http.(*ServeMux).ServeHTTP
         0     0%  1.36%     7750ms 95.92%  net/http.(*conn).serve
         0     0%  1.36%     7750ms 95.92%  net/http.HandlerFunc.ServeHTTP
         0     0%  1.36%     7750ms 95.92%  net/http.serverHandler.ServeHTTP
         0     0%  8.29%     2830ms 35.02%  math.Log (inline)

Spotted! main.heavyComputation is consuming 95.92% of the total CPU — that is our "Big Bad Boy."

You can do the same for memory, block, mutex, and goroutine profiles

Memory (heap) – see allocations and leaks:

go tool pprof http://localhost:6060/debug/pprof/heap

Goroutines – detect leaks or deadlocks:

go tool pprof http://localhost:6060/debug/pprof/goroutine

Block – see time spent waiting on channels, mutexes, etc.:

go tool pprof http://localhost:6060/debug/pprof/block

Mutex – see contention hotspots:

go tool pprof http://localhost:6060/debug/pprof/mutex

All of these can be analyzed the same way (top, list, web, svg). The web and svg commands produce graphical visualizations (requires Graphviz), making it much easier to spot hotspots.

Visualization (Graphviz required)

Graphical visualizations make it easier to spot CPU or memory hotspots quickly. Install Graphviz first:

web: opens a call graph in your browser
svg: outputs an SVG call graph
pdf: outputs a PDF graph

Don't spray and pray

pprof has multiple profile types because performance problems love to hide in different places. Each type answers a different question:

CPU – where time is spent
Heap – memory usage and leaks
Goroutines – leaks or deadlocks
Block – wait times
Mutex – contention

Always choose the profile that matches the problem.

ADDITIONAL: Profiling in Kubernetes

If your app runs in a Kubernetes cluster, port-forward the pprof port from your pod:

kubectl port-forward deploy/my-app 6060:6060

Access pprof locally:

go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10

Analyze interactively as usual (top, list).

Useful Links & References

Go pprof docs: https://pkg.go.dev/net/http/pprof
Runtime profiling: https://pkg.go.dev/runtime/pprof
go tool pprof guide: https://go.dev/doc/diagnostics#profiling
Official Go blog post about pprof: https://go.dev/blog/pprof

So, Thanks!

If this article saved you even one late night of guessing and blaming the garbage collector, it already did its job 😄. Thanks for reading!

See you soon ;)

Getting Started With Linux

Davi Orlandi — Sun, 14 Dec 2025 22:36:44 +0000

This article is a study-oriented, introductory overview of Linux. It covers basic concepts and simplifies some topics to help beginners build an initial mental model — a starting point, not an exhaustive reference.

Base needed knowledge:

GNU: GNU is a predecessor of Linux and a free open-source Unix-like operating system.

Kernel: The kernel is the core of an operating system. It acts as a bridge between software and hardware, managing system resources (CPU, memory, peripheral devices). Although people use "Linux" to describe the whole operating system, Linux itself refers only to the kernel.

What is Linux?

Linux is an open-source operating system kernel originally created by Linus Torvalds. In practice, when people say "Linux," they usually mean a complete operating system: the Linux kernel combined with tools, libraries, and other software from the GNU project.

A Linux system is divided into three layers:

Hardware: The physical resources of your machine — CPU, memory, peripheral devices, etc.

Linux Kernel: The core of the operating system. It manages the hardware and facilitates communication between software and hardware.

User Space: The environment where users interact with the system, using applications and command-line interfaces.

What is a Linux distribution?

A distribution is a bundle of the Linux kernel with specific software, tools, system utilities, libraries, and applications. Essentially, a distro is a complete, ready-to-use operating system built around the Linux kernel.

Debian:

Debian is an operating system composed entirely of free and open-source software, and one of the most respected projects in the community.

Package Management

Debian uses a powerful package management tool called apt (Advanced Package Tool). The system maintains a massive repository of pre-compiled software packages.

Red Hat Enterprise Linux (RHEL)

RHEL is a commercial Linux distribution developed by Red Hat, built to provide long-term stability, security, and professional support.

Package Management

RHEL uses the RPM (Red Hat Package Manager) format for its software packages. For managing those packages, it provides package managers like YUM (Yellowdog Updater, Modifier) and its successor, DNF (Dandified YUM).

Ubuntu

Ubuntu is probably the most famous Linux distribution — an excellent entry point for anyone looking to get started with Linux.

Package Management

As a Debian-based operating system, Ubuntu uses the core Debian package management system. That means it uses the apt (Advanced Package Tool) command-line utility to handle software installation, updates, and removal, giving users access to a vast repository of free and open-source software.

Fedora

Fedora is roughly Ubuntu's counterpart from the Red Hat side — built on Red Hat's foundation instead of Debian.

Package Management

Fedora uses the RPM package format and manages software with the DNF (Dandified YUM) package manager. DNF is a command-line tool for installing, updating, and removing software packages.

The shell

The shell is a program that accepts your typed commands and passes them to the operating system. If you've used a GUI (Graphical User Interface), you might have encountered applications like "Terminal" or "Console" — those are simply programs that open a shell session for you.

BASH (Bourne Again Shell)

Bash is the default shell for most Linux distros. While other shells like ksh, zsh, and tcsh exist, mastering Bash provides a solid foundation for working with any Linux system.

When you open a terminal, you'll see the shell prompt. Its appearance can vary between distros, but it typically follows this format: username@hostname:current_directory$.

Yeah, I used a MacOS Terminal screenshot — don't care, it's not relevant.

The $ symbol at the end indicates that the shell is ready to accept commands. You do not type this symbol when entering commands — it is purely informational!

How the hell does this work?
Just paste this command echo "I love Linux" and you'll see "I love Linux" as the output in the console.

Filesystem basics

Linux uses a single root filesystem, meaning everything starts from / (root). There are no drive letters like C: or D: — all storage devices are mounted into the same tree.

Common directories

/ — root of the filesystem
/home — user home directories
/etc — system configuration files
/var — variable data (logs, cache, spool)
/usr — user-installed software and libraries
/bin and /sbin — essential system binaries

In Linux, everything is treated as a file, including devices, processes, and sockets.

Paths

A path is the location of a file or directory inside the filesystem. It tells the system where something is in the directory tree.

Absolute paths start from /, like /home/user/projects. Relative paths omit the leading slash, like projects/my-app.

Useful navigation commands:

pwd   # show current directory
ls    # list files
cd    # change directory

Permissions & users

Linux is a multi-user operating system, built with security in mind from the start. Every file and directory has an owner, a group, and a set of permissions.

You can see permissions on your computer with ls -l:

Root is the superuser, with full access. Normal users have limited permissions. You can run commands as root by prefixing them with sudo.

Permissions are a core concept in Linux and one of the main reasons servers are secure by default.

Networking basics

Linux provides built-in tools to inspect, debug, and interact with networks. Networking is a fundamental skill, especially for servers, containers, and cloud environments.

Network concepts

IP address: identifies a machine on a network
Ports: identify services running on a machine
Protocols: rules for communication (HTTP, TCP, UDP)

Common networking commands:

ping "url.com"

curl "url.com"

wget "url.com/file.zip"

ip a

Useful links & references

GNU project: https://www.gnu.org
Linux Kernel documentation: https://www.kernel.org/doc/html/latest/
Filesystem Hierarchy Standard (FHS): https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
Debian official docs: https://www.debian.org/doc/
APT documentation: https://wiki.debian.org/Apt
Red Hat Enterprise Linux docs: https://access.redhat.com/documentation
DNF documentation: https://dnf.readthedocs.io/en/latest/
Ubuntu documentation: https://help.ubuntu.com/
Fedora documentation: https://docs.fedoraproject.org/
Bash manual: https://www.gnu.org/software/bash/manual/
Linux permissions reference: https://www.redhat.com/sysadmin/linux-file-permissions
Linux networking overview: https://www.kernel.org/doc/html/latest/networking/index.html

Thanks!

Thanks for reading. I hope it clarified the core concepts behind Linux and gave you a starter foundation to keep exploring.

DEV Community: Davi Orlandi

Atlas Online Archive for Large Collections: Keep Hot Data Hot

How it works in practice

Good candidates versus poor ones

Designing the rule without painting yourself into a corner

Partition fields decide archive query cost

Application patterns that keep history honest

What Online Archive is not

Cost sanity check

Rollout checklist and common pitfalls

Closing

Walking Hierarchies with MongoDB $graphLookup (Without Melting Memory)

How $graphLookup behaves when you respect it

A minimal hierarchy that makes the direction obvious

Guardrails that would have saved that admin screen

When not to use it

A debugging recipe I trust more than optimism

Closing

Lessons I Still Use from MongoDB in Action (Without Rewriting the Book)

Rule 1: Model for queries, not for your ER diagram

Rule 2: Atomicity lives at the document boundary

Rule 3: Indexes are part of the schema

Rule 4: Aggregation is a product feature

Rule 5: Favor embedding until a compelling reason appears

Rule 6: Flexible schema is not "no schema"

Patterns that still surprise teammates

What I leave to the book

Closing

Consul Service Discovery That Does Not Lie: Health Checks First

Registration is a readiness story

Prefer HTTP and TCP checks over shell folklore

Design /health on purpose

Other check types and when they earn their complexity

Client discovery only becomes trustworthy after checks are honest

Registration hygiene that keeps the catalog adult

Closing

Go Test Coverage Is a Smoke Alarm, Not a Quality Certificate

Deceptive green

What coverage is good for

What coverage lies about

Table-driven tests beat a percentage

A workflow without the cult

Recommendations I actually follow

Closing

Rate Limiting Is Not Back Pressure: Layering Protection in Go Services

Two mechanisms, two failures

The unbounded queue is what makes overload fatal

A practical layering order in Go

Load shedding is back pressure with a decision attached

What I look for in reviews

Closing

Bloom Filters for Username Checks: The Case Study (and When to Walk Away)

Why direct username checks get expensive

What the filter actually promises

Building the availability check as a story, not a party trick

The bug that looks like flaky signup

Production considerations that decide whether this stays elegant

When you should walk away

Closing

Watermill Pitfalls I Wish I Knew Before Shipping EDA in Go

The outage that is not a bug

Publish inside the same transaction, or admit you did not

Handler groups change the meaning of "this message"

Exactly-once is a wish; idempotency is a design

Retries without a poison path are optional self-harm

Request-reply is not your default hop

Topics that mean everything age badly

Prove the hard parts

Closing

Redis Queues in Practice: Lists, Streams, and When Each One Wins

What BRPOP actually promises

Making Lists honest without leaving Redis

Streams as bookkeeping you stop reinventing

The comparison that actually decides the rewrite

The gotchas I keep writing down

Closing

How I Use SDD (Spec-Driven Development)

What is SDD?

Workflow

Functional Spec

How `$graphLookup` behaves when you respect it

Design `/health` on purpose