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

# Logging

> Show, filter and shape logging from the agent, providers, models and mappers.

The dartantic\_ai package implements a comprehensive logging system using the
`logging` package. All logging follows a hierarchical naming convention to
provide clear operational visibility and debugging capabilities.

## Basic Usage

By default, dartantic logging is disabled. You can enable logging by setting the
`loggingOptions` property of the `Agent` class to an instance of the
`LoggingOptions` class:

```dart theme={null}
// Enable logging
Agent.loggingOptions = const LoggingOptions();

final agent = Agent('openai');
await agent.send('Hello!');
// See formatted logs in console
```

## Logging Levels

The `loggingOptions` property of the `Agent` class can be set to a
`LoggingOptions` object to configure the logging level.

```dart theme={null}
import 'package:logging/logging.dart';

// Development - verbose output
Agent.loggingOptions = LoggingOptions(level: Level.FINE);

// Production - minimal output  
Agent.loggingOptions = LoggingOptions(level: Level.WARNING);
```

| Level           | Use Case    | Output   |
| --------------- | ----------- | -------- |
| `Level.FINE`    | Development | Verbose  |
| `Level.INFO`    | General     | Moderate |
| `Level.WARNING` | Production  | Minimal  |

## Filter by String

You can filter logging by a string by setting the `filter` property of the
`LoggingOptions` class to a string that matches the logging output:

```dart theme={null}
// Only OpenAI logs
Agent.loggingOptions = LoggingOptions(
  filter: 'openai',
  onRecord: (record) => print('OpenAI: ${record.message}'),
);

// Only HTTP retry logs
Agent.loggingOptions = LoggingOptions(filter: 'http');
```

## Environment Variable

Set logging without touching code by exporting `DARTANTIC_LOG_LEVEL` before you
run your app. Any value accepted by `package:logging` works (`INFO`, `FINE`,
`WARNING`, `OFF`, etc.):

```bash theme={null}
DARTANTIC_LOG_LEVEL=FINE dart run packages/dartantic_ai/example/bin/logging.dart
```

At startup `Agent.loggingOptions` reads this environment variable and adopts
the requested logging level automatically. You can still override it in code if
you need more granular control.

## Examples

* [Logging](https://github.com/csells/dartantic_ai/blob/main/packages/dartantic_ai/example/bin/logging.dart)

## Next Steps

* [Automatic Retry](/automatic-retry) - Handle rate limits
* [Usage Tracking](/usage-tracking) - Monitor costs