> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vijil.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Observability
> Monitor Dome Guardrails with OpenTelemetry, tracing, and logging.
Dome is OpenTelemetry-compliant and integrates with popular observability platforms. This guide covers tracing, metrics, and logging setup.
## Quick Setup
Install the [OpenTelemetry](https://opentelemetry.io/) support version of Dome using pip or your package manager.
## LLM Tracing Platforms
### Weights & Biases Weave
[Weave](https://weave-docs.wandb.ai/) is W\&B's toolkit for tracing LLM applications. You can use it with Dome to trace all inputs and outputs by wrapping Dome with Weave.
In your Weave dashboard, you'll see:
* All `guard_input` and `guard_output` calls
* Individual Guard execution within each Guardrail
* Detector-level details for each Guard
### AgentOps
[AgentOps](https://www.agentops.ai/) provides agent-focused observability. Initialize AgentOps and apply its tracking to the Dome instance.
## OpenTelemetry Integration
Dome works with any OpenTelemetry-compliant platform (Jaeger, Uptrace, Signoz, etc.).
### Basic Setup
You can instrument Dome with your tracer, meter, and handlers configuration via Dome's instrument method.
### Full Example with Jaeger
Specify your tracer provider and inject it into Dome's instrument method. All Guard calls will then create spans in Jaeger.
## Tracing
When instrumented with a tracer, Dome creates spans for:
* **Guardrail execution**: Top-level span for `guard_input` / `guard_output`
* **Guard execution**: Nested span for each Guard in the Guardrail
* **Detector execution**: Nested span for each Detector in the Guard
Each span includes:
* Input and output data
* Execution time
* Error information (if any)
* Whether content was flagged
### Span Hierarchy
```
guard_input
├── security-guard
│ ├── prompt-injection-mbert
│ └── encoding-heuristics
└── moderation-guard
└── moderation-flashtext
```
## Metrics
When instrumented with a meter, Dome automatically tracks:
| Metric | Description |
| ---------- | ---------------------------------- |
| `requests` | Total requests to each component |
| `flagged` | Requests flagged by each component |
| `errors` | Errors encountered |
| `latency` | Execution time |
### Metric Naming
Metrics follow the pattern: `[guardrail].[guard].[detector].[metric]`
Examples:
* `input_guardrail.security_guard.requests`
* `input_guardrail.security_guard.prompt_injection_mbert.flagged`
* `output_guardrail.latency`
### Example: Prometheus
You can export metrics from Dome to Prometheus by supplying a Prometheus metric reader and meter.
## Logging
Dome logs to Python loggers under `vijil.dome`. You can add standard handlers to capture logs.
### Log Levels
| Level | What is Logged |
| ---------- | ------------------------------------------------- |
| `DEBUG` | Initialization details, parameters |
| `INFO` | Inputs and outputs from each component |
| `WARNING` | Missing config, context window exceeded, timeouts |
| `ERROR` | Handled exceptions during execution |
| `CRITICAL` | Initialization failures, unhandled exceptions |
### Structured Logging
For JSON-structured logs, define a JSON formatter in your logging setup.
## Custom Metrics
You can also add and merge your own custom metrics alongside Dome's built-in metrics using the meter provider.
## Dashboard Examples
### Grafana Dashboard
You can track key metrics such as Blocked Request Rate, Average Latency, and Error Rates.
### Alerts
You can set up alerts for anomalies like high block rates or high latency directly in your observability solutions (e.g., Prometheus AlertManager).
## Best Practices
1. **Always instrument in production**: Visibility is essential for security
2. **Set appropriate log levels**: Use INFO for production, DEBUG for troubleshooting
3. **Monitor block rates**: Sudden increases may indicate attacks
4. **Track latency**: Ensure Guards do not impact user experience
5. **Alert on errors**: Guard failures should be investigated immediately
The programmatic observability capabilities and integrations are currently in private preview and subject to change.
## Next Steps
Guard configuration options
Runtime integration patterns
Build custom detection methods
Dome architecture overview