Trailbeam documentation

When someone asks "what happened to this message?", the honest answer is usually scattered across three services' logs and a CloudWatch graph. Trailbeam puts it in one place. Hooks in your services record every SQS call per message, and Trailbeam, one process you run yourself, turns them into a timeline:

1. 12:00:01.204Sentorders-api · SendMessage
2. 12:00:01.230Received, delivery 1worker-a · receive count 1
3. inferredVisibility timeout expiredafter delivery 1, before delivery 2
4. 12:00:11.402Received, delivery 2worker-b · receive count 2
5. 12:00:11.610Deletedworker-b · delivery 2 · final
6. 12:00:13.118Delete rejectedworker-a · delivery 1 · too late

That message ran twice. Worker A was too slow, SQS handed the message to worker B, and A's late delete bounced. Every line says who recorded it, and the one step nobody could record is marked inferred.

Three things Trailbeam will not do#

• Touch your queues. Trailbeam makes no SQS calls of its own. The hooks only observe the calls your code already makes, and Trailbeam makes no AWS calls at all, so it can never raise a receive count.
• Read your messages. Hooks never read bodies or message attributes, and never export a receipt handle.
• Guess. Two steps are drawn in order only when an observed fact proves it: the hosts' clocks, the call order inside one process, SQS's receive count or SQS's timestamps. Otherwise they share a box marked concurrent, order unknown.

Trailbeam 0.1 is a pre-release: the repository is private and nothing is published yet. If you're weighing it up, start with Is Trailbeam a good fit?. It's candid about where Trailbeam falls short.