Incident naming conventions for services, queues, and DBs

Why names break incident response

Incidents compress time. People skim dashboards, logs, alerts, and chat threads while part of the system is already down. If names are vague, every lookup takes longer than it should.

A service called "core", a queue called "main", or a database called "prod2" tells almost nobody what it owns, what it touches, or whether it matters to the problem. During an outage, that missing context turns a two-minute check into 20 minutes of guessing.

Similar names cause a different kind of damage. They create false confidence. Someone sees order-api in an alert and opens orders-api because the names look close enough under stress. Another person restarts billing-worker when the broken process is actually billing-writer. The team moves fast, but in the wrong direction.

Internal nicknames make things worse. A small team may know that octopus means the customer sync service or that red-db means the reporting database. New hires do not know that. On-call engineers from another team do not know that. Even people who once knew often forget at 3:17 a.m. when five alerts fire at once.

Readable names lower the mental load. customer-sync-service says more than octopus. checkout-payment-events says more than events-main. billing-prod-us is easier to trust than db3 because people can tell what it is before they open another tab.

When systems fail, nobody wants clever names. They want names that are boring, obvious, and hard to misread. A good name answers two questions at once: what this thing does, and where someone should look next.

What good names look like

Good names answer two questions fast: what kind of thing is this, and what job does it do? When alerts start stacking up, nobody should stop and guess whether worker-final is a service, a queue, or a database. svc-payments-auth is much clearer.

A simple pattern helps. Put the system type first, then the business purpose. That makes logs, dashboards, and chat messages easier to scan. If every name follows the same shape, people do less decoding when they are already under pressure.

Mixed styles create small delays that add up. A screen full of names like payments-api, db_users, queue-email-send, and finalizer forces people to interpret each one from scratch. That is wasted effort.

Short, plain patterns usually work best:

• service: svc-order-checkout
• queue: q-order-confirmation
• database: db-customer-billing
• cache: cache-session-auth

These names are plain, and that is the point. Keep them short enough to read in one glance. Most teams do well with two to four parts. If a name turns into a sentence, people will shorten it in chat, and confusion starts again.

Use words that make sense outside one team. Skip inside jokes, project nicknames, and clever code names. q-phoenix may sound memorable to the team that built it, but it tells nobody else what broke. q-refund-events tells the on-call engineer far more.

Shorthand causes trouble when only part of the company understands it. If you shorten a word, use terms most engineers already know, such as auth or api, and keep them consistent. A new teammate should not need a translation layer to understand a name.

If someone can look at a name and tell the type and purpose in two seconds, it is probably good enough.

How to build a naming standard

Start small. A naming standard fails when it tries to handle every edge case on day one. You need a rule people can remember during a noisy incident, not a long document nobody reads.

Begin with a short list of system types. Keep it plain: service, queue, database, worker, cron job, cache, topic. If a new thing does not fit one of those buckets, stop and decide where it belongs before naming it.

Then choose one name order and keep it the same everywhere. A pattern like environment-domain-function-type often works because people can scan it quickly. Write the pattern down with a few real examples, such as prod-billing-api-service or staging-orders-retry-queue.

Abbreviations need rules too. This is where teams drift. One person writes svc, another writes service, and a third uses api for anything with an endpoint. Keep a short allowed list and reject the rest. If an abbreviation is not obvious to a new engineer, do not use it.

A practical rollout is simple. First, export your current names from dashboards, logs, cloud consoles, and repositories. Then mark the ones that cause the most confusion, especially names that hide the environment or business area. After that, define one template for each system type, agree on allowed abbreviations, and rename in batches.

Do not rename everything at once. That creates fresh confusion, breaks scripts, and gives the team two problems instead of one. Change the worst names first, update alerts and runbooks at the same time, then move to the next batch.

A small team can clean up a surprising amount in a week if the rules stay simple and strict.

How to name services

When an alert fires, people do not read service names for style. They read them to decide who should respond and what might break next.

A service name should answer two questions at a glance: who owns it, and what it does. billing-payments-api is clearer than core-service because the owner and purpose are both visible. In a small company, the owner can be a business domain. In a larger one, it may need to be a team name.

One pattern that works well is owner-purpose-type-env. Names like billing-payments-api-prod, growth-email-worker-staging, and identity-session-service-dev are not elegant, but they are easy to read in alerts.

Make public and internal services obvious. During an incident, teams need to know whether customers see the failure or whether it only affects staff tools and background jobs. checkout-public-api-prod tells a very different story from checkout-internal-pricing-prod. The first is customer-facing. The second may still matter, but it usually has a different blast radius and a different response order.

Pick one set of labels, such as public and internal, and reuse them everywhere. Do not mix external, frontend, edge, and public for roughly the same idea.

Environment tags also need a fixed place. Put them in one spot, usually at the end. Then names sort more cleanly, filters work better, and searches are less error-prone. Do not mix prod-checkout-api, checkout-api-production, and checkout-api-prod.

Version numbers usually do not belong in service names. Deploy history and release tooling already track versions better. Keep a version in the name only when operations depend on it, such as when search-api-v1 and search-api-v2 run side by side and route traffic differently.

If a tired engineer can read the name and know the owner, purpose, exposure, and environment, the name is doing its job.

How to name queues

A queue name should tell you what work is waiting and where it should go. During an outage, names like jobs, events, or worker_main slow people down because nobody can tell what is stuck or how risky the delay is.

Name the queue after the thing entering it. invoice.pdf.generate is clearer than billing_async. user.signup.email is clearer than notifications_v2. When backlog grows, the object in the queue matters more than an internal team label.

Direction helps when the same data moves both ways. orders.created.to_erp tells you the app is sending order data out. orders.updated.from_erp tells you it is receiving updates back. Use direction only when it removes doubt. If there is only one path, extra words just make the name harder to scan.

Dead letter queues need blunt names. Do not hide them behind shortcuts like orders-fail or misc_errors. orders.created.dlq leaves no room for guessing. Retry queues should be just as direct: orders.created.retry.5m or invoice.pdf.generate.retry.1m tells the team both the job and the retry timing.

Urgency belongs in the name only when it changes who should wake up or how fast people need to act. If a delayed job can block revenue, say so. payment.capture.urgent is more useful than a normal-looking queue name that hides business impact. But do not stamp everything as urgent. Once every queue looks urgent, the label means nothing.

A good queue pattern usually includes the subject or event, the action, optional direction, and optional queue type such as retry or dlq. Add urgency only when it changes response.

This matters sooner than most teams expect. A small AI or SaaS product can collect dozens of background jobs within a few months. If names stay plain and consistent, on-call engineers can spot the bad queue in seconds instead of tracing producers and asking who owns async-v3.

How to name databases

When a database alert fires, the name should answer basic questions in one glance: what product area it belongs to, which environment it runs in, where it lives, and whether it handles writes or reads. If people need to open a wiki or ask in chat, the name has already failed.

A simple pattern works well: product-area-env-region-role-shard. You do not need every part every time, but the order should stay fixed. Consistency matters more than perfect wording.

Names like billing-prod-us-east-primary or accounts-prod-eu-west-replica are plain, but plain is good during stress. Compare them with main-db, newcluster2, or appmaster_old. Those names force people to guess, and guessing costs time.

Read replicas need the clearest label of all. Put replica or read in the name every time, and keep the write node marked as primary or writer. Do not rely on team memory like "everyone knows db-02 is read only." During an incident, someone new or half-awake may be the person looking.

Production and test should never look similar. Use full environment labels such as prod, staging, test, and dev. Avoid mixed forms like production, prd, and live across different systems. Pick one form and stick with it.

Database names should match the real product area, not an old internal project name that survived three rewrites. If the database stores customer billing data, call it billing, not phoenix, temp-core, or legacy-v2.

Region and shard labels need one format too. Choose eu-west, us-east, shard-01, shard-02, and use that style everywhere. If one team uses euw1 and another uses eu-west-1, search results and dashboards get messy fast.

In most cases, a good database name includes the product area, the environment, the region if location matters, the role, and the shard number if data is split.

Mistakes that waste time

The most common naming problems are boring. That is why they survive for so long.

The first problem is inconsistent vocabulary. One team says "customer", another says "user", and a third says "account" for the same flow. Alerts, logs, and runbooks stop lining up. Search gets noisy, and new engineers start guessing.

The second problem is too much compression. A name like svc-pymt-prd-eu2-v04-core may make sense to the person who created it. At 2 a.m., everyone else has to decode abbreviations before they can act. Put the plain business meaning first. Add environment or region only if people really need it in the name.

The third problem is format drift. If one team uses payments-api-prod, another uses prod.payments.api, and a third uses PaymentsAPI, people miss alerts and type the wrong search terms. A naming rule works only if teams keep the same order and separator.

Temporary names are another trap. Projects often begin with new-db, queue-test, or service-v2. Then the label sticks around for years. After a while, nobody remembers what new or v2 was supposed to mean.

Renames create their own mess when teams update the code but forget everything around it. Old alert titles, runbooks, dashboards, and on-call notes keep the old name alive. During an incident, responders waste time translating between old and new labels.

A small example shows how this happens. The service changes from orders-worker to fulfillment-worker. The queue still says orders-events. The runbook still says "check order-consumer lag." Nothing is broken by itself, but every responder loses time matching names across tools.

The fix is straightforward: pick one word for each concept, keep the format simple, remove temporary names early, and treat renames as a full change across code, alerts, dashboards, and documents.

A simple incident example

Peak traffic hits at 8:05 p.m. after a promo email goes out. Orders keep coming in, but customers stop getting payment confirmations. Support starts getting "charged, but still pending" complaints within minutes.

The on-call team opens the dashboards and sees one queue climbing fast: jobs-main. That name tells them almost nothing. Is it email? Fraud checks? Payment capture? Receipt generation? Three people start tracing different workers because the queue name hides the failing step.

At the same time, someone checks the database layer and sees two hosts: payments-db and payments-db-1. Under pressure, that looks close enough to primary and backup, so an engineer loses several minutes checking the wrong node first. payments-db-1 is only a read replica, but the name does not say that clearly.

Those first 15 minutes matter. People are still building a picture of the problem, and bad names slow every decision. Instead of asking "what failed?" the team asks "what is this thing?"

The fix turns out to be simple. A worker that moves approved payments into settlement cannot keep up with traffic. If the queue had been named payments-settlement-write or checkout-payment-settlement, the team would have looked in the right place first. If the databases had been named payments-primary and payments-replica-read, nobody would have treated the replica like a write target.

After the incident, the team writes a short standard. Service names must include the business function. Queue names must include the exact step. Database names must say primary or replica in plain words. Read-only nodes must include read or replica every time. Temporary and legacy names cannot stay in production.

The next time payment delays show up, the first screen already points to the failing path. The team spends those opening minutes fixing the issue, not decoding names.

A quick naming checklist

Before you approve a new service, queue, or database name, run a quick check:

• A new teammate can guess what it does in a few seconds.
• The environment appears in the same place every time.
• Every name follows one order and one separator style.
• Alerts, logs, and dashboards use the same label.
• People can say the name out loud without spelling it.

A spoken test helps more than people expect. Read the name during a call and ask someone else to repeat it. If they ask, "Was that pay or payment?" or "Did you mean prod or preprod?" the name needs work.

It also helps to check for near-duplicates. Names like user-db, users-db, and user-data-db look different when you create them, but they blur together during an outage. Pick one pattern and stay with it.

Teams often skip this review because each name looks fine on its own. The trouble starts when ten services, four queues, and three databases appear in alerts at once.

What to do next

Start with the systems that wake people up. If a service, queue, or database can trigger a night alert, rename that first. You do not need a company-wide cleanup before you get results. Fix the names around the pages, and the next incident usually gets easier.

Write the rules on one short page. Define the parts every name must include, list the few abbreviations people may use, show how to mark environment, region, and owner, and note which old names need replacement first. If the guide needs a long meeting, it is too long.

Then use your next incident retro to test the rules. Look for the moments where people lost time because a name was vague, duplicated, or outdated. Turn each of those moments into either a small rule change or a rename task. That usually works better than trying to redesign every name in one big project.

Naming arguments are common, and they get old quickly. One group wants shorter names. Another wants every detail in the label. Someone else wants to keep legacy names because changing dashboards is annoying. A clear owner has to make the call and keep the standard consistent.

If that keeps turning into a recurring problem, outside technical leadership can help. Oleg Sotnikov at oleg.is works with startups and smaller teams on practical software and infrastructure decisions, and this kind of operational cleanup often needs that same steady hand.

A short naming document, a cleanup list, and one or two weeks of steady fixes are often enough to remove a lot of incident noise.