Listening and Observing Events

Observability Surfaces

Backend Activity Endpoint

Normalized activity stream:

GET /api/activity?limit=100

Response:

{
  "items": [
    {
      "kind": "event",
      "timestamp": "2024-01-15T10:30:00Z",
      "session_id": "abc-123",
      "user_id": "user-456",
      "payload": {
        "event": "validation_failed",
        "screen": "pan_entry",
        "component_id": "pan_field"
      },
      "trace": {
        "trace_id": "trace-abc",
        "request_id": "req-123"
      }
    }
  ],
  "livekit_ready": true,
  "feature_flags": {
    "trigger.v2_scoring": true
  }
}

Activity Stream (SSE)

Real-time updates:

GET /api/activity/stream

Server-sent events, 1-second polling loop.

Frontend Activity Dashboard

Visual event timeline:

Event kinds color-coded
Session grouping
User identification
Trace correlation

Correlation Fields

Primary correlation keys:

Field	Purpose
`session_id`	App session lifecycle
`user_id`	User identification
`trace_id`	Request correlation
`request_id`	Single request
`traceparent`	W3C trace context

Debugging with Headers

SDK generates trace headers:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
X-Request-ID: req-123-456
X-KYCIS-SDK-Version: 1.0.0
X-KYCIS-Session-ID: session-uuid

Host app can include these:

val headers = AI.traceHeadersForRequest("host_pan_screen")
// Include in your API calls

Checking Feature Flags

Current flag states:

GET /api/features

Response:

{
  "flags": {
    "integration.livekit_dispatch": true,
    "trigger.v2_scoring": false,
    "integration.schema_registry": true
  }
}

Log Analysis

Backend logs include:

Request/response traces
Session state changes
Trigger evaluation decisions
Voice agent context fetches

SDK Status Monitoring

AI.setStatusListener { status ->
  // Log all status changes
  analytics.track("kycis_status", mapOf(
    "code" to status.code.name,
    "message" to status.message
  ))
}

Common Debugging Tasks

Verify Events Reaching Backend

Check /api/activity for expected kind: "event"
Confirm payload.event matches sent type
Verify trace fields present

Verify Trigger Evaluation

Look for kind: "trigger" in activity
Check payload.signals includes expected data
Review payload.reason and payload.action

Verify Voice Session

Check kind: "session_start" with room/token
Look for kind: "session_stop" on end
Review kind: "reengagement" for recommendations

Cross-System Correlation

Find trace_id in SDK logs
Search backend logs for same trace_id
Check voice agent logs for session context

Health Check

Backend health:

GET /health

Response:

{ "status": "ok" }

Listening and Observing Events

On this page