Skip to content

Context Collection

Context collection is a powerful feature that helps the AI understand your application better by gathering relevant information from your codebase, logs, and configuration files.

What is Context Collection?

Context collection automatically gathers information about your application to provide better AI analysis and more accurate fixes. The system collects:

  • Code Files: Relevant source code files related to errors
  • Configuration Files: Application configuration (e.g., config.php, package.json, requirements.txt)
  • Log Files: Application logs and error logs
  • Custom Log Paths: Additional log files you specify

How It Works

  1. Automatic Collection: When an error is detected, the connector automatically collects context
  2. Detection snapshot (v2.3+): Connectors on a supported version also capture a small sanitized excerpt of the failing source file at detection time (when the file is readable on the customer host). This snapshot is stored on the error in Patcherly and used for analysis when a live refresh from the site is unavailable (for example during a WordPress theme fatal).
  3. AI Analysis: The collected context is sent to the AI along with the error for better understanding. The system selects an AI prompt template using the site’s optional language/framework (if set), the connector-reported context when present, or the error content.
  4. Improved Fixes: With more context, the AI generates more accurate and appropriate fixes

Automatic Context Collection

The connector automatically collects context from:

  • Error Location: Code files where the error occurred (live HMAC file-content fetch during analysis)
  • Related paths (first pass): Same-directory or one-level parent-relative imports/requires visible in the primary excerpt (capped at 3 files total with traceback frames - no full import-graph crawl)
  • Detection snapshot: Small sanitized primary-file excerpt at ingest when readable (fallback if live fetch fails for that primary path)
  • Configuration / logs: Site environment summary and configured log paths (separate from FILE CONTEXT excerpts)

Plan-based context depth

Context depth is plan-aware via advanced_fixes (Core and Pro; Personal uses the narrower window):

  • Standard (Personal): narrower line window around the failing area; single AI pass
  • Advanced (Core/Pro): wider file windows, richer site environment summary, and optionally one automatic extra-file follow-up when Pass 1 is Not patchable for insufficient context and the model names 1 - 2 project-relative paths

Both tiers still use the same safety and validation rules. The difference is depth and that one entitled follow-up, not bypassing safeguards.

Line numbers in analysis

When you open Error details → Analysis, source excerpts show absolute line numbers from the original file (L 54| …). The line marked ← ERROR matches the stack trace. Unified diffs in the fix preview use standard @@ hunk headers - line numbers in the excerpt help you confirm the AI is patching the same line PHP/WordPress reported.

Custom Log Paths

You can configure custom log paths to include additional log files in context collection. This is useful for:

  • Application-Specific Logs: Custom log files your application writes to
  • Third-Party Logs: Logs from libraries or services you use
  • Multiple Log Locations: Applications that write logs to multiple locations

Adding Custom Log Paths

  1. Open Sites in your dashboard, expand the site, and click Customize next to Monitored Logs.
  2. Under Add custom log, enter the path (absolute or relative to your app root), optional description, keep Enabled on, then Add.
  3. Manage paths under Custom logs; Detected and Preset lists are read-only inventory.

Full steps and path-safety rules: Custom log paths.

Log Path Requirements

  • Path Format: Can be absolute (e.g., /var/log/app.log) or relative to your application root
  • File Access: The connector must have read permissions for the log file
  • File Size: Very large log files may be truncated (last N lines collected)
  • Encoding: Log files should be UTF-8 encoded

Plan features

Custom log paths require the Advanced Error Monitoring plan feature (Core and Pro). Without it, the connector monitors the preset log locations for its connector type only - adding custom paths is disabled (upgrade hint on Customize). Check the Pricing page to see if your plan includes it.

Context Refresh

You can manually trigger a context refresh for a site:

  1. From Dashboard
  2. Go to your site's page
  3. Click Refresh Context
  4. Wait for collection to complete

Viewing Collected Context

You can view the collected context for any error:

  1. From Error Details
  2. Open an error in the dashboard
  3. Scroll to Context section
  4. View collected files and logs

Best Practices

  1. Include Relevant Logs: Add log paths that contain useful debugging information
  2. Avoid Sensitive Data: Don't include logs with passwords, API keys, or personal information
  3. Keep Paths Updated: Update log paths if your application structure changes
  4. Monitor File Sizes: Very large log files may slow down context collection
  5. Use Descriptions: Add descriptions to help identify log paths later

Troubleshooting

Context Not Collected

  • Check Permissions: Ensure the connector has read access to log files
  • Verify Paths: Confirm log paths are correct and files exist
  • Check plan features: verify your plan includes Advanced Error Monitoring (Core or Pro)
  • Review Logs: Check connector logs for collection errors

Context Too Large

  • Reduce Log Paths: Disable unnecessary log paths
  • Truncate Logs: The system automatically truncates very large files
  • Check File Sizes: Review log file sizes and consider log rotation

Context Outdated

  • Manual Refresh: Trigger a manual context refresh
  • Automatic Refresh: Context is automatically refreshed when errors occur
  • Check Collection Status: Review context collection status in site settings