Monitor and Troubleshoot Agents

StreamNative Cloud surfaces health and diagnostics for every Orca agent so you can debug issues quickly. Use the CLI for live status checks, review logs through the console, and stream log data to topics when you need deeper analysis.

View agent status

Install and configure snctl as described in Set up client tools so the commands below can authenticate to your organization.

Run snctl agents status with the agent’s tenant, namespace, and name to fetch its current state:

snctl agents status \
  --tenant public \
  --namespace support \
  --name concierge

Example output:

{
  "numInstances": 1,
  "numRunning": 1,
  "instances": [
    {
      "instanceId": 0,
      "status": {
        "running": true,
        "error": "",
        "numRestarts": 0,
        "numReceived": 128,
        "numSuccessfullyProcessed": 128,
        "numUserExceptions": 0,
        "latestUserExceptions": [],
        "numSystemExceptions": 0,
        "latestSystemExceptions": [],
        "averageLatency": 135,
        "lastInvocationTime": 1709855312000,
        "workerId": "orcaworker-1"
      }
    }
  ]
}

Key fields to watch:

running: Confirms the runtime loop is healthy. A false value indicates the instance stopped and requires attention.
numRestarts: Counts automatic restarts. Frequent restarts suggest initialization errors or crashes.
numUserExceptions and latestUserExceptions: Surface issues thrown by your agent code.
numSystemExceptions and latestSystemExceptions: Capture platform-level errors such as connectivity or serialization problems.
averageLatency and lastInvocationTime: Help validate that requests are being processed on schedule.

Combine the status output with snctl agents restart or snctl agents trigger (when supported) to validate fixes before returning agents to production traffic.

Inspect logs and exceptions in StreamNative Cloud Console

The StreamNative Cloud Console provides a real-time view of agent activity.

Log in to StreamNative Cloud Console.
In the left navigation, open Agents panel.
Select the agent you deployed to open its detail page. Review the status metrics for quick health insight.
Switch to the Logs tab for streaming log output.

Console views combine status, logs, and configuration so you can verify rollouts, confirm tool configs, and observe runtime behavior without leaving the browser.

View the agent logs using `snctl`

This section describes how to view agent logs using snctl.

This example assumes you have installed snctl and initialized snctl configurations.

You can run the snctl logs command to view logs for a specific agent. This table outlines the configuration options that are used for viewing agent logs. For details about all supported fields, you can use the snctl logs -h command to list more information.

Option	Descriptions
`-c` or `--cluster`	The name of your Pulsar cluster where the agent is created.
`-p` or `--component`	The type of component to monitor. Available options are `function`, `sink`, `source`, ‘kafka-connect’ and ‘agent-function’.
`-f` or `--follow`	Continuously list the agent log history.
`-h` or `--help`	Show usage information about the `snctl logs` command.
`-i` or `--instance`	The name of your Pulsar instance where the agent is created.
`--name`	The name of your agent.
`-o` or `--organization`	The name of your organization where the agent is created.
`--previous`	Print the logs that are generated before the configured timestamp.
`--pulsar-tenant`	The name of your Pulsar tenant where the agent is created.
`--pulsar-namespace`	The name of your Pulsar namespace where the agent is created.
`--since`	List logs more recent than the specific time. Available units are `second`, `minute`, and `hour`, such as `24h`.
`-s` or `--size`	Specify how many lines of recent logs to display.
`--timestamp`	Include timestamps on each line in the log output.

The following command example shows how to view up to 60 lines of the agent-func agent’s logs within the last 5 hours.

snctl logs --since 5h --organization sndev --instance aws --cluster aws --name agent-func --pulsar-tenant public --pulsar-namespace default -p agent-function -f -s 60

You should see the agent logs output.

Overview

Get Started

Develop Agents

Operations

Integrations

MCP

View agent status

Inspect logs and exceptions in StreamNative Cloud Console

View the agent logs using `snctl`

​View agent status

​Inspect logs and exceptions in StreamNative Cloud Console

​View the agent logs using snctl

View agent status

Inspect logs and exceptions in StreamNative Cloud Console

View the agent logs using `snctl`