> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor and Troubleshoot Agents

> Learn how to inspect Orca agent health, review logs, and stream diagnostics to messaging topics.

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

<Note title="Before you start">
  Install and configure `snctl` as described in [Set up client tools](/agent-engine/agents-setup#set-up-client-tools) so the commands below can authenticate to your organization.
</Note>

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

```bash theme={null}
snctl agents status \
  --tenant public \
  --namespace support \
  --name concierge
```

Example output:

```json theme={null}
{
  "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](https://console.streamnative.cloud/?defaultMethod=signup).
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`.

<Note title="Note">
  This example assumes you have [installed snctl](/tools/cli/snctl/snctl-overview#install-snctl) and [initialized snctl configurations](/tools/cli/snctl/snctl-overview#initialize-snctl-configurationn).
</Note>

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.

```bash theme={null}
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.