Skip to main content

Observability & Audit

The Observability & Audit APIs help you capture every policy decision as an operational event in the Actra Python SDK.

This is critical for production Python systems where Actra decisions must be:

  • auditable
  • searchable
  • measurable
  • rollout-safe
  • compliance-ready

The Python SDK provides two real observability surfaces from the shared runtime implementation:

  • runtime.set_decision_observer()
  • runtime.audit()

Together, these enable both decision event streaming and non-blocking shadow evaluation.

Core Mental Model​

Runtime decision -> event -> logs / metrics / SIEM

Every evaluation can become a structured event for:

  • security logging
  • compliance exports
  • rollout analysis
  • anomaly detection
  • incident forensics

Decision Observer​

Use the runtime observer to receive every decision event.

runtime.set_decision_observer(
    lambda event: print(event.decision["effect"])
)

This is the primary Python hook for observability pipelines.

Event Payload​

The observer event includes runtime metadata such as:

  • decision
  • action
  • resolved actor
  • resolved snapshot
  • duration_ms

From the runtime flow, this event is emitted after evaluation and includes the full constructed context plus latency timing.

This makes it ideal for both logs and metrics.

Structured Logging​

A common Python production pattern is structured JSON logs.

runtime.set_decision_observer(
    lambda event: logger.info({
        "effect": event.decision["effect"],
        "matched_rule": event.decision.get("matched_rule"),
        "duration_ms": event.duration_ms,
    })
)

Great for:

  • ELK
  • Datadog
  • CloudWatch
  • Loki
  • OpenSearch

Metrics & Dashboards​

Observers are perfect for Python metrics pipelines.

runtime.set_decision_observer(
    lambda event: metrics.increment(
        f"actra.{event.decision['effect']}"
    )
)

Useful dashboards:

  • allow vs block rate
  • approval frequency
  • top matched rules
  • latency distribution
  • action hotspots

Security & SIEM​

A very strong enterprise Python use case.

runtime.set_decision_observer(
    lambda event: siem.send({
        "effect": event.decision["effect"],
        "actor": event.context["actor"],
        "action": event.action,
        "matched_rule": event.decision.get("matched_rule"),
    })
)

Best for:

  • SOC workflows
  • insider risk
  • privilege escalation detection
  • destructive action tracing
  • regulated environments

Non-Blocking Audit Mode​

Use audit() for shadow evaluation.

@runtime.audit(action_type="refund")
def refund(order_id: str, amount: int):
    return process_refund(order_id, amount)

This always executes the function while still:

  1. evaluating policy
  2. emitting observer events
  3. capturing decision metadata

This is ideal for:

  • safe rollouts
  • policy migrations
  • dry runs
  • measuring blast radius
  • legacy system onboarding

Shadow Rollout Pattern​

A highly recommended Python production workflow.

@runtime.audit(action_type="deploy")
def deploy_service(service_name: str):
    ...

Observe for:

  • unexpected blocks
  • approval spikes
  • missing resolver state
  • noisy rules
  • performance regressions

Then switch to:

@runtime.admit(action_type="deploy")
def deploy_service(service_name: str):
    ...

once confidence is high.

Compliance Audit Trail​

Actra decision events are excellent compliance evidence.

Track:

  • who attempted the action
  • what was attempted
  • current state
  • which rule matched
  • whether approval was required
  • how long evaluation took

This is highly valuable for:

  • SOX
  • ISO 27001
  • PCI
  • internal audit
  • change management

Production Safety Behavior​

Telemetry Isolation​

A core production guarantee is that audit mode never blocks execution.

Even when policy decisions return block, runtime.audit() swallows ActraPolicyError and continues execution, while still preserving observability.

This makes it safe for staged rollouts.

Best Practices​

Always instrument matched rules​

Track:

matched_rule

This makes incident forensics dramatically easier.

Start with audit() in rollouts​

Use shadow mode before enabling blocking enforcement.

Track latency budgets​

Use duration_ms to watch policy cost under load.

Production Mental Model​

Function call
 -> Evaluate policy
 -> Emit decision event
 -> Log / metric / SIEM
 -> Execute or shadow-run

This makes Actra observable as a Python production control plane.

Next Steps​

Recommended next Python SDK pages:

  • Testing Policies n- CI Validation
  • Explain & Debugging
  • rollout playbooks with audit()