# Logging

Census supports two log output formats: human-readable text (default) and structured JSON for machine consumption.

## Log formats

### Text (default)

```bash
census -v scan /data --source hr
```

Output on stderr:

```
14:30:00 DEBUG    Hashed: report.pdf → a1b2c3d4...
14:30:00 DEBUG    Hashed: data.csv → e5f6a7b8...
14:30:01 INFO     Batch attest: 2 hashes
```

### JSON

```bash
census -v --log-format json scan /data --source hr
```

Output on stderr (one JSON object per line):

```json
{"timestamp": "2026-03-18T14:30:00", "level": "DEBUG", "module": "scanner", "message": "Hashed: report.pdf \u2192 a1b2c3d4..."}
{"timestamp": "2026-03-18T14:30:01", "level": "INFO", "module": "cli", "message": "Batch attest: 2 hashes"}
```

## Verbosity

| Flag | Log level | Use case |
|------|-----------|----------|
| (none) | INFO | Normal operation — progress, results, warnings |
| `-v` / `--verbose` | DEBUG | Troubleshooting — per-file hashes, API call details |

## Stream separation

- **stdout**: CLI output (scan results, status, export data)
- **stderr**: Log messages (debug, info, warnings, errors)

This allows piping CLI output while preserving logs:

```bash
# Pipe CSV export, logs visible on terminal
census export manifest.db --format csv > inventory.csv

# Redirect logs to file
census -v scan /data --source hr 2> census.log
```

## SIEM integration

The JSON log format is designed for direct ingestion by log aggregation systems:

- **ELK Stack**: Filebeat with JSON parsing → Elasticsearch
- **Splunk**: Monitor stderr output with JSON sourcetype
- **Datadog**: Log collection agent with JSON auto-parse

Each log line contains:

| Field | Type | Description |
|-------|------|-------------|
| `timestamp` | string | ISO 8601 format (`YYYY-MM-DDTHH:MM:SS`) |
| `level` | string | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
| `module` | string | Source module (`scanner`, `cli`, `compare`, `retry`) |
| `message` | string | Human-readable log message |
| `exception` | string | Stack trace (only present on errors with exceptions) |
