# Discovery Monitor Observability Framework

Structured logging framework for monitor execution with automatic lifecycle tracking.

## Usage

```python
from fidesplus.api.service.discovery.observability import (
    initialize,
    monitor_execution,
    phase,
)

# Initialize once at startup (optional - auto-initializes with defaults)
initialize()

# Track monitor execution
with monitor_execution("okta_prod", "discovery", "exec_123") as ctx:
    apps = fetch_okta_apps()

    # Track phases within execution
    async with phase("stage_apps", ctx) as phase_ctx:
        staged = stage_resources(apps)
        phase_ctx["resources_staged"] = len(staged)

    # Add execution-level metrics
    ctx["apps_discovered"] = len(apps)
```

**Output**: Automatically logs start/complete/error events with durations and structured attributes.

## Extending

**Add new attribute keys**: Edit `registry.py` to add to `AttributeKey` enum and `ATTRIBUTE_TYPES` dict.

**Add new event types**: Edit `registry.py` to add to `EventType` enum. Event types are strictly validated.

**Add typed helpers**: Create wrapper functions around `get_logger().log_event()` when needed.

**Custom validators/emitters**: Implement `Validator` or `Emitter` protocols and pass to `initialize()`.

## Best Practices

### Attribute Naming Conventions

- Use dot notation: `"resource.count"`, not `"resource_count"`
- Namespace by domain: `"okta.app.count"`, not `"app_count"`
- Follow existing `AttributeKey` patterns for consistency
- Use present tense: `"phase.name"`, not `"phase.named"`

### Event Type Conventions

- Event types must be defined in `EventType` enum (strict validation)
- Use hierarchical naming: `"monitor.start"`, `"phase.complete"`
- Use past tense for completion: `"monitor.complete"`, not `"monitor.completed"`
- Use error suffix for failures: `"monitor.error"`, `"phase.error"`

### Testing

Use `CaptureEmitter` from `testing.py` for test assertions:

## Components

- `registry.py` - AttributeKey enum, EventType enum, type validation rules
- `interfaces.py` - Validator and Emitter protocols
- `logger.py` - StructuredLogger core, initialization, thread-safe singleton
- `context.py` - monitor_execution() and phase() context managers
- `validators.py` - RegistryValidator implementation (strict validation)
- `emitters.py` - LoguruEmitter implementation
- `testing.py` - CaptureEmitter for test assertions

See code files for implementation details.
