Skip to main content

Event Tailing: Real-Time Decision Monitoring from Terminal

Terminal-side monitoring matters when the fastest path to an answer is not opening a dashboard but narrowing the evidence set immediately. kt events tail is the CLI surface for that job in Keeptrusts. It gives you recent decision data, lets you constrain the time window, narrows results by verdict, and emits JSON when you need a clean handoff into jq, shell automation, or another tool in your incident workflow.

Use this page when​

  • You need to confirm that a gateway is emitting recent decisions after a rollout.
  • You are investigating blocked, redacted, or escalated requests from a terminal session.
  • You want to hand another engineer a precise event slice instead of a screenshot from the console.

Primary audience​

  • Primary: Technical Engineers and platform operators
  • Secondary: Security analysts and technical leaders

The problem​

When governed traffic changes, the first symptom is often aggregate. A team sees more blocked requests, higher escalation volume, or a sudden change in model behavior. Aggregate views are useful for noticing the shift, but they are not where you prove the cause.

The real debugging questions are always narrower.

Which verdict changed? Over what time window? Did the shift affect all requests or just one environment? Was it tied to one provider or model? Was the system actually failing, or was a policy doing exactly what it was configured to do?

Without a terminal-friendly way to query recent decisions, engineers often fall back to slower patterns: reopening the console, copying filters by hand, or waiting until a fuller export is available. That slows post-deploy validation and makes incident handoffs weaker than they need to be.

The terminal is still where most operational work begins. If you cannot observe Keeptrusts decisions from there, you lose speed precisely when speed matters most.

The solution​

kt events tail solves that by giving you a lightweight event query surface that is close to the way engineers already work.

The command lets you scope events by time window, verdict, limit, and output format. That sounds simple, but operationally it is enough to answer the first set of questions after almost any change.

Use it after a deployment and you can confirm that decision events still look healthy. Use it during an incident and you can isolate the blocked or redacted slice immediately. Use it during a handoff and you can pass another operator the exact same JSON evidence instead of asking them to recreate your filter state.

It also makes Keeptrusts work better with the rest of the shell. JSON output means the event stream can be filtered, summarized, archived, or joined with other operational data. You do not need a special export workflow for routine debugging.

Implementation​

The basic command is intentionally small:

kt events tail --since 5m --limit 20 --json

That is a strong default after any rollout. It asks one narrow question: what happened in the last five minutes? If you are validating a newly deployed policy version, that window is usually enough.

When you already know the class of behavior you care about, filter by verdict:

kt events tail --since 1h --verdict blocked --json

That is especially useful for triage. A deployment may be healthy overall while still introducing an unwanted increase in one specific outcome class. Looking only at blocked results keeps the evidence set small enough to reason about quickly.

The next step is usually shell-side reduction. Because the command emits structured JSON, you can pull just the fields you need:

kt events tail --since 15m --verdict blocked --json | \
  jq '.[] | {id, timestamp, verdict, reason_code, provider, model, config_version}'

That pattern is useful after rollout because it gives you a compact summary of the exact decision surface that changed. It is also useful during handoff because the output is small enough to paste into a ticket or attach to an incident note.

One practical workflow is post-deploy verification.

  1. Deploy the new policy version.
  2. Send one or two known-safe and known-bad requests through the gateway.
  3. Run kt events tail --since 5m --limit 20 --json.
  4. Confirm the returned events show the expected verdicts and reason codes.

Another practical workflow is escalation triage.

  1. A support channel reports that requests started failing.
  2. Run kt events tail --since 30m --verdict escalated --json.
  3. Compare timestamps and reason codes.
  4. If needed, widen the query by removing the verdict filter and comparing the overall mix.

The command is also helpful when you want to decide whether the problem is enforcement or routing. If recent events still show the correct model, provider, and config version, the issue may be in prompt design or upstream behavior rather than gateway configuration. If the config version or reason codes changed sharply after a deploy, the policy rollout deserves first attention.

You can make the command part of automation too. A small shell guard in a release job can fail the deployment if no recent events appear after a smoke request, or if the verdict mix is obviously wrong for a fixed test case. That is a simple pattern, but it turns event evidence into an active release control instead of a passive debugging tool.

Results and impact​

Teams that start using kt events tail consistently stop depending on guesswork after a change. They can move straight from “something looks wrong” to a compact, recent, request-level evidence set.

That speeds up rollouts because validation no longer depends on a manual console walkthrough. It speeds up debugging because the terminal is already where the deploy, smoke test, and logs are happening. It also improves collaboration because JSON output is easier to share, diff, and archive than an ad hoc screenshot.

The more important impact is operational discipline. Event monitoring becomes part of the standard post-change loop, not something reserved for major incidents.

Key takeaways​

  • kt events tail is the fastest terminal-side path to recent Keeptrusts decision evidence.
  • Use --since first, then add --verdict when you already know the outcome class you care about.
  • Prefer --json when you need to hand the result to jq, another engineer, or a release job.
  • The command is useful for post-deploy verification, incident triage, and release handoff.
  • Small, recent event slices are often enough to distinguish policy issues from routing or upstream issues.

Next steps​