# Story 5.32: Document Cloud and Database Sinks

**Status:** Complete
**Priority:** Medium
**Depends on:** None

---

## Context / Background

The `docs/api-reference/plugins/sinks.md` file only documents 5 of 10 built-in sinks:

- stdout_json
- stdout_pretty
- rotating_file
- http
- webhook

Three production-ready sinks lack detailed API reference documentation:

- **CloudWatchSink** (`src/fapilog/plugins/sinks/contrib/cloudwatch.py`) - AWS CloudWatch Logs
- **LokiSink** (`src/fapilog/plugins/sinks/contrib/loki.py`) - Grafana Loki
- **PostgresSink** (`src/fapilog/plugins/sinks/contrib/postgres.py`) - PostgreSQL database

Users can discover these sinks in the summary table (`plugins/index.md`) but have no guidance on configuration options, environment variables, or usage patterns. This was flagged as a P1 issue in a documentation review report.

---

## Scope (In / Out)

### In Scope

- Add CloudWatchSink section to `sinks.md` with:
  - Configuration options table
  - Environment variables
  - Usage example
  - AWS authentication notes
- Add LokiSink section to `sinks.md` with:
  - Configuration options table
  - Environment variables
  - Authentication options (basic auth, bearer token, tenant ID)
  - Labels configuration
- Add PostgresSink section to `sinks.md` with:
  - Configuration options table
  - Environment variables
  - Connection pooling notes
  - Table schema and JSONB storage explanation

### Out of Scope

- AuditSink documentation (enterprise feature, separate docs)
- RoutingSink documentation (future story)
- New code or features (documentation only)
- Tutorial or guide content (API reference only)

---

## Acceptance Criteria

### AC1: CloudWatchSink Documented

**Description:** CloudWatch sink has complete API reference documentation.

**Validation:**

- Section exists in `sinks.md` under "## CloudWatch Sink"
- Config table includes all 11 options: log_group_name, log_stream_name, region, create_log_group, create_log_stream, batch_size, batch_timeout_seconds, max_retries, retry_base_delay, endpoint_url, circuit_breaker_enabled, circuit_breaker_threshold
- Environment variables section lists AWS_REGION, AWS_DEFAULT_REGION
- Dependency note mentions `boto3>=1.26.0`
- Basic usage example with Settings configuration

### AC2: LokiSink Documented

**Description:** Loki sink has complete API reference documentation.

**Validation:**

- Section exists in `sinks.md` under "## Loki Sink"
- Config table includes all 13 options: url, tenant_id, labels, label_keys, batch_size, batch_timeout_seconds, timeout_seconds, max_retries, retry_base_delay, auth_username, auth_password, auth_token, circuit_breaker_enabled, circuit_breaker_threshold
- Environment variables section lists all FAPILOG_LOKI\_\_\* vars
- Authentication options explained (basic auth vs bearer token)
- Labels configuration example

### AC3: PostgresSink Documented

**Description:** Postgres sink has complete API reference documentation.

**Validation:**

- Section exists in `sinks.md` under "## PostgreSQL Sink"
- Config table includes all 20 options: dsn, host, port, database, user, password, table_name, schema_name, create_table, min_pool_size, max_pool_size, pool_acquire_timeout, batch_size, batch_timeout_seconds, max_retries, retry_base_delay, circuit_breaker_enabled, circuit_breaker_threshold, use_jsonb, include_raw_json, extract_fields
- Environment variables section lists all FAPILOG_POSTGRES\_\_\* vars
- Dependency note mentions `asyncpg>=0.28.0`
- Table schema explanation (auto-created columns, indexes)

### AC4: Documentation Review Report Updated

**Description:** Mark the P1 issue as resolved in the review report.

**Validation:**

- `docs/documentation-review-report.md` shows CloudWatch/Loki/Postgres docs as resolved

---

## Implementation Notes

### File Changes

```
docs/api-reference/plugins/sinks.md (MODIFIED - add 3 sink sections)
docs/documentation-review-report.md (MODIFIED - mark issue resolved)
```

### Configuration Details to Document

**CloudWatchSink** (from `CloudWatchSinkConfig`, 11 options):
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| log_group_name | str | "/fapilog/default" | CloudWatch log group |
| log_stream_name | str | None (auto-generated) | CloudWatch log stream |
| region | str | AWS_REGION env | AWS region |
| create_log_group | bool | True | Auto-create log group |
| create_log_stream | bool | True | Auto-create log stream |
| batch_size | int | 100 | Events per batch |
| batch_timeout_seconds | float | 5.0 | Max batch wait time |
| max_retries | int | 3 | Retry attempts |
| retry_base_delay | float | 0.5 | Base delay for exponential backoff |
| endpoint_url | str | None | LocalStack/testing endpoint |
| circuit_breaker_enabled | bool | True | Enable circuit breaker |
| circuit_breaker_threshold | int | 5 | Failures before circuit opens |

**LokiSink** (from `LokiSinkConfig`, 13 options):
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| url | str | "http://localhost:3100" | Loki server URL |
| tenant_id | str | None | X-Scope-OrgID header |
| labels | dict | {"service": "fapilog"} | Static labels |
| label_keys | list | ["level"] | Dynamic label fields |
| batch_size | int | 100 | Events per batch |
| batch_timeout_seconds | float | 5.0 | Max batch wait time |
| timeout_seconds | float | 10.0 | HTTP timeout |
| max_retries | int | 3 | Retry attempts |
| retry_base_delay | float | 0.5 | Base delay for exponential backoff |
| auth_username | str | None | Basic auth username |
| auth_password | str | None | Basic auth password |
| auth_token | str | None | Bearer token |
| circuit_breaker_enabled | bool | True | Enable circuit breaker |
| circuit_breaker_threshold | int | 5 | Failures before circuit opens |

**PostgresSink** (from `PostgresSinkConfig`, 20 options):
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| dsn | str | None | Full connection string (overrides host/port/etc) |
| host | str | "localhost" | Database host |
| port | int | 5432 | Database port |
| database | str | "fapilog" | Database name |
| user | str | "fapilog" | Database user |
| password | str | None | Database password |
| table_name | str | "logs" | Target table |
| schema_name | str | "public" | Target schema |
| create_table | bool | True | Auto-create table |
| min_pool_size | int | 2 | Min connections |
| max_pool_size | int | 10 | Max connections |
| pool_acquire_timeout | float | 10.0 | Connection acquire timeout |
| batch_size | int | 100 | Events per batch |
| batch_timeout_seconds | float | 5.0 | Max batch wait time |
| max_retries | int | 3 | Retry attempts |
| retry_base_delay | float | 0.5 | Base delay for exponential backoff |
| circuit_breaker_enabled | bool | True | Enable circuit breaker |
| circuit_breaker_threshold | int | 5 | Failures before circuit opens |
| use_jsonb | bool | True | Use JSONB vs JSON |
| include_raw_json | bool | True | Include full event in JSON column |
| extract_fields | list | [timestamp, level, ...] | Columns to extract |

---

## Tasks

### Phase 1: CloudWatch Documentation

- [ ] Add "## CloudWatch Sink" section to sinks.md
- [ ] Document configuration options table
- [ ] Document environment variables (AWS_REGION, AWS_DEFAULT_REGION)
- [ ] Add usage example with Settings
- [ ] Note boto3 dependency requirement

### Phase 2: Loki Documentation

- [ ] Add "## Loki Sink" section to sinks.md
- [ ] Document configuration options table
- [ ] Document environment variables (FAPILOG_LOKI\_\_\*)
- [ ] Explain authentication options
- [ ] Add labels configuration example

### Phase 3: Postgres Documentation

- [ ] Add "## PostgreSQL Sink" section to sinks.md
- [ ] Document configuration options table
- [ ] Document environment variables (FAPILOG_POSTGRES\_\_\*)
- [ ] Explain auto-created table schema and indexes
- [ ] Note asyncpg dependency requirement

### Phase 4: Cleanup

- [ ] Update documentation-review-report.md to mark issue resolved
- [ ] Verify all links work
- [ ] Review for consistency with existing sink docs

---

## Tests

### Manual Verification

- Documentation renders correctly in Sphinx/MkDocs
- All config options match source code
- Environment variable names are accurate
- Code examples are syntactically correct

---

## Definition of Done

### Documentation Complete

- [ ] All three sinks have dedicated sections
- [ ] Configuration tables match Pydantic models in source
- [ ] Environment variables documented
- [ ] Dependencies noted
- [ ] Usage examples provided

### Quality Assurance

- [ ] No broken links
- [ ] Consistent formatting with existing sections
- [ ] Spell check passes
- [ ] Tables render correctly

---

## Risks / Rollback

### Risks

1. **Risk:** Config options may change before merge
   - **Mitigation:** Document from current source, update if needed

### Rollback Plan

If issues occur:

1. Revert documentation changes
2. No code impact (docs only)

---

## Related Stories

- **Related:** Story 5.30 - Document Event Loop Lifecycle (recent docs work)
- **Enables:** Future routing sink documentation

---

## Change Log

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