Observability

Dome is OpenTelemetry-compliant and integrates with popular observability platforms. This guide covers tracing, metrics, and logging setup for your Guardrails. If you use Trust Runtime, its structured audit events complement Dome telemetry with Agent identity, tool access, attestation, downgrade, and enforcement-heartbeat decisions. Every event includes the configured agent_id; cryptographic identity fields are available only when the runtime is attested.

Install OpenTelemetry Support

pip install "vijil-dome[opentelemetry]"

Add the google extra as well when you export to Google Cloud Trace, Monitoring, or Logging.

Instrument Dome

instrument_dome() attaches a logging handler, a tracer, and a meter to an existing Dome instance. Every argument is optional, so you can enable only the signals you need:

import logging
from opentelemetry import metrics, trace

from vijil_dome import Dome
from vijil_dome.integrations.instrumentation.otel_instrumentation import instrument_dome

dome = Dome()

instrument_dome(
    dome,
    handler=logging.StreamHandler(),
    tracer=trace.get_tracer("my-agent"),
    meter=metrics.get_meter("my-agent"),
)

Instrumentation is applied once per instance. Calling instrument_dome() again on the same instance is a no-op.

Set up your tracer and meter providers, including exporters for Jaeger, Prometheus, or another OpenTelemetry backend, before you call instrument_dome().

LLM Tracing Platforms

Dome exposes apply_decorator(), which wraps its scan methods with any decorator. Use it to add Dome activity to platforms that trace through decorators.

Weights & Biases Weave

Weave is W&B’s toolkit for tracing LLM applications:

import weave
from vijil_dome import Dome

dome = Dome()
dome.apply_decorator(weave.op)

Calls to guard_input(), guard_output(), and their asynchronous forms then appear in your Weave dashboard with per-Guard and per-Detector details.

AgentOps

AgentOps provides Agent-focused observability. Install agentops separately, then apply its recorder:

import os

import agentops
from vijil_dome import Dome

agentops.init(os.getenv("AGENTOPS_API_KEY"))

dome = Dome()
dome.apply_decorator(agentops.record_action())

The decorator you pass to apply_decorator() must support both synchronous and asynchronous functions, because Dome wraps both scan variants.

Tracing

When you supply a tracer, Dome creates spans for each Guard and Detector it runs:

Guardrail execution: top-level span for guard_input() and guard_output()
Guard execution: nested span for each Guard in the Guardrail
Detector execution: nested span for each Detector in the Guard

Each span carries the input and output of the call, execution time, error information, and whether content was flagged. Dome also emits one dome-detection span per scan, carrying dome.guardrail, detection.label, detection.score, detection.method, dome.guard.enforced, and the agent.id, team.id, and user.id values you pass to the scan. The Vijil Console reads these spans and presents them in Monitor Dome Metrics.

Span Hierarchy

Dome-Input-Guardrail.scan
├── Dome-Input-Guardrail.security_default.scan
│   ├── Dome-Input-Guardrail.security_default.EncodingHeuristicsDetector.scan
│   └── Dome-Input-Guardrail.security_default.MBertPromptInjectionModel.scan
└── Dome-Input-Guardrail.moderation_default.scan
    └── Dome-Input-Guardrail.moderation_default.KWBanList.scan

Metrics

When you supply a meter, Dome instruments every Guardrail, Guard, and Detector with four instruments:

Instrument	Suffix	Description
Requests	`-requests_total`	Requests sent to the component
Flagged	`-flagged_total`	Requests the component flagged
Errors	`-error_total`	Errors the component raised
Latency	`-latency_seconds`	Execution time of the component

Metric Naming

Names follow the pattern [guardrail].[guard].[detector] plus the instrument suffix. instrument_dome() names the two Guardrails dome-input and dome-output, and characters that OpenTelemetry does not accept in an instrument name become underscores:

dome_input-requests_total
dome_input.security_default-flagged_total
dome_input.security_default.MBertPromptInjectionModel-latency_seconds

Logging

Dome logs through Python loggers named vijil.dome. Any handler you pass to instrument_dome() is attached to those loggers.

Level	What Is Logged
`DEBUG`	Initialization of Guardrails, Guards, and Detectors, with their parameters
`INFO`	Inputs and outputs of each component, and Detector routing decisions
`WARNING`	Missing configuration, context window exceeded, timeouts, Detector errors
`ERROR`	Handled exceptions during execution
`CRITICAL`	Initialization failures and unhandled exceptions

Set VIJIL_LOG_PAYLOADS=1 to add a redacted payload record, which reports the payload type and length rather than its content, at DEBUG level for every scan.

Best Practices

Always instrument in production: visibility is essential for security.
Set appropriate log levels: use INFO in production and DEBUG for troubleshooting.
Monitor block rates: sudden increases may indicate an attack.
Track latency: confirm that Guards do not degrade the user experience.
Alert on errors: a rise in -error_total means Detectors are failing, and the on-error policy is deciding outcomes instead of the Detectors.

Work in Progress

The programmatic observability capabilities and integrations are currently in private preview and subject to change.

Next Steps

Trust Runtime

Capture identity and policy decisions

Configure Guardrails

Guard configuration options

Use Guardrails

Runtime integration patterns

Custom Detectors

Build custom detection methods

Get Started

Evaluate Agents

Protect Agents

Reference

Observability

Install OpenTelemetry Support

Instrument Dome

LLM Tracing Platforms

Weights & Biases Weave

AgentOps

Tracing

Span Hierarchy

Metrics

Metric Naming

Logging

Best Practices

Work in Progress

Next Steps

Trust Runtime

Configure Guardrails

Use Guardrails

Custom Detectors

​Install OpenTelemetry Support

​Instrument Dome

​LLM Tracing Platforms

​Weights & Biases Weave

​AgentOps

​Tracing

​Span Hierarchy

​Metrics

​Metric Naming

​Logging

​Best Practices

Work in Progress

​Next Steps

Trust Runtime

Configure Guardrails

Use Guardrails

Custom Detectors

Install OpenTelemetry Support

Instrument Dome

LLM Tracing Platforms

Weights & Biases Weave

AgentOps

Tracing

Span Hierarchy

Metrics

Metric Naming

Logging

Best Practices

Next Steps