# Story 6.5: Document Environment Variable Aliases

## Status: Complete

## Summary

Create comprehensive documentation for all environment variable aliases supported by Fapilog, making 12-factor app configuration discoverable.

## Motivation

The complexity audit identified that Fapilog supports short environment variable aliases (e.g., `FAPILOG_CLOUDWATCH__REGION` instead of `FAPILOG_SINK_CONFIG__CLOUDWATCH__REGION`) via `@model_validator` methods in settings. This is excellent enterprise DX, but users can only discover these aliases by reading source code.

Environment variable configuration is critical for:

- Kubernetes deployments
- Docker containers
- CI/CD pipelines
- 12-factor applications

## Acceptance Criteria

- [ ] `docs/user-guide/environment-variables.md` created
- [ ] All sink aliases documented (CloudWatch, Loki, Postgres, HTTP, Webhook)
- [ ] All processor aliases documented (SizeGuard)
- [ ] Routing configuration aliases documented
- [ ] Core settings env vars documented
- [ ] Examples showing common deployment patterns
- [ ] Cross-referenced from getting-started and deployment guides
- [ ] Table format for quick reference
- [ ] Type information included (string, int, bool, JSON)

## Technical Approach

### Document Structure

````markdown
# Environment Variable Configuration

Fapilog supports comprehensive configuration via environment variables,
following 12-factor app principles.

## Naming Convention

All environment variables use the `FAPILOG_` prefix with double underscores
for nesting:

- `FAPILOG_CORE__LOG_LEVEL` → `settings.core.log_level`
- `FAPILOG_CLOUDWATCH__REGION` → `settings.sink_config.cloudwatch.region`

## Quick Reference

### Core Settings

| Variable                       | Type   | Default | Description       |
| ------------------------------ | ------ | ------- | ----------------- |
| `FAPILOG_CORE__LOG_LEVEL`      | string | `INFO`  | Minimum log level |
| `FAPILOG_CORE__MAX_QUEUE_SIZE` | int    | `10000` | Max queue depth   |
| ...                            |        |         |                   |

### CloudWatch Sink

| Variable                             | Type   | Default            | Description |
| ------------------------------------ | ------ | ------------------ | ----------- |
| `FAPILOG_CLOUDWATCH__LOG_GROUP_NAME` | string | `/fapilog/default` | Log group   |
| `FAPILOG_CLOUDWATCH__REGION`         | string | (auto)             | AWS region  |
| ...                                  |        |                    |             |

### Loki Sink

| Variable                  | Type   | Default                 | Description     |
| ------------------------- | ------ | ----------------------- | --------------- |
| `FAPILOG_LOKI__URL`       | string | `http://localhost:3100` | Loki endpoint   |
| `FAPILOG_LOKI__TENANT_ID` | string | (none)                  | Multi-tenant ID |
| ...                       |        |                         |                 |

### PostgreSQL Sink

| Variable                 | Type   | Default     | Description            |
| ------------------------ | ------ | ----------- | ---------------------- |
| `FAPILOG_POSTGRES__HOST` | string | `localhost` | Database host          |
| `FAPILOG_POSTGRES__DSN`  | string | (none)      | Full connection string |
| ...                      |        |             |                        |

## Deployment Examples

### Kubernetes ConfigMap

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: fapilog-config
data:
  FAPILOG_CORE__LOG_LEVEL: "INFO"
  FAPILOG_CORE__SINKS: '["cloudwatch"]'
  FAPILOG_CLOUDWATCH__LOG_GROUP_NAME: "/myapp/production"
  FAPILOG_CLOUDWATCH__REGION: "us-east-1"
```
````

### Docker Compose

```yaml
services:
  app:
    environment:
      - FAPILOG_CORE__LOG_LEVEL=DEBUG
      - FAPILOG_LOKI__URL=http://loki:3100
      - FAPILOG_CORE__SINKS=["loki"]
```

### Heroku / Railway

```bash
heroku config:set FAPILOG_CORE__LOG_LEVEL=INFO
heroku config:set FAPILOG_POSTGRES__DSN=$DATABASE_URL
heroku config:set FAPILOG_CORE__SINKS='["postgres"]'
```

```

### Extract from Source

Parse `settings.py` to extract all env var aliases from `@model_validator` methods:

1. `_apply_size_guard_env_aliases` → SizeGuard vars
2. `_apply_cloudwatch_env_aliases` → CloudWatch vars
3. `_apply_loki_env_aliases` → Loki vars
4. `_apply_postgres_env_aliases` → Postgres vars
5. `_apply_sink_routing_env_aliases` → Routing vars

## Files Changed

- `docs/user-guide/environment-variables.md` — New file (+300 lines)
- `docs/user-guide/index.md` — Add link to new page
- `docs/getting-started/quickstart.md` — Cross-reference env vars
- `docs/examples/kubernetes-deployment.md` — Add env var examples (if exists)

## Estimated Effort

3-4 hours

## Risk Assessment

**Risk Level: Low**

- Documentation only
- No code changes
- Improves discoverability

## Validation

- [ ] All env vars from `@model_validator` methods documented
- [ ] Examples tested in local Docker environment
- [ ] Links work in built documentation

## Future Enhancement

Consider generating this documentation from code annotations:
- Add descriptions to each `os.getenv()` call
- Script to extract and format as markdown
- Ensures docs stay in sync with code

```
