Skip to content

feat(tracing): add breadcrumbs/event trail system#50

Merged
Naoray merged 1 commit intomainfrom
feat/breadcrumb-system
Feb 8, 2026
Merged

feat(tracing): add breadcrumbs/event trail system#50
Naoray merged 1 commit intomainfrom
feat/breadcrumb-system

Conversation

@Naoray
Copy link
Copy Markdown
Owner

@Naoray Naoray commented Feb 8, 2026

Summary

  • Adds a BreadcrumbCollector that captures an ordered trail of log messages and cache events leading up to an error, providing pre-error context similar to Sentry/Flare breadcrumbs
  • Implements a ring buffer (configurable limit, default 40) that stores timestamped entries with category, message, and optional metadata
  • Formats breadcrumbs as a readable markdown table in GitHub issues/comments via BreadcrumbFormatter

Changes

New Files

  • src/Tracing/BreadcrumbCollector.php -- Ring buffer collector listening to MessageLogged (skips error+), CacheHit, CacheMissed
  • src/Issues/Formatters/BreadcrumbFormatter.php -- Markdown table formatter for breadcrumb data
  • tests/Tracing/BreadcrumbCollectorTest.php -- 15 tests covering collection, filtering, ring buffer, config
  • tests/Issues/Formatters/BreadcrumbFormatterTest.php -- 7 tests covering formatting, escaping, edge cases

Modified Files

  • config/github-monolog.php -- Added breadcrumbs toggle and breadcrumb_limit setting
  • src/Tracing/EventHandler.php -- Register breadcrumb event listeners
  • src/Tracing/ContextProcessor.php -- Collect breadcrumbs on log time
  • src/Issues/TemplateRenderer.php -- Add {breadcrumbs} replacement with BreadcrumbFormatter
  • src/Issues/SectionMapping.php -- Add breadcrumbs section mapping and standalone flag pattern
  • src/Issues/Formatters/ContextFormatter.php -- Exclude breadcrumbs from generic context
  • src/GithubMonologServiceProvider.php -- Add breadcrumbs to context dehydration
  • resources/views/issue.md -- Add breadcrumbs section
  • resources/views/comment.md -- Add breadcrumbs section

Test plan

  • BreadcrumbCollector collects log messages (debug, info, notice, warning)
  • BreadcrumbCollector collects cache hit and miss events
  • Error/critical/alert/emergency log levels are excluded
  • Ring buffer caps at configured limit (keeps latest entries)
  • Default limit of 40 applies when not configured
  • Collector respects enabled/disabled config toggle
  • Breadcrumbs are pushed to Context on collect()
  • Chronological order preserved across mixed event types
  • BreadcrumbFormatter produces valid markdown table
  • Pipe characters in messages are escaped
  • Empty breadcrumbs render as empty string (section removed from template)
  • Breadcrumbs appear in rendered issue and comment templates
  • Breadcrumbs excluded from generic context section
  • PHPStan passes with zero errors
  • All 303 tests pass

Closes #39

🤖 Generated with Claude Code

Add a breadcrumb collector that captures an ordered trail of events
(log messages and cache hits/misses) leading up to an error, giving
developers pre-error context similar to Sentry/Flare breadcrumbs.

- BreadcrumbCollector: ring buffer with configurable limit (default 40),
  listens to MessageLogged (skipping error+), CacheHit, CacheMissed
- BreadcrumbFormatter: renders breadcrumbs as a markdown table
- Integrated into EventHandler, ContextProcessor, TemplateRenderer,
  SectionMapping, and both issue/comment templates
- Added breadcrumbs to context dehydration and ContextFormatter exclusion
- Config: tracing.breadcrumbs (toggle) and tracing.breadcrumb_limit

Closes #39

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@Naoray Naoray force-pushed the feat/breadcrumb-system branch from d74b60f to 169ed09 Compare February 8, 2026 13:12
@Naoray Naoray merged commit f25d19e into main Feb 8, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add breadcrumbs/event trail system for pre-error context

1 participant