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

# Monitor

# Monitor

The Monitor class buffers traces and spans and flushes them to the Adaline API in the background. It follows the OpenTelemetry error handling principle: telemetry failures never propagate to your application. Items that fail after retries are dropped and counted, not stored.

Create a Monitor via [`adaline.init_monitor()`](/docs/reference/sdk/v2/python/classes/adaline#init_monitor).

## Properties

| Property                 | Type                                                              | Description                                                                                                                                              |
| ------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `buffer`                 | `list`                                                            | Entries waiting to be flushed. Each item is a [`BufferedEntry`](/docs/reference/sdk/v2/python/types/BufferedEntry) with `ready`, `data`, and `category` keys. |
| `sent_count`             | `int`                                                             | Total number of items successfully sent to the API. Starts at `0`.                                                                                       |
| `dropped_count`          | `int`                                                             | Total number of items dropped due to errors or buffer overflow. Starts at `0`.                                                                           |
| `default_content`        | [`LogSpanContent`](/docs/reference/sdk/v2/python/types/LogSpanContent) | Fallback span content when none is provided. Defaults to `LogSpanOtherContent(type="Other", input="{}", output="{}")`.                                   |
| `flush_interval_seconds` | `int`                                                             | Seconds between automatic background flushes.                                                                                                            |
| `max_buffer_size`        | `int`                                                             | Maximum buffered items before oldest entries are dropped.                                                                                                |
| `project_id`             | `str`                                                             | The project ID associated with this monitor.                                                                                                             |

## Methods

### log\_trace

Creates a new [Trace](/docs/reference/sdk/v2/python/classes/trace) and appends it to the buffer. This is a synchronous method.

```python theme={null}
trace = monitor.log_trace(
    name="Chat Completion",
    status="unknown",
    session_id="user-session-123",
    reference_id=None,
    tags=["production", "v2"],
    attributes={"user_id": "123", "model": "gpt-4"}
)
```

#### Parameters

<ParamField body="name" type="str" required>
  Display name for the trace.
</ParamField>

<ParamField body="status" type="str" optional default="unknown">
  Trace status ([`TraceStatus`](/docs/reference/sdk/v2/python/types/TraceStatus)). One of: `"success"`, `"failure"`, `"aborted"`, `"cancelled"`, `"pending"`, `"unknown"`.
</ParamField>

<ParamField body="session_id" type="str | None" optional>
  Optional session identifier for grouping related traces.
</ParamField>

<ParamField body="reference_id" type="str | None" optional>
  Client-side unique identifier. If omitted, a UUID is auto-generated.
</ParamField>

<ParamField body="tags" type="list[str] | None" optional>
  Optional list of string tags.
</ParamField>

<ParamField body="attributes" type="dict[str, Any] | None" optional>
  Optional key-value metadata. Values are wrapped in [`LogAttributesValue`](/docs/reference/sdk/v2/python/types/LogAttributesValue) automatically.
</ParamField>

**Returns:** A new [Trace](/docs/reference/sdk/v2/python/classes/trace) instance.

***

### flush

Manually flushes all ready items from the buffer to the API. Sends each ready trace or span concurrently. Successfully sent items are removed from the buffer. Failed items are dropped and counted via `dropped_count`. Skips if a flush is already in progress. This is an async method.

```python theme={null}
await monitor.flush()
```

***

### stop

Stops the background flush loop and cancels the flush task. This is a synchronous method. After calling `stop()`, no more automatic flushes occur. Call `flush()` before `stop()` if you need to send remaining items.

```python theme={null}
monitor.stop()
```

## Usage Pattern

```python theme={null}
import asyncio
from adaline.main import Adaline

async def main():
    adaline = Adaline()
    monitor = adaline.init_monitor(project_id="my-project")

    trace = monitor.log_trace(name="Request Handler")

    span = trace.log_span(name="LLM Call")
    # ... perform work ...
    span.update({"status": "success"})
    span.end()

    trace.update({"status": "success"})
    trace.end()

    # Flush remaining items before stopping
    await monitor.flush()
    monitor.stop()

    print(f"Sent: {monitor.sent_count}, Dropped: {monitor.dropped_count}")

asyncio.run(main())
```