> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor hosted agent logs with the Azure Developer CLI

> Stream and inspect Microsoft Foundry hosted agent logs with azd to troubleshoot sessions, container events, and runtime behavior.

Stream and inspect logs from your deployed Microsoft Foundry hosted agent for troubleshooting and observability. You learn how to view console logs, stream in real time, inspect system events, filter by session, and recognize common log patterns.

## Prerequisites

* A deployed hosted agent. To deploy one, see [Deploy a hosted agent](/agents/deploy-hosted-agent).
* The azd Foundry extensions installed. For installation steps, see [Install the azd Foundry extensions](/developer-tools-and-integrations/install-cli-foundry-extensions).
* An authenticated Azure Developer CLI session. Run `azd auth login` if needed.
* For session-specific logs, a session ID from an `azd ai agent invoke` response. To invoke an agent, see [Invoke a hosted agent with the Azure Developer CLI](/agents/invoke-hosted-agent).

## View recent console logs

* Fetch recent console logs:

  ```bash theme={null}
  azd ai agent monitor
  ```

  This command fetches recent console logs, including stdout and stderr, from the agent's last invoke session. If no session exists, it streams container logs. The command exits after fetching the available logs. Use `--follow` to stream continuously.

## Stream logs in real time

* Stream logs continuously:

  ```bash theme={null}
  azd ai agent monitor --follow
  ```

  Press **Ctrl+C** to stop. This is the most useful mode for debugging. Run it in one terminal while sending requests in another.

## View system event logs

* Show container lifecycle events instead of console output:

  ```bash theme={null}
  azd ai agent monitor --type system
  ```

  Use system event logs to diagnose container crashes, restart loops, and resource issues.

## View session-specific logs

* Filter logs to a specific agent session:

  ```bash theme={null}
  azd ai agent monitor --session-id <session-id>
  ```

* Combine with `--follow` for real-time streaming:

  ```bash theme={null}
  azd ai agent monitor --session-id <session-id> --follow
  ```

  To find session IDs, check the output of `azd ai agent invoke`. It prints the session ID for each request.

## Control log length

* Show the last 100 lines:

  ```bash theme={null}
  azd ai agent monitor --tail 100
  ```

  The range is 1-300. The default is 50.

## Monitor a specific agent

* In multi-service projects, pass the agent name:

  ```bash theme={null}
  azd ai agent monitor my-agent
  ```

## Recognize common log patterns

| Pattern                                 | Meaning                                              | Action                                                                                              |
| --------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `Listening on 0.0.0.0:8088`             | Agent started successfully.                          | None needed.                                                                                        |
| `AuthenticationError`                   | The agent's Entra Agent Identity can't authenticate. | Check RBAC roles.                                                                                   |
| `ModelNotFound`                         | Model deployment name mismatch.                      | Verify the deployment name in `azure.yaml` matches the Foundry portal.                              |
| `ResourceNotFound`                      | Foundry endpoint mismatch.                           | Check `FOUNDRY_PROJECT_ENDPOINT` value.                                                             |
| Container restart events in system logs | Crash loop.                                          | Check code for unhandled exceptions; consider increasing container resource limits in `azure.yaml`. |
| `TimeoutError`                          | Request took too long.                               | Check model responsiveness; increase timeout on invoke.                                             |

## Follow a debugging workflow

A typical debugging session looks like this:

1. Stream logs in one terminal:

   ```bash theme={null}
   azd ai agent monitor --follow
   ```

2. Send a request in another terminal:

   ```bash theme={null}
   azd ai agent invoke "Test message"
   ```

3. Watch the logs for error patterns or unexpected behavior.

4. Check system events if the agent seems unresponsive:

   ```bash theme={null}
   azd ai agent monitor --type system
   ```

For a comprehensive debugging workflow, see [Debug a hosted agent](/agents/debug-hosted-agent).

## Related content

* [Debug a hosted agent](/agents/debug-hosted-agent) for step-by-step diagnostic workflows.
* [Test a hosted agent](/agents/test-hosted-agent) for validation strategies before production.
* [Isolate hosted agent sessions per user](/agents/isolate-sessions-per-user) for logs in isolated sessions.