# Story 12.8: Log Sampling and Rate Limiting for FastAPI

**Status:** Complete
**Priority:** P2 (Medium)
**Depends on:** None
**Epic:** 12.0 Cookbook (SEO-Driven Documentation)

---

## Context / Background

High-traffic services can generate overwhelming log volume during traffic spikes. Sampling (logging a percentage of requests) and rate limiting (capping logs per second) help maintain observability without drowning in data.

fapilog provides configurable sampling and rate limiting to keep signal under load.

**Target search queries:**

- "python log sampling"
- "rate limit logs"
- "reduce logging volume python"
- "fastapi sampling logs"

**Why fapilog is the answer:** Built-in sampling and rate limiting plugins with configurable thresholds.

---

## Scope (In / Out)

### In Scope

- Cookbook page explaining sampling vs rate limiting
- Configuration examples for both
- When to use each approach
- Preserving important logs (errors always logged)

### Out of Scope

- Custom sampling algorithms
- Distributed sampling coordination
- Trace-based sampling (OpenTelemetry)

---

## Acceptance Criteria

### AC1: Page Exists with Correct Title

**Description:** Cookbook page created with SEO-optimized title.

**Validation:**
```
docs/cookbook/log-sampling-rate-limiting.md exists
H1: "Log sampling and rate limiting for FastAPI"
```

### AC2: Sampling Explained and Configured

**Description:** How to log a percentage of requests.

**Validation:**

Sampling is configured via filter plugins:
```python
from fapilog import get_async_logger, Settings

settings = Settings()
settings.core.filters = ["sampling"]
# Plugin config is set separately via plugin configuration system
logger = await get_async_logger(settings=settings)
```

### AC3: Rate Limiting Explained and Configured

**Description:** How to cap log volume per second.

**Validation:**

Rate limiting is configured via the `rate_limit` filter plugin:
```python
from fapilog import get_async_logger, Settings

settings = Settings()
settings.core.filters = ["rate_limit"]
# RateLimitFilter uses token bucket: capacity (tokens) and refill_rate_per_sec
logger = await get_async_logger(settings=settings)
```

### AC4: Decision Framework Provided

**Description:** Helps reader choose the right approach.

**Validation:**
| Approach | Use When | Tradeoff |
|----------|----------|----------|
| Sampling | High volume, statistical debugging | Miss individual requests |
| Rate limiting | Spike protection | Drop excess during spikes |
| Both | Maximum protection | Combined limitations |

### AC5: Error Preservation Documented

**Description:** Important logs bypass sampling.

**Validation:**
- Errors always logged (not sampled)
- How to configure which levels are preserved

---

## Implementation Notes

### File Path

`docs/cookbook/log-sampling-rate-limiting.md`

### Page Structure

```markdown
# Log sampling and rate limiting for FastAPI

Traffic spikes shouldn't mean log bill spikes...

## Sampling: Log a Percentage

{When to use}
{Configuration}

## Rate Limiting: Cap Volume

{When to use}
{Configuration}

## Which Should I Use?

{Decision table}

## Preserving Important Logs

{Errors bypass sampling}

## Going Deeper

- [Sampling Plugin Reference](/plugins/sampling)
- [Rate Limiting Plugin Reference](/plugins/rate-limiting)
```

---

## Tasks

- [ ] Create `docs/cookbook/log-sampling-rate-limiting.md`
- [ ] Write sampling section
- [ ] Write rate limiting section
- [ ] Create decision framework
- [ ] Document error preservation
- [ ] Test configurations
- [ ] Add cross-links

---

## Tests

- Sampling produces expected reduction
- Rate limiting caps as configured
- Errors not dropped

---

## Definition of Done

### Content Complete

- [x] All sections written
- [x] Configurations tested
- [x] Decision framework clear

### SEO Optimized

- [x] Keywords in H1 and first paragraph
- [x] Under 1000 words

### Integrated

- [x] Added to cookbook index
- [x] Linked from skip-noisy-endpoints

---

## Risks / Rollback

### Risks

1. **Risk:** Features not yet implemented
   - **Mitigation:** Verify against Story 5.3

### Rollback Plan

Revert commit.

---

## Related Stories

- **Depends on:** 5.3 Sampling and Rate Limiting Plugins

---

## Code Review

**Date:** 2026-01-21
**Reviewer:** Claude
**Verdict:** OK to PR

### Summary

Cookbook page for log sampling and rate limiting with middleware/pipeline configuration examples, decision framework, and error preservation documentation.

### AC Verification

| Criterion                          | Evidence                                                          |
| ---------------------------------- | ----------------------------------------------------------------- |
| AC1: Page exists with correct title | `log-sampling-rate-limiting.md:1` - H1 matches spec               |
| AC2: Sampling explained             | `log-sampling-rate-limiting.md:16-83` - Middleware + pipeline config |
| AC3: Rate limiting explained        | `log-sampling-rate-limiting.md:85-167` - Token bucket with examples |
| AC4: Decision framework             | `log-sampling-rate-limiting.md:169-176` - Table matches spec      |
| AC5: Error preservation             | `log-sampling-rate-limiting.md:207-248` - Errors bypass sampling  |

### Quality Gates

- [x] Code examples verified working
- [x] Under 1000 words (973)
- [x] Keywords in H1 and first paragraph
- [x] Added to cookbook index
- [x] Cross-links updated

---

## Change Log

| Date       | Change                  | Author |
| ---------- | ----------------------- | ------ |
| 2026-01-21 | Initial draft           | Claude |
| 2026-01-21 | Implementation complete | Claude |
