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-http

Then 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 nameAttributes
listener.acceptlistener.protocol, listener.port
router.handledomain, client.ip, beacon.id (when set)
pipeline.evaluatefilter_count, mode
filter.<name>filter.action, filter.score
upstream.forwardupstream.url, upstream.status_code
drop.handledrop_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.