Skip to main content

Event Logs

Event Log Overview​

The Event Logs page shows every event that has been processed by Relay for your organization. This is your primary tool for monitoring, debugging, and auditing event traffic.

Access it via Event Logs in the dashboard sidebar.

The Event Log Table​

Each row represents one event. You'll see:

ColumnWhat It Shows
Event IDUnique identifier (e.g., evt_k9p2)
AppWhich app sent the event
AgentWhich agent was targeted
ThreadThe thread ID from the original event
StatusSuccess/failure status (see below)
LatencyHow long from event sent to reply received (or error)
TimestampWhen the event was processed

Event Statuses​

Each event has a status that tells you what happened:

Delivered​

The event was successfully sent to the agent, the agent processed it, and a reply was sent back.

  • ✅ Event reached the agent
  • ✅ Agent sent a response
  • ✅ Response was delivered back to the app
  • Latency: Shows end-to-end time (e.g., 2300ms)

Failed​

The event reached the agent, but something went wrong.

Common causes:

  • Agent timed out while processing
  • Agent session crashed or was interrupted
  • Network error between Relay and agent
  • Agent returned an explicit error

Latency: May be empty or show partial time depending on when failure occurred.

How to investigate:

  1. Click the event
  2. Check the error details in the detail panel
  3. Look at the agent's connection status (was it online?)
  4. Check the agent service logs

Pending​

The event is still being processed. This is temporary and should resolve within seconds.

  • Relay received the event
  • Relay sent it to the agent
  • Agent is still working on the reply

When you'd see it:

  • Long-running agent tasks
  • Slow network or high latency
  • You looked at the log while processing was still happening

How to investigate:

  1. Wait a few seconds
  2. Refresh the page
  3. Status should change to "delivered" or "failed"
  4. If it stays pending for more than 30 seconds, something is wrong

Rejected​

The event was rejected and never forwarded to the agent.

Common causes:

  • App is not allowlisted for this agent
  • Agent doesn't exist or is inactive
  • Organization ID mismatch (shouldn't happen, but logged)

Latency: Not applicable (no agent was involved).

How to investigate:

  1. Click the event to see the specific rejection reason
  2. If it's PERMISSION_DENIED: Check the agent's allowlist (see Managing Allowlists)
  3. If it's AGENT_NOT_FOUND: Verify the agent still exists and is active

Filtering Events​

Use filters to find the events you're looking for:

By App​

Show only events from a specific app:

  1. Click the App filter dropdown
  2. Select the app (e.g., "Portal", "Flow")
  3. Results update immediately

Leave blank or select "All Apps" to see events from every app.

By Agent​

Show only events sent to a specific agent:

  1. Click the Agent filter dropdown
  2. Select the agent (e.g., "Athena", "Klyve")
  3. Results update immediately

Leave blank or select "All Agents" to see events for every agent.

By Status​

Show only events with a specific status:

  1. Click the Status filter dropdown
  2. Select one or more statuses: delivered, failed, pending, rejected
  3. Results update immediately

Examples:

  • "Show me only rejected events" → filter by Status: rejected
  • "Show me only failures" → filter by Status: failed
  • "Show me what's working" → filter by Status: delivered

Combine Filters​

You can use multiple filters together:

  • "Events from Portal app AND to Athena agent" → Filter by App: Portal + Agent: Athena
  • "Failures from Flow to Klyve" → Filter by App: Flow + Agent: Klyve + Status: failed
  • "All rejected events" → Filter by Status: rejected (shows which apps are being blocked)

Event Detail Panel​

Click any event row to open its detail panel. This shows rich information:

Header Information​

Event ID: evt_k9p2
App: Portal
Agent: Athena
Status: Delivered
Timestamp: 2026-04-07 10:15:32 UTC

Payload (What the App Sent)​

The original data sent by the app. This is opaque to Relay — whatever the app sent is displayed exactly:

{
  "event": "comment.mention",
  "message": "@athena summarize this task",
  "sender": {
    "id": "user-456",
    "name": "Christian Garcia"
  },
  "task_id": "task-123",
  "task_title": "Q2 Roadmap Review",
  "project": "Smiling Group Platform"
}

Why it matters: This shows exactly what context was provided to the agent. If the agent's response seems off-topic, check the payload to see if the right data was included.

Reply (What the Agent Sent)​

The agent's response, either as plain text or structured data:

Here's a summary of the Q2 Roadmap Review:

The task focuses on planning the next quarter's product roadmap. Key areas include:
1. Feature prioritization
2. Technical debt reduction
3. Team capacity planning

Discussion has centered on balancing new features with stability improvements...

If the status is "failed" or "rejected": The reply field may be empty or show an error message instead.

Session Key​

The session key used for this event:

Session Key: relay:portal:task-123

This is how the agent's plugin identifies the conversation thread. All events with the same thread ID use the same session, maintaining conversation continuity.

Timeline​

A detailed breakdown of what happened:

Event Created:    2026-04-07 10:15:00 UTC
Forwarded to Agent: 2026-04-07 10:15:01 UTC (+1s)
Reply Started:    2026-04-07 10:15:02 UTC (+2s)
Reply Completed:  2026-04-07 10:15:32 UTC (+32s)
Delivered to App: 2026-04-07 10:15:32 UTC (+32s)

This shows exactly where time was spent:

  • How long it took Relay to forward the event (~1s)
  • How long the agent took to start responding (~1s more)
  • How long the full response took (~30s of the 32s total)

Use this to diagnose slowdowns:

  • If agent reply is slow → investigate agent service performance
  • If relay forwarding is slow → network or connection issue
  • If total time is slow but individual steps are fast → check end-to-end network latency

Metadata​

Additional details about the event:

{
  "tokens_used": 1500,
  "model": "claude-sonnet",
  "latency_ms": 32000,
  "retry_count": 0,
  "error": null
}
  • tokens_used: How many AI tokens the agent used (if reported)
  • model: Which AI model the agent used
  • latency_ms: Total end-to-end latency in milliseconds
  • retry_count: If the event was retried (typically 0)
  • error: Error message if status is "failed" or "rejected"

Common Debugging Scenarios​

Scenario: Agent Is Offline​

You notice events are stuck in "pending" status.

Diagnosis:

  1. Go to Agents page
  2. Check the agent's Connection Status
  3. If "Disconnected," the agent service is not connected to Relay

Solution:

  1. Check the agent service logs for connection errors
  2. Verify the agent token is correct (hasn't been rotated without updating the service config)
  3. Verify the agent service has outbound WSS access to api.relay.ckgworks.com
  4. Restart the agent service

Scenario: App Is Being Rejected​

You see "rejected" status for events from a specific app.

Diagnosis:

  1. Click the event to see the rejection reason
  2. If PERMISSION_DENIED: App is not allowlisted
  3. If AGENT_NOT_FOUND: Agent doesn't exist or is inactive

Solution (for PERMISSION_DENIED):

  1. Go to the agent's Allowlist tab
  2. Click Add App and select the app
  3. Events from that app will now be delivered

Solution (for AGENT_NOT_FOUND):

  1. Go to Agents page
  2. Verify the agent exists and is active
  3. If not, check with the agent team or restart the service

Scenario: Agent Replies Are Slow​

Events are delivering, but latency is very high (> 10s).

Diagnosis:

  1. Click the event
  2. Check the Timeline to see where time is spent
  3. Is the agent taking a long time? (high "reply" duration)
  4. Or is the network slow? (high "forwarding" duration)

Solution (slow agent):

  1. Check the agent service — is it under heavy load?
  2. Check if the AI model being used is slow (GPT-4 is slower than Sonnet)
  3. Check if the context being sent is very large (causing the model to be slow)

Solution (slow network):

  1. Check your network connection
  2. Verify the Relay API is responding normally (check uptime/status page)
  3. Try a different geographic location if possible

Scenario: High Failure Rate​

Many events have "failed" status.

Diagnosis:

  1. Filter by Status: failed
  2. Click a few events to see the error messages
  3. Are all failures from one agent? Or multiple?
  4. Are the errors consistent or varied?

Solution (agent-specific):

  1. Go to Agents page and check the agent's connection status
  2. If offline, reconnect the agent service
  3. Check the agent service logs for crashes or errors
  4. Verify the agent has sufficient resources (CPU, memory)

Solution (varied errors):

  1. Check the Relay API status
  2. Look at the event timestamps — did failures happen at a specific time?
  3. Check if there was a service restart or deployment

Exporting and Monitoring​

Exporting Events​

The event log table may support export:

  • Click Export (if available)
  • Choose format: CSV, JSON
  • Use for external analysis, compliance records, or integration with monitoring systems

Setting Up Alerts (Future)​

In a future version, Relay may support alerting:

  • "Alert if any event fails"
  • "Alert if agent is offline for more than 5 minutes"
  • "Alert if rejection rate exceeds threshold"

For now, check the event log regularly.

Best Practices​

1. Monitor Event Traffic Regularly​

  • Check the event log daily or weekly
  • Look for unexpected rejections or failures
  • Ensure apps and agents you expect to be active are working

2. Use Filters to Diagnose Issues​

  • "Show me all failures from Portal" → debug Portal integration
  • "Show me all rejections to Athena" → check allowlist
  • "Show me pending events" → detect slow agents
  • Are events getting slower over time?
  • Did a recent deployment introduce latency?
  • Is it consistent across agents or specific to one?

4. Archive Old Logs​

  • Relay retains event logs indefinitely (currently)
  • For compliance or analysis, export logs periodically
  • Clean up test events from development/staging

5. Correlate with Application Logs​

  • When an event fails, check both Relay logs and your app logs
  • Verify your app is handling Relay errors correctly
  • Ensure your app is reconnecting to Relay if disconnected

Summary​

  • View all events sent through Relay for your organization
  • Filter by app, agent, or status to find what you need
  • Click events for details: payload, reply, timeline, metadata
  • Diagnose issues using the timeline and status information
  • Monitor trends to catch problems early

Next steps: