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

# Conversation log

> Write structured log entries visible in Conversation Review diagnostics using conv.log methods.

> **Info**
>
> **This page requires Python familiarity.** It covers structured logging from Python functions.

`conv.log` lets your function write small, structured log entries that show up in **Conversation Review → Diagnosis** and in the Conversations API. Use it for breadcrumbs, warnings, and errors. Without logging, function failures are invisible – you cannot debug what you cannot see.

> **Tip**
>
> Logging is part of the core `Conversation` object. It lives on `conv.log`, not `conv.utils`.

## Methods

#### log.info(message)

**Description**: Add a routine breadcrumb.

**Example**:

```python
conv.log.info("Validated inputs", validation_passed=True)
```

#### log.warning(message)

**Description**: Flag a soft failure or approaching limit.

**Example**:

```python
conv.log.warning(
  "Rate limit nearing cap",
  vendor="maps_api", window_remaining=5, threshold=10
)
```

#### log.error(message)

**Description**: Record a handled failure with context.

**Example**:

```python
conv.log.error(
  "CRM upsert failed", status=409, retriable=True, attempt=2
)
```

## PII

Set `is_pii=True` when the message or fields contain personally identifiable information.

```python
conv.log.warning("Caller number captured", user_phone="+123…", is_pii=True)
```

Users without PII permission won't see PII logs in Review or API responses.

## Where it appears

* **Conversation Review → Diagnosis**: grouped under the turn's function event.
* **Conversations API**: returned on function events as `logs.conversation_logger`.

## Entry shape

Each call produces a JSON object like this:

```json
{
  "level": "info|warning|error",
  "content": "Message",
  "is_pii": false,
  "timestamp": "2025-01-01T10:00:00Z",
  "logger": "conversation_logger",
  "...": "any extra key–values you passed"
}
```

## Patterns

**Validation**

```python
conv.log.info("Validation ok", validation_passed=True, missing_fields=[])
```

**Retries**

```python
conv.log.error("Inventory API failed", error_code=500, attempt=1, retriable=True)
```

**Companion redaction**

```python
conv.log.warning("User email captured", email="j***@example.com", is_pii=True)
conv.log.info("User email captured [redacted]")
```

## Best practices

* Keep messages short; put details in fields.
* Log at decision points, not in tight loops.
* Prefer identifiers over payload dumps.
* Default to `is_pii=True` if you're unsure.

## See also

* [Conversation object](/agent-studio/tools/classes-and-objects/object)
* [Conversation utilities](/agent-studio/tools/classes-and-objects/utilities)
* [`conv.log_api_response()`](/agent-studio/tools/classes-and-objects/object#log_api_response) – log full HTTP responses from API integrations to Conversation Review → Diagnosis