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

# Observability & Logs

Charm records execution data so builders can debug and improve published agents.

## What You Can Inspect

* Run status.
* Runtime logs.
* Status events.
* Errors.
* Token or usage metadata when available.
* Revenue and billing events where applicable.

## CLI Logs

Use:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm logs --path . --limit 50
```

This is the fastest way to inspect recent cloud behavior from your terminal.

## Studio

Charm Studio provides a web dashboard for run history, usage, debugging, and revenue visibility.

## Debugging Production Issues

When a cloud run fails:

1. Confirm the same input works locally.
2. Run `charm validate`.
3. Check logs.
4. Confirm required environment variables or OAuth connections.
5. Test in Docker if the issue looks runtime-specific.

## Telemetry Architecture

Charm utilizes an event-driven `TelemetryManager` built into the `CharmEmitter` system. When an agent runs, the SDK dispatches a standard set of lifecycle events (e.g., token generation, tool usage, errors) to the internal event bus.

By default, these events are serialized to `stdout` where the Charm Cloud Runner captures them and broadcasts them to end-users via Server-Sent Events (SSE).

### Pluggable Exporters

To support enterprise observability, Charm allows registering external Telemetry Exporters via Python entry points. The `TelemetryManager` iterates through all activated plugins defined in your `charm.yaml` and executes their lifecycle hooks in isolation, ensuring that a crash in a telemetry exporter does not halt your agent's execution.

### Standard Lifecycle Hooks

The following methods are dispatched by the `BaseTelemetryExporter` interface:

* `on_run_start(run_id, inputs)`: Fired when an agent begins execution.
* `on_run_end(run_id, outputs)`: Fired upon successful completion.
* `on_error(run_id, error)`: Fired if the agent crashes globally.
* `on_tool_start(tool_name, input_str)`: Fired when an agent invokes a tool/skill.
* `on_tool_end(tool_name, output)`: Fired when a tool returns a result.
* `on_tool_error(tool_name, error)`: Fired if a tool invocation raises an exception.
* `on_llm_new_token(token)`: Fired as the LLM streams characters.
* `on_agent_action(tool, tool_input)`: Generic action tracing.

> **Note:** If you want to build your own exporter, see the [Custom Telemetry Exporters Guide](/guides/telemetry-exporters).

## Access Control

Execution logs and telemetry data are only visible to authorized project owners and maintainers in the Charm Studio.