Conversation log

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

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.

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:

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

log.warning(message)

Description: Flag a soft failure or approaching limit.

Example:

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:

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.

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:

{
  "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

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

Retries

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

Companion redaction

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
• Conversation utilities
• conv.log_api_response() – log full HTTP responses from API integrations to Conversation Review → Diagnosis