# Story 12.4: One FastAPI Logging Config for Dev + Prod (Uvicorn/Gunicorn)

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

---

## Context / Background

Developers struggle to maintain consistent logging across different environments. Local development with `uvicorn main:app --reload` behaves differently than production with Gunicorn workers. Log formats change, levels get misconfigured, and debugging production issues becomes harder.

fapilog's environment auto-detection and presets solve this with a single configuration that adapts automatically.

**Target search queries:**

- "fastapi logging production uvicorn gunicorn"
- "python logging different environments"
- "fastapi dev vs production logging"
- "gunicorn logging configuration"

**Why fapilog is the answer:** Single config that auto-detects environment and adapts format/level appropriately.

---

## Scope (In / Out)

### In Scope

- Cookbook page showing unified dev/prod config
- Environment detection explanation
- Uvicorn vs Gunicorn differences
- Override patterns for specific environments

### Out of Scope

- Full Gunicorn deployment guide
- Kubernetes/Docker orchestration
- Log aggregation setup

---

## Acceptance Criteria

### AC1: Page Exists with Correct Title

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

**Validation:**
```
docs/cookbook/dev-prod-logging-config.md exists
H1: "One FastAPI logging config for dev + prod (Uvicorn/Gunicorn)"
```

### AC2: Single Config Pattern Shown

**Description:** One configuration that works everywhere.

**Validation:**
```python
# This works in dev AND prod
from fapilog.fastapi import setup_logging

lifespan = setup_logging(
    preset="fastapi",  # Auto-detects environment
)
```

### AC3: Environment Differences Explained

**Description:** What changes between dev and prod.

**Validation:**
- Table showing: format, level, color defaults per environment
- How detection works (env vars, TTY detection)

### AC4: Override Patterns Documented

**Description:** How to customize per-environment behavior.

**Validation:**
- Environment variable overrides
- Programmatic environment detection
- Example: force JSON in dev for testing

---

## Implementation Notes

### File Path

`docs/cookbook/dev-prod-logging-config.md`

### Page Structure

```markdown
# One FastAPI logging config for dev + prod (Uvicorn/Gunicorn)

Stop maintaining separate logging configs for each environment...

## The Problem

{Different configs drift apart}
{Production surprises}

## The Solution: Environment-Aware Defaults

```python
# Works everywhere
lifespan = setup_logging(preset="fastapi")
```

## What Changes Per Environment

| Setting | Development | Production |
|---------|-------------|------------|
| Format | pretty | json |
| Level | DEBUG | INFO |
| Colors | yes | no |

## How Detection Works

{ENV vars, TTY, etc.}

## Overriding Defaults

{Examples for specific needs}

## Going Deeper

- [Presets Reference](/api-reference/presets)
- [Environment Variables](/docs/env-vars)
```

---

## Tasks

- [ ] Create `docs/cookbook/dev-prod-logging-config.md`
- [ ] Write problem section
- [ ] Write single-config solution
- [ ] Create environment comparison table
- [ ] Document detection mechanism
- [ ] Add override examples
- [ ] Test in both environments

---

## Tests

- Config works with uvicorn
- Config works with gunicorn
- Environment detection correct

---

## Definition of Done

### Content Complete

- [x] All sections written
- [x] Tested in multiple environments
- [x] Code examples verified

### SEO Optimized

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

### Integrated

- [x] Added to cookbook index
- [x] Linked from deployment docs

---

## Risks / Rollback

### Risks

1. **Risk:** Auto-detection doesn't cover all cases
   - **Mitigation:** Document manual override patterns

### Rollback Plan

Revert commit.

---

## Code Review

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

### Summary

Reviewed cookbook page for unified dev/prod logging configuration with environment auto-detection.

### AC Verification

| Criterion | Evidence |
|-----------|----------|
| AC1: Page exists with correct title | `docs/cookbook/dev-prod-logging-config.md:1` - H1 matches spec |
| AC2: Single config pattern shown | `docs/cookbook/dev-prod-logging-config.md:27-31` - `setup_logging(preset="fastapi")` |
| AC3: Environment differences explained | `docs/cookbook/dev-prod-logging-config.md:43-67` - Table + detection mechanism |
| AC4: Override patterns documented | `docs/cookbook/dev-prod-logging-config.md:99-137` - Env vars + programmatic |

### Quality Gates

- [x] All DoD items verified
- [x] Under 1000 words (601)
- [x] Added to cookbook index
- [x] Linked from integration guide

---

## Change Log

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