# Story 12.2: FastAPI JSON Logging to stdout (Uvicorn Access Logs Included)

**Status:** Ready for Code Review
**Priority:** P0 (High)
**Depends on:** None
**Epic:** 12.0 Cookbook (SEO-Driven Documentation)

---

## Context / Background

JSON logging is essential for containerized deployments where logs are ingested by aggregation systems (CloudWatch, Datadog, ELK). Developers struggle to get both FastAPI app logs AND Uvicorn access logs in the same JSON format.

fapilog provides unified JSON output with configurable schema that covers both app logs and server access logs.

**Target search queries:**

- "FastAPI JSON logging"
- "uvicorn access logs json"
- "format uvicorn logs"
- "docker fastapi logging json"

**Why fapilog is the answer:** Single configuration produces consistent JSON for both application and access logs, with no ANSI color codes that break log parsers.

---

## Scope (In / Out)

### In Scope

- Cookbook page showing JSON logging setup
- Unified format for app + Uvicorn access logs
- Docker-friendly stdout configuration
- How to disable color codes

### Out of Scope

- Custom JSON schema design (link to schema guide)
- Log aggregation service configuration
- Uvicorn internals

---

## Acceptance Criteria

### AC1: Page Exists with Correct Title

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

**Validation:**
```
docs/cookbook/fastapi-json-logging.md exists
H1: "FastAPI JSON logging to stdout (Uvicorn access logs included)"
```

### AC2: Shows Unified JSON Output

**Description:** Example showing both app and access logs in JSON.

**Validation:**
- Sample app log JSON output
- Sample access log JSON output
- Both share consistent field names (timestamp, level, message)

### AC3: Docker-Ready Configuration

**Description:** Configuration that works in containers.

**Validation:**
- stdout sink (not file)
- No color codes
- Example Dockerfile snippet if helpful

### AC4: Uvicorn Integration Explained

**Description:** How to capture Uvicorn logs in fapilog.

**Validation:**
- Shows log_config override for Uvicorn
- Or shows fapilog middleware approach

---

## Implementation Notes

### File Path

`docs/cookbook/fastapi-json-logging.md`

### Page Structure

```markdown
# FastAPI JSON logging to stdout (Uvicorn access logs included)

Container platforms expect structured JSON logs on stdout...

## The Problem

{Different formats for app vs access logs}
{Color codes breaking parsers}

## The Solution

```python
from fapilog.fastapi import setup_logging

# preset="fastapi" gives JSON output by default
lifespan = setup_logging(preset="fastapi")
```

Or with explicit format control:
```python
from fapilog import get_async_logger

# format="json" ensures JSON output
logger = await get_async_logger(format="json")
```

## Sample Output

{JSON examples}

## Including Uvicorn Access Logs

{Integration snippet}

## Going Deeper

- [Schema Reference](/docs/schema-guide)
- [Docker Deployment Guide](/guides/docker)
```

---

## Tasks

- [ ] Create `docs/cookbook/fastapi-json-logging.md`
- [ ] Write problem section
- [ ] Write solution with minimal code
- [ ] Add sample JSON output
- [ ] Document Uvicorn integration
- [ ] Add Docker considerations
- [ ] Test code examples

---

## Tests

- Code examples produce valid JSON
- No color codes in output
- Links valid

---

## Definition of Done

### Content Complete

- [ ] All sections written
- [ ] JSON output samples verified
- [ ] Code tested

### SEO Optimized

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

### Integrated

- [ ] Added to cookbook index
- [ ] Linked from deployment guide

---

## Risks / Rollback

### Risks

1. **Risk:** Uvicorn log format changes
   - **Mitigation:** Pin to tested Uvicorn versions in examples

### Rollback Plan

Revert commit.

---

## Change Log

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