Skip to content

Debugging

The AI Context module includes optional debug logging to help troubleshoot context selection, rendering, and scope matching issues.

Enabling debug logging

  1. Navigate to /admin/config/ai/context/settings/general
  2. Expand the Debugging section
  3. Check the Enable debug logging checkbox
  4. Save the configuration

Viewing debug logs

Debug information is written to the standard Drupal log:

  1. Go to Reports > Recent log messages (/admin/reports/dblog)
  2. Filter by type: ai_context

Or using Drush:

ddev exec drush watchdog:show --type=ai_context

What gets logged

Context selection (AiContextSelector)

  • Scope index prefilter counts (candidate IDs vs. published IDs)
  • Number of published items loaded across chunks and always-include count
  • Item count after priority-group merge
  • One final selection summary with the consumer ID, selected item IDs, truncated item IDs, and token usage
  • Warning when items are truncated due to token limits
  • Warning when TEXT_RENDERED text exceeds configured max_tokens

The final debug summary uses this format:

AiContextSelector: Selection summary; consumer=CONSUMER; selected=[IDS]; truncated=[IDS]; tokens=USED/MAX.

It is emitted once per completed selection only when debug logging is enabled. The summary does not include task text, context content, provider responses, or IDs rejected by access checks.

See Selector pipeline events for when those overrides are allowed.

Scope scoring and hard context filtering run inside the selector via AiContextScopeResolver but do not emit separate debug messages.

Context rendering (AiContextRenderer)

  • Items skipped when the token budget is exhausted before or during rendering

Subcontext resolution (AiContextSubcontextResolver)

Conditional selection fails closed: when a decision cannot be completed, conditional children are excluded while required children remain selected. The resolver writes one privacy-safe warning with the parent Context Item ID, affected child count, and one of these reason categories:

  • missing_provider: no provider/model is configured, or the configured provider plugin is unavailable
  • decision_cap_exhausted: the per-request conditional parent limit was reached
  • invalid_response: the provider response is not a JSON list of scalar child IDs
  • unsupported_provider: the provider does not support chat
  • provider_exception: provider creation or execution failed

The warning uses this format:

AiContextSubcontextResolver: Conditional children excluded; parent=PARENT; affected=COUNT; reason=REASON.

Warnings never contain Context Item content, task text, provider-response content, or exception messages. Use the parent ID to inspect configuration, then verify the provider/model, conditional parent limit, and provider logs.

Performance considerations

Debug logging generates significant log entries and may impact performance. Only enable it when actively troubleshooting issues. Remember to disable it when you are done debugging.