John Dvorak
141 lines
3.3 KiB
Markdown
141 lines
3.3 KiB
Markdown
# Observe Mode
|
|
|
|
Runtime visibility and drift detection without blocking by default.
|
|
|
|
## What Observe Does
|
|
|
|
`apophis observe` validates your runtime observe configuration:
|
|
|
|
1. Checks that observe mode is allowed in the current environment
|
|
2. Validates reporting sink setup (logs, metrics, traces)
|
|
3. Confirms non-blocking semantics
|
|
4. Reports what would be observed and why it is safe
|
|
|
|
## When to Use It
|
|
|
|
- **Staging**: Validate observe config before promoting to production
|
|
- **Production**: Monitor contract drift without affecting requests
|
|
- **Platform teams**: Centralized visibility across services
|
|
|
|
## Safety Boundaries
|
|
|
|
Observe mode is non-blocking by default:
|
|
|
|
- **Non-blocking by default**: Contract violations are logged, not thrown
|
|
- **No request failures in non-blocking mode**: Violations are reported instead of thrown
|
|
- **Explicit opt-in for blocking**: Requires `allowBlocking: true` in environment policy
|
|
- **Production gating**: Blocking behavior is blocked in production by default
|
|
|
|
## Sink Configuration
|
|
|
|
Observe mode requires a reporting sink. Configure it in your environment policy:
|
|
|
|
```javascript
|
|
environments: {
|
|
staging: {
|
|
name: 'staging',
|
|
allowVerify: true,
|
|
allowObserve: true,
|
|
allowQualify: false,
|
|
allowChaos: false,
|
|
allowBlocking: false,
|
|
requireSink: true
|
|
}
|
|
}
|
|
```
|
|
|
|
APOPHIS supports these sink types:
|
|
|
|
- **Logs**: Structured logging of contract violations
|
|
- **Metrics**: Counter and histogram metrics for violation rates
|
|
- **Traces**: Distributed tracing integration for violation context
|
|
|
|
## Sampling
|
|
|
|
Control observation overhead with sampling:
|
|
|
|
```javascript
|
|
profiles: {
|
|
'staging-observe': {
|
|
name: 'staging-observe',
|
|
mode: 'observe',
|
|
preset: 'platform-observe',
|
|
routes: []
|
|
}
|
|
}
|
|
```
|
|
|
|
The `platform-observe` preset enables sampling at the preset level. Fine-tune per route with `x-observe-sampling` in your route schema.
|
|
|
|
## Staging vs Production
|
|
|
|
| Environment | Blocking | Sampling | Sink Required |
|
|
|---|---|---|---|
|
|
| Staging | No (default) | 10% | Yes |
|
|
| Production | No (default) | 1% | Yes |
|
|
|
|
## `--check-config` Flag
|
|
|
|
Validate config without activating observe mode:
|
|
|
|
```bash
|
|
apophis observe --profile staging-observe --check-config
|
|
```
|
|
|
|
This is useful in CI to ensure observe config is valid before deployment.
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning |
|
|
|---|---|
|
|
| 0 | Observe config is valid and safe |
|
|
| 2 | Safety violation or invalid config |
|
|
|
|
## Config Example
|
|
|
|
```javascript
|
|
// apophis.config.js
|
|
export default {
|
|
mode: 'observe',
|
|
profile: 'staging-observe',
|
|
profiles: {
|
|
'staging-observe': {
|
|
name: 'staging-observe',
|
|
mode: 'observe',
|
|
preset: 'platform-observe',
|
|
routes: []
|
|
}
|
|
},
|
|
presets: {
|
|
'platform-observe': {
|
|
name: 'platform-observe',
|
|
depth: 'standard',
|
|
timeout: 10000,
|
|
parallel: true,
|
|
chaos: false,
|
|
observe: true
|
|
}
|
|
},
|
|
environments: {
|
|
staging: {
|
|
name: 'staging',
|
|
allowVerify: true,
|
|
allowObserve: true,
|
|
allowQualify: false,
|
|
allowChaos: false,
|
|
allowBlocking: false,
|
|
requireSink: true
|
|
},
|
|
production: {
|
|
name: 'production',
|
|
allowVerify: true,
|
|
allowObserve: true,
|
|
allowQualify: false,
|
|
allowChaos: false,
|
|
allowBlocking: false,
|
|
requireSink: true
|
|
}
|
|
}
|
|
};
|
|
```
|