OpenTelemetry Traces#
Added in v0.5. InfraGuard optionally emits distributed-trace spans that link a single beacon hit across the redirector: listener accept, filter pipeline, upstream forward, response write. Correlation IDs propagate from the proxy through plugins so a single trace shows one beacon’s full round-trip.
Enable#
Install the SDK:
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-httpThen call the setup helper from your app entrypoint (or add the block
to core/app.py’s lifespan):
from infraguard.observability import setup_otel
setup_otel(
service_name="infraguard-proxy",
endpoint="http://otel-collector:4318",
resource_attrs={"deployment.env": "production"},
)When endpoint is None, spans still emit but go to the console
exporter (dev mode).
Span namespace#
Spans use dotted names so downstream tools can filter by phase:
| Span name | Attributes |
|---|---|
listener.accept | listener.protocol, listener.port |
router.handle | domain, client.ip, beacon.id (when set) |
pipeline.evaluate | filter_count, mode |
filter.<name> | filter.action, filter.score |
upstream.forward | upstream.url, upstream.status_code |
drop.handle | drop_action.type, drop_action.target |
Wiring in plugins#
Any plugin can create a child span:
from infraguard.observability import span
async def on_request(self, ctx):
with span("plugin.myscan", client=str(ctx.client_ip)):
return await self._scan(ctx)If OTEL is not installed the span context manager is a no-op, so
plugins do not need to guard the import.
Correlation with tracking DB#
Every request row in the tracking DB carries the request hash. The
router adds that hash to the current span as request_hash so a trace
in Grafana Tempo (or Jaeger) can be joined back to the SQLite row by
hash. Useful for post-op review.
What is NOT traced (yet)#
- Cross-node calls to the shared state backend (Redis lookups). Enable by upgrading to the OTEL Redis instrumentation.
- Command Post fan-out. Manual span placement is the workaround for now.
See the roadmap for the full observability follow-ups.