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/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)

• Number of published context items found
• Current language for translation
• Items categorized as global, entity-targeted, or regular
• Agent configuration details (assigned items, always include, excluded)
• Assigned context items selected for relevance matching
• Router ranking results
• Final selection with subcontext inclusion
• Rendered text length

Context routing (AiContextRouter)

• Number of candidate context IDs
• Selected routing strategy (keyword or LLM)
• Current language for translation
• Number of published vs. unpublished items
• Number of items ranked

Context rendering (AiContextRenderer)

• Number of context items to render
• Token budget and usage
• Individual item details (title, tokens, content)
• Items skipped due to token budget
• Final token count and character length

Scope matching (AiContextScopeMatcher)

• Agent scope subscriptions
• Item rejection by hard filters
• Scope score calculations (with raw score breakdown)
• Filter results (items filtered vs. total)

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.