Skip to main content
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.
  1. Log in to StreamNative Cloud Console.
  2. In the left navigation, open Agents panel.
  3. Select the agent you deployed to open its detail page. Review the status metrics for quick health insight.
  4. 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.
OptionDescriptions
-c or --clusterThe name of your Pulsar cluster where the agent is created.
-p or --componentThe type of component to monitor. Available options are function, sink, source, ‘kafka-connect’ and ‘agent-function’.
-f or --followContinuously list the agent log history.
-h or --helpShow usage information about the snctl logs command.
-i or --instanceThe name of your Pulsar instance where the agent is created.
--nameThe name of your agent.
-o or --organizationThe name of your organization where the agent is created.
--previousPrint the logs that are generated before the configured timestamp.
--pulsar-tenantThe name of your Pulsar tenant where the agent is created.
--pulsar-namespaceThe name of your Pulsar namespace where the agent is created.
--sinceList logs more recent than the specific time. Available units are second, minute, and hour, such as 24h.
-s or --sizeSpecify how many lines of recent logs to display.
--timestampInclude 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.
⌘I