> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Monitor your agents

Astro AI automatically monitors agents that interact with common AI model providers. After you deploy an agent, its token usage, tool calls, and latency appear on the [Insights](https://astropods.com/insights) page. For deeper observability, Astro AI provides adapters for common frameworks.

## Framework guides

#### [AI SDK](/monitor-ai-sdk)

Send Vercel AI SDK telemetry to the dashboard.

#### [Mastra](/monitor-mastra)

Instrument Mastra agents automatically.

#### [Claude Agent SDK](/monitor-claude-agent-sdk)

Instrument the Claude Agent SDK with a drop-in package.

## Manually attaching observability

When an adapter isn't available for your framework, you can instrument an agent manually using standard OpenTelemetry. Every deployed agent container receives these environment variables automatically:

| Variable                      | Purpose                                                        |
| ----------------------------- | -------------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP HTTP base URL. Append `/v1/traces` for the traces signal. |
| `ASTRO_AGENT_NAME`            | Use as OpenTelemetry `service.name`.                           |
| `ASTRO_AGENT_BUILD`           | Use as OpenTelemetry `service.version`.                        |

`OTEL_EXPORTER_OTLP_ENDPOINT` is unset during local development. Guard your instrumentation on the variable so the agent runs cleanly in both environments.

### Node.js

#### Install the OpenTelemetry SDK

Install the SDK and the OTLP HTTP trace exporter:

```bash
bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
```

#### Initialize the SDK

Initialize the SDK at the entry point of your agent, before any other imports that you want traced:

```typescript
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { resourceFromAttributes } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";

if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
  new NodeSDK({
    resource: resourceFromAttributes({
      [ATTR_SERVICE_NAME]: process.env.ASTRO_AGENT_NAME ?? "agent",
      [ATTR_SERVICE_VERSION]: process.env.ASTRO_AGENT_BUILD ?? "dev",
    }),
    traceExporter: new OTLPTraceExporter({
      url: `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
    }),
  }).start();
}
```

#### Emit spans

With the SDK running, emit spans wherever you want them — see the [OpenTelemetry tracing API](https://opentelemetry.io/docs/languages/js/instrumentation/#traces) for the span API and the [auto-instrumentation packages](https://opentelemetry.io/docs/languages/js/libraries/) for HTTP, fetch, and other off-the-shelf coverage.

#### Verify

Deploy the agent, send it a message, then open the agent's detail page in the Astro AI dashboard. Traces appear within \~30 seconds.