Skip to main content
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

Description: Add a routine breadcrumb.Example:
conv.log.info("Validated inputs", validation_passed=True)
Description: Flag a soft failure or approaching limit.Example:
conv.log.warning(
  "Rate limit nearing cap",
  vendor="maps_api", window_remaining=5, threshold=10
)
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

Last modified on March 22, 2026