Skip to content

Docs: Lead performance/cost table with speculative write costs (the default) #386

@sodre

Description

@sodre

Problem

The performance documentation shows both normal path and speculative write costs, but doesn't emphasize that speculative writes are enabled by default. A reader scanning the cost table sees the normal path first and assumes that's the default cost.

This led to a concrete misunderstanding: estimating 10M non-cascade calls at $7.50/month (normal path: 1 RCU + 1 WCU per call) when the actual default cost is ~$6.88/month (speculative: 0 RCU + 1 WCU per call, with ~5% fallback).

Suggested Changes

  1. Reorder the cost table to lead with speculative write costs since they are the default behavior.

  2. Add a callout at the top of the performance section:

> **Note:** Speculative writes are enabled by default. The costs
> below reflect the default configuration. To use the normal
> read-before-write path, set `speculative_writes=False`.
  1. Add a quick-reference cost summary for common scales:
Scale Non-Cascade (default) Cascade (default)
1M calls/month ~$0.69 ~$1.29
10M calls/month ~$6.88 ~$12.85
100M calls/month ~$68.80 ~$128.50

(Assuming ~95% speculative hit rate, on-demand pricing)

Why This Matters

Cost estimation is a key factor when evaluating rate limiting solutions. If the docs lead with the more expensive path, users may overestimate costs and choose a different solution unnecessarily.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions