InfluxData Blog

Ideas you will meet

Databases

Schemas, indexes, query plans and choosing a store.

Observability

Metrics, logs, traces, SLOs and alerting.

What we already know about this

Our own lessons on these ideas. Read them here before you start, so it makes sense.

• System Design Foundations · 9 minObservability and running a systemMetrics, logs and traces, how to define 'healthy' with SLOs, and how to ship changes without breaking things.Read hereClose

  You cannot fix what you cannot see

  A system you cannot observe is a system you cannot trust. Observability is the ability to understand what is happening inside from the outside. Three kinds of signal work together.

  Signal	What it is	Best for
  Metrics	Numbers over time (requests per second, error rate, CPU)	Dashboards, alerts, trends
  Logs	Timestamped records of events	Details of what happened
  Traces	The path of one request through many services	Finding where time is spent

  100%

  Figure SDA-FND-11-1 · From alert to root cause · © forcsguy.com

  What to measure

  A simple checklist, the four golden signals:

  1. Latency: how long requests take (use percentiles).
  2. Traffic: how much demand there is.
  3. Errors: how many requests fail.
  4. Saturation: how full the busiest resource is (CPU, memory, connections, disk, queue depth).

  Averages hide pain. If the average is 100 ms but p99 is 4 seconds, one user in a hundred is waiting four seconds, and with many requests per page that is most of your users sometimes.

  Defining healthy: SLIs, SLOs, error budgets

  • An SLI (indicator) is a measurement, like "fraction of requests answered successfully in under 300 ms".
  • An SLO (objective) is the target, like "99.9% over 30 days".
  • The error budget is what is left over: 0.1% of requests may fail. While there is budget, ship features; when it runs out, focus on reliability.

  Alert on symptoms users feel (error rate, latency) more than on causes (one machine's CPU). Page a human only for things that need action now.

  Ship changes safely

  Most outages come from changes. Reduce the risk:

  • Small, frequent releases are easier to understand and undo than big ones.
  • Canary release: send a few percent of traffic to the new version and watch the metrics before going wider.
  • Feature flags: deploy code turned off, then enable it gradually, and switch it off instantly if needed.
  • Blue-green: keep the old version running so you can switch back in seconds.
  • Backwards-compatible changes: database and API changes should work with both old and new code during rollout.
  • Fast rollback must be a rehearsed, boring button.

  When things go wrong

  Have an incident process: someone leads, someone communicates, mitigate first and investigate later. Afterwards write a blameless postmortem that asks "how did our system and process allow this?" rather than "who did this?". That is how reliability actually improves.

  A worked example: error budgets and burn rate

  Your service has an SLO of 99.9% of requests succeed over 30 days, and it serves 10 million requests a month.

  • Error budget: 0.1% of 10,000,000 = 10,000 failed requests may happen in the month before you break the promise.
  • Burn rate is how fast you spend it. A burn rate of 1 uses exactly the budget over 30 days. If 5% of requests are failing now, the error rate is 50 times the allowed 0.1%, a burn rate of 50: the whole month's budget is gone in 30 / 50 = 0.6 days, about 14 hours.
  • Alert on burn rate, not on a single bad minute. A common pattern watches two windows together: page someone if the burn rate over the last hour is above about 14 and the last 5 minutes agree (a fast burn: 2% of the monthly budget gone in an hour). Open a ticket for a slower burn, say rate above 6 over 6 hours. Two windows avoid paging for blips and avoid missing slow leaks.

  Why this beats "alert when error rate is above X": it ties alerts to what users were promised, it pages only when the budget is in danger, and it gives the team a rule for trade-offs: when the budget is healthy, ship faster; when it is nearly spent, slow down and fix reliability.

  100%

  Figure SDA-FND-11-2 · Alerting on how fast the error budget burns · © forcsguy.com

  Finding the cause with all three signals

  A worked investigation shows why you want metrics, traces and logs together.

  1. A metric alerts: the checkout success rate dropped and p99 latency rose. Metrics tell you that something is wrong and how bad, cheaply and over time.
  2. Narrow it down by dimension: break the metric down by region, version and endpoint. Only the new version in one region is affected, a strong hint it is a deploy.
  3. A trace shows where the time goes: one slow checkout request shows 4.8 of its 5 seconds in a call to the payment provider's tokenisation endpoint.
  4. Logs give the detail: filter logs by the trace id from that request and read the exact error: a timeout talking to a new tokenisation URL.
  5. Fix and verify: roll back the version, and watch the metric recover.

  100%

  Figure SDA-FND-11-3 · From an alert to a root cause · © forcsguy.com

  The glue is a correlation id (trace id) carried on every request and written into every log line, so you can jump from one signal to the others.

  Mistakes people make

  • Alerting on causes instead of symptoms. "CPU is 85%" may be fine; "users are seeing errors" never is. Page on symptoms users feel, and use cause metrics for diagnosis.
  • Averaging percentiles. The mean of two hosts' p99 is meaningless; merge distributions instead (see the t-digest lesson).
  • High-cardinality labels. A label such as user_id on a metric creates a new time series per user, which can multiply storage and cost by millions. Put such detail in logs or traces.
  • Logs without structure or ids. Free text is hard to query. Log JSON with a trace id, service and version.
  • Dashboards no one owns. A wall of graphs nobody reads is noise. Build a small dashboard per service around the golden signals: latency, traffic, errors and saturation.
  • No runbook. An alert that does not say what to check first wastes the first ten minutes of every incident.

  Try it yourself

  Run any test in the System Builder and read its charts as if they were production graphs: which signal moves first, and which part would you look at next? Build the search metrics lab to practise percentile maths, and read the t-digest lesson for how real systems summarise latency at scale.

  Real-world reading

  Related reading

  • The Site Reliability WorkbookGoogle SRE team · O'Reilly / GoogleBooks
  • Feature Toggles (aka Feature Flags)Pete Hodgson · Martin FowlerBlogs
  • InfluxData BlogInfluxData engineers · InfluxDataBlogs
  • MetricsDB: TimeSeries Database for storing metrics at TwitterTwitter engineers · TwitterCase Studies

  Show 6 moreShow fewer

  • The Architecture Twitter Uses to Deal with 150M Active Users, 300K QPS, a 22 MB/S Firehose, and Send Tweets in Under 5 SecondsHigh Scalability engineers · High ScalabilityCase Studies
  • Steady State: Always Put Logs on Separate DiskMicrosoft engineers · MicrosoftCase Studies
  • XCMetrics: All-in-One Tool for Tracking Xcode Build Metrics at SpotifySpotify engineers · SpotifyCase Studies
  • Honeycomb BlogHoneycomb engineers · HoneycombBlogs
  • BookKeeper: Distributed Log Storage at YahooYahoo engineers · YahooCase Studies
  • Analyzing V8 Garbage Collection Logs at AlibabaAlibaba engineers · AlibabaCase Studies

  Open this lesson with its quiz and exercise

• Software Design Essentials · 11 minClean and hexagonal architectureKeep business rules independent of frameworks, databases and the web: the dependency rule, layers, and ports and adapters.Read hereClose

  The problem

  In many applications, business rules are tangled with framework code, SQL and HTTP details. Then:

  • You cannot test a rule without a database and a web server.
  • Changing a framework or database means rewriting business logic.
  • The code is organised around technology, not around what the system does.

  Several architectures (hexagonal, onion, clean) solve this with the same idea: put business rules at the centre and keep details at the edges.

  The dependency rule

  100%

  Figure SDA-SDE-06-1 · Clean architecture: dependencies point inwards · © forcsguy.com

  Source code dependencies point inwards only. Entities know nothing about use cases; use cases know nothing about the web or the database. Outer layers depend on inner ones, never the reverse.

  Layer	Contains	Knows about
  Entities	Core business objects and rules that would exist whatever the technology	Nothing else
  Use cases	Application-specific actions ("place order", "cancel subscription") that coordinate entities	Entities and the ports they define
  Interface adapters	Controllers, presenters, repositories' implementations, mappers	Use cases
  Frameworks and drivers	The web framework, database, message queue, UI	Adapters

  Before: logic tangled in the controller

  100%

  After: business rules in the middle

  100%

  What changed

  • Business rules can be tested without a web server or database
  • The database or framework can be replaced at the edge
  • There are more files and layers to maintain

  Ports and adapters (hexagonal)

  The application is the hexagon. It talks to the outside only through ports: interfaces it owns. Adapters translate between the outside world and the ports.

  • Driving (inbound) ports: how the world calls the application (PlaceOrder). Adapters: REST controller, CLI, message listener, test.
  • Driven (outbound) ports: what the application needs (OrderRepository, PaymentGateway, Clock). Adapters: SQL implementation, payment provider client, fake for tests.

  // Port owned by the application
  interface OrderRepository { save(order: Order): Promise<void>; byId(id: string): Promise<Order | null> }
  interface PaymentGateway { charge(cents: number, token: string): Promise<boolean> }
  
  // Use case: pure application logic
  class PlaceOrder {
    constructor(private orders: OrderRepository, private payments: PaymentGateway) {}
    async run(input: { items: Item[]; token: string }) {
      const order = Order.create(input.items);                   // entity enforces rules
      if (!(await this.payments.charge(order.totalCents, input.token))) throw new Error("Payment failed");
      await this.orders.save(order);
      return order.id;
    }
  }
  
  // Adapters live outside, implementing the ports
  class SqlOrderRepository implements OrderRepository { /* uses a database */ }
  class StripeGateway implements PaymentGateway { /* calls the provider */ }
  
  // Composition root wires everything together at start-up
  const placeOrder = new PlaceOrder(new SqlOrderRepository(db), new StripeGateway(key));
  

  This is the dependency inversion principle from SOLID applied to a whole system.

  Benefits

  • Testable: run use cases with in-memory fakes, fast and without infrastructure.
  • Replaceable details: change the database, queue or web framework by writing an adapter.
  • Focus on the domain: the central code reads like the business process.
  • Deferred decisions: you can postpone choosing a database.

  Costs and cautions

  • More structure: interfaces, mappers and wiring add code. For a small CRUD app it can be overkill.
  • Mapping between layers (domain objects, database rows, API shapes) is repetitive; do it deliberately and avoid leaking database entities into the API.
  • Do not create layers "because the diagram says so". Add a boundary where a real change or testing need exists.
  • It is about dependencies, not folder names: a good folder layout helps but does not guarantee the rule is followed. Enforce it with tests or lint rules.

  Related ideas

  • Domain-driven design supplies the language for the centre of the hexagon (next lesson).
  • Microservices are a deployment choice; each service can use this internal structure.
  • Composition root: one place, at start-up, where concrete classes are chosen and injected.

  Real-world reading

  Related reading

  • Cockroach Labs BlogCockroach Labs engineers · Cockroach LabsBlogs
  • Fivetran BlogFivetran engineers · FivetranBlogs
  • ClickHouse BlogClickHouse engineers · ClickHouseBlogs
  • InfluxData BlogInfluxData engineers · InfluxDataBlogs

  Show 6 moreShow fewer

  • Elastic BlogElastic engineers · ElasticBlogs
  • AWS Database BlogAWS database teams · Amazon Web ServicesBlogs
  • How SQLite WorksSQLite team · SQLiteDocumentation
  • AWS Big Data BlogAmazon Web Services engineers · Amazon Web ServicesBlogs
  • Viget Engineering BlogViget engineers · VigetBlogs
  • Meituan Blog (Chinese)Meituan engineers · MeituanBlogs

  Open this lesson with its quiz and exercise

• Databases Deep Dive · 12 minReplication topologies and multi-region databasesSingle-leader, multi-leader and leaderless replication, how they handle conflicts and lag, and what changes across regions.Read hereClose

  Why replicate

  Replication keeps copies of data on several machines for three reasons: availability (survive a node failure), read scaling (serve reads from replicas) and latency (put data near users). The hard part is keeping copies consistent while writes continue. (Basics are in the replication and sharding lesson of the foundations course; this lesson compares the topologies.)

  Single-leader (primary and replicas)

  One node, the leader (primary or master), accepts writes and ships its changes to followers (replicas), which serve reads.

  100%

  Figure SDA-DDV-04-1 · Single-leader replication · © forcsguy.com

  • Synchronous replication waits for a follower before acknowledging: safer, slower, and a stalled follower can block writes. Asynchronous is faster but a failover can lose the latest writes. A common compromise: one synchronous follower, others asynchronous.
  • Failover must detect failure, choose the most up-to-date replica, redirect clients and ensure the old leader does not come back believing it still leads (split brain).
  • Replication lag causes stale reads. Techniques: read-your-writes (route a user's reads to the leader shortly after they write), monotonic reads (keep a user on one replica), and checking replica position.

  Multi-leader

  Several nodes accept writes (often one per region) and replicate to each other. Benefits: local write latency and continued operation if a region is cut off. Cost: write conflicts.

  Conflict handling options:

  • Avoid them: route all writes for one record to one leader (for example by user or region).
  • Last write wins by timestamp: simple, but silently drops one of two concurrent updates and depends on clocks.
  • Merge values (union of sets, counters) using mergeable data types (CRDTs; see the collaborative editing lesson).
  • Custom resolution in application code, or ask the user.

  Multi-leader also appears in offline-capable apps (each device is a leader) and collaborative editing.

  Before: single leader

  100%

  After: multi-leader across regions

  100%

  What changed

  • Users in each region write to a nearby database
  • Concurrent edits to the same row need conflict handling
  • More moving parts to run and monitor

  Leaderless (Dynamo-style)

  Any replica accepts writes; clients write to several replicas and read from several, using quorums (W + R > N) to get fresh data (see the key-value store lesson). Background anti-entropy and read repair fix stale copies; versions or vector clocks detect conflicts. It favours availability and is typical of Cassandra and DynamoDB-style stores.

  100%

  Figure SDA-DDV-04-2 · Choosing a replication model · © forcsguy.com

  Multi-region designs

  • Active-passive: one region serves writes; another is a warm standby. Simple; failover loses a little data (the replication lag) and takes minutes.
  • Active-active: several regions serve traffic. Requires either partitioning data by home region (each record has one home, cross-region reads are replicas) or true multi-leader conflict handling.
  • Global databases use consensus across regions (see the consensus lesson) for strong consistency at the cost of cross-region write latency; some offer tunable consistency per query.
  • Latency numbers matter: a cross-ocean round trip is around 100 ms or more, so synchronous cross-region replication adds that to every write.
  • Data residency laws may require keeping certain users' data in a region.

  Partitioning and replication together

  Real systems shard data into partitions and replicate each partition (a leader per partition spreads write load across nodes). Rebalancing, hot partitions and cross-partition transactions are the new problems (see sharding and the consistent-hashing lesson).

  Master/slave naming

  You will see "master/slave", "primary/replica" and "leader/follower" for the same single-leader idea; most current documentation prefers the last two.

  Checklist

  • What happens to writes if the leader or a region is lost, and how long?
  • How much data can we lose (RPO) and how long can we be down (RTO)?
  • How do we handle stale reads from replicas?
  • Who resolves conflicts, and how?
  • Have we practised failover?

  Real-world reading

  Related reading

  • Active-Active for Multi-Regional ResiliencyNetflix Engineering · NetflixCase Studies
  • Designing Data-Intensive ApplicationsMartin Kleppmann · O'ReillyBooks
  • Read Consistency with Database Replicas at ShopifyShopify engineers · ShopifyCase Studies
  • Uber Schemaless: A Scalable MySQL DatastoreUber Engineering · UberCase Studies

  Show 6 moreShow fewer

  • Mitigating MySQL Replication Lag and Reducing Read Load at GithubGithub engineers · GithubCase Studies
  • Cassandra architecture overviewApache Cassandra · Apache Software FoundationDocumentation
  • How Discord Stores Trillions of MessagesBo Ingram · DiscordBlogs
  • Spanner: Google's Globally Distributed Database (paper)Corbett et al. · GooglePapers
  • Scaling Multitenant Architecture Across Multiple Data Centres at Shopify - Weingarten, Engineering Lead at ShopifyShopifyYouTube
  • MIT 6.824: Distributed SystemsRobert Morris · MITCourses

  Open this lesson with its quiz and exercise