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

# Telemetry

> Heartbeats, usage tracking, and auto-tracking wrappers

## heartbeat()

Send a single heartbeat to confirm the agent is alive. Called automatically by `start_heartbeat()`, but you can also call it manually.

```python theme={null}
client.heartbeat()
```

The heartbeat updates the agent's `last_heartbeat` timestamp and keeps its status as `healthy`. If no heartbeat is received for 2 minutes, the agent status changes to `degraded`. After 5 minutes, it changes to `down`.

## start\_heartbeat()

Start a background thread that sends heartbeats at a regular interval.

```python theme={null}
client.start_heartbeat()
```

The interval is configured via the `heartbeat_interval` constructor parameter (default: 30 seconds). The background thread is a daemon thread that stops automatically when your process exits.

```python theme={null}
# Custom interval
client = MeshAI(api_key="msh_...", agent_name="my-agent", heartbeat_interval=60)
client.register(framework="custom", model_provider="openai")
client.start_heartbeat()  # Sends every 60 seconds
```

## stop\_heartbeat()

Stop the background heartbeat thread started by `start_heartbeat()`.

```python theme={null}
client.stop_heartbeat()
```

## track\_usage()

Report a single LLM usage event: tokens consumed, model used, and optional cost.

```python theme={null}
client.track_usage(
    model_provider="openai",
    model_name="gpt-4o",
    input_tokens=1500,
    output_tokens=800,
    request_type="chat.completions",
    cost_usd=0.035,
)
```

<ParamField path="model_provider" type="string" required>
  LLM provider: `openai`, `anthropic`, `google`, `nvidia`, `bedrock`
</ParamField>

<ParamField path="model_name" type="string" required>
  Model identifier (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
</ParamField>

<ParamField path="input_tokens" type="integer" required>
  Number of input/prompt tokens
</ParamField>

<ParamField path="output_tokens" type="integer" required>
  Number of output/completion tokens
</ParamField>

<ParamField path="request_type" type="string">
  Type of request (e.g., `chat.completions`, `embeddings`)
</ParamField>

<ParamField path="cost_usd" type="float">
  Explicit cost in USD. If omitted, MeshAI calculates cost based on model pricing tables.
</ParamField>

## Auto-Tracking Wrappers

Instead of calling `track_usage()` manually, use framework wrappers that capture usage automatically:

```python theme={null}
# OpenAI
from meshai.integrations.openai import wrap_openai
oai = wrap_openai(openai.OpenAI(), meshai=client)

# Anthropic
from meshai.integrations.anthropic import wrap_anthropic
ant = wrap_anthropic(anthropic.Anthropic(), meshai=client)

# CrewAI
from meshai.integrations.crewai import MeshAICrewCallback
crew = Crew(callbacks=[MeshAICrewCallback(meshai=client)])

# LangChain
from meshai.integrations.langchain import MeshAILangChainCallback
chain.invoke(input, config={"callbacks": [MeshAILangChainCallback(meshai=client)]})

# AutoGen
from meshai.integrations.autogen import MeshAIAutoGenCallback
agent = AssistantAgent(callbacks=[MeshAIAutoGenCallback(meshai=client)])
```

See the [Framework Guides](/framework-guides/openai) for complete examples.

## shutdown()

Flush all pending heartbeat and usage events, stop the background heartbeat, and close the HTTP transport. Called automatically on process exit via `atexit`, but you can call it manually to flush and close early.

```python theme={null}
client.shutdown()
```