Skip to main content

Audit Trail Generation: How Every Decision Gets Logged as an Event

Every governed Keeptrusts request becomes a reviewable event because the gateway evaluates the request, records the decision path, and exposes that stream through Events and kt events tail. The audit-logger policy marks audit logging as active in the chain, while persistence, exports, and evidence workflows are handled by the wider platform rather than by the policy block itself.

Use this page when​

  • You need to explain how Keeptrusts produces an audit trail without hand-waving over the implementation.
  • You want to distinguish what the audit-logger policy does from what the event and export system does.
  • You are building an investigation or compliance workflow around gateway events.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: Technical Leaders, security and compliance reviewers

The problem​

An audit trail is only useful if it reflects the actual decision point. Direct provider integrations usually leave you with fragments: provider logs, application logs, maybe a few tracing spans, and a separate moderation report if you are lucky. That is enough for debugging sometimes, but it is not a coherent governance record.

For AI systems, the question is not just whether a request succeeded. You usually need to know which model handled it, which policies were active, whether anything was blocked or redacted, whether a human review was triggered, and how much the request cost. Those details matter for incident response, internal review, and external evidence.

Another source of confusion is the audit-logger name itself. Many teams assume the policy block controls retention, immutability, or the storage backend. The current user-docs page is explicit that it does not. The policy is an allow-only marker in the active chain. Event persistence and export behavior live elsewhere in the platform.

That distinction is worth understanding because it prevents false confidence. You do not get an audit program by setting retention_days under a policy block and hoping the runtime enforces it. You get an audit trail by routing traffic through the gateway, making events part of the normal execution path, and then using the event and export surfaces intentionally.

The solution​

Keeptrusts solves the audit problem by making the gateway the control point.

When traffic moves through the gateway, the request is evaluated against the active chain and the outcome becomes part of the event stream. The audit-logger policy signals that audit logging is active in the chain, returning the allow result audit_logger.logged. The wider platform then handles storage, query, and export workflows.

The practical model looks like this:

  • The gateway evaluates the request.
  • Policies return allow, block, redact, or escalate behavior as appropriate.
  • Decision metadata is emitted as an event.
  • Engineers inspect recent decisions through the Events surface or kt events tail.
  • Reviewers export evidence when they need an artifact outside the live system.

That is why the audit trail is useful operationally, not just theoretically. The same execution path that governs live traffic is the one that produces evidence.

Implementation​

The chain itself can be minimal. The important point is to put the gateway in front of the traffic and make audit logging explicit.

pack:
  name: audit-trail-example
  version: 1.0.0
  enabled: true

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: gpt-5.4-mini-mini
      secret_key_ref:
        env: OPENAI_API_KEY

policies:
  chain:
    - prompt-injection
    - pii-detector
    - audit-logger

policy:
  prompt-injection:
    response:
      action: block
  pii-detector:
    action: redact
    redaction:
      marker_format: label
  audit-logger: {}

Validate and start the gateway:

kt policy lint --file policy-config.yaml
kt gateway run --policy-config policy-config.yaml --listen 0.0.0.0:41002

Then inspect the live decision stream:

kt events tail --limit 5 --json

That command is where the theory becomes concrete. It gives you the recent request decisions directly from the governance path. For runtime investigation, this is usually the fastest way to answer basic questions such as “did the request reach the provider?”, “which policy decided the outcome?”, or “is this part of a broader pattern?”

When the use case shifts from investigation to evidence handoff, move from the live stream to the documented export workflow. That is where Export Evidence for a Review and Tutorial: Exporting Compliance Evidence fit. They are not separate from the event model; they package it for review.

One practical nuance from the current audit-logger docs: do not rely on policy-local fields such as immutable or retention_days for enforcement. The published behavior today is that the evaluator ignores policy-specific config and acts as an allow-only marker. If you need storage or export guarantees, use the platform features built for that purpose.

This separation is actually helpful. It keeps the policy semantics simple and keeps retention or export responsibilities in the parts of the platform that own them.

Results and impact​

The first result is faster investigation. Because decision events live at the gateway boundary, engineers do not have to reconstruct the story from disconnected system logs.

The second result is stronger evidence handling. You can move from live tailing to structured export without inventing a separate compliance pipeline for AI traffic.

The third result is better policy tuning. Repeated blocks, escalations, or redactions are visible as operational patterns, which makes it easier to decide whether the policy is too strict, too weak, or simply catching the right class of traffic.

There is also an organizational benefit. Teams stop debating whether governance is “really happening” because the decision trail is observable in the normal workflow. That builds trust in the controls faster than a static policy document ever will.

Key takeaways​

  • The audit trail comes from routing traffic through the gateway decision path, not from documentation alone.
  • audit-logger currently marks audit logging as active and always returns allow.
  • Event persistence and export handling are broader platform functions, not policy-local retention rules.
  • kt events tail is the fastest way to inspect recent governed decisions.
  • Export workflows turn the live event stream into reviewable evidence.

Next steps​