AWS Builder Center
VaporTrace: Real-Time Distributed Tracing for AWS Event Pipelines

VaporTrace: Real-Time Distributed Tracing for AWS Event Pipelines

A CLI and local dashboard that tunnels live AWS execution traces to your machine over IoT Core, so you can watch an event-driven pipeline run, catch failures instantly, and fix + resubmit them without touching the console.

The problem

Debugging a serverless AWS pipeline usually means opening five CloudWatch log groups and manually lining up timestamps to figure out which invocation caused which failure. There's no single view of a request's actual journey through S3, EventBridge, and Lambda you reconstruct it by hand, every time.

In simple words

Imagine ordering food online. Your order goes through several systems before it reaches the restaurant payment, order routing, kitchen notification, delivery assignment. If your order gets stuck somewhere, the support person has to check five different systems one by one to figure out where it broke.
That's exactly what happens with cloud applications built on AWS. A single action — like a file getting uploaded quietly triggers a chain of services behind the scenes: one service picks it up, passes it to another, which passes it to a third. If something fails in that chain, there's no single place to look you have to hunt through logs from every service involved, one at a time.
VaporTrace gives you one screen that shows the entire journey, live, as it happens — which service ran, how long it took, and exactly where and why it broke, in plain English, not a wall of logs.

The stack

  • AWS CDK infrastructure as code for the whole thing
  • S3 sample event producer
  • EventBridge, with Archive + Replay routes events, keeps a 7-day replay window
  • Lambda (×2, active X-Ray tracing enabled) a forwarder and a business-logic processor
  • IoT Core used unusually here, as an MQTT tunnel carrying live events out of the AWS account to a local machine over TLS
  • AWS X-Ray real distributed tracing, cross-verifying our own trace model
  • Node.js CLI + Next.js dashboard (React Flow) the local side, rendering a live, correlated trace waterfall
VaporTrace Architecture


How it actually works, step by step

  1. You upload a file to a storage bucket (S3) in your AWS account.
  1. That upload automatically fires an "event" AWS's way of saying "something happened."
  1. A router (EventBridge) picks up that event and sends it to the right places in our case, two small programs (Lambda functions).
  1. One of those programs' only job is to relay the event out of AWS, through a tunnel (IoT Core), straight to your own laptop.
  1. The other program does the real work in our demo, a simple "process this order" task and reports back whether it succeeded or failed.
  1. Your laptop receives both, live, and draws them on a dashboard as a connected graph so you see the whole journey, not just one piece of it.
  1. If something failed, you fix the data right there in the dashboard and send it back through the same chain — no logging into AWS, no guessing which service to check first.
That's the whole idea: instead of hunting for what broke, you watch it break, in real time, and fix it in the same place.

What fought back

 cdk bootstrap  silently failing in  us-east-1 . Fully-permissioned account, correct IAM, and  CreateChangeSet / DescribeStacks  still got denied with no clear cause. Switching to  us-east-1  fixed it instantly. Never fully root-caused a good reminder that not every blocker is a bug in your own code.
X-Ray's  FacadeSegment . Inside a Lambda,  AWSXRay.getSegment()  returns a read-only facade calling  .addAnnotation()  directly on it is a silent no-op. No error, no effect, nothing in the logs. It took checking the AWS Console trace-by-trace, cross-referencing CloudWatch, and finally reading into how X-Ray's segment model actually works inside Lambda to find the real fix: create an explicit subsegment via  captureFunc()  and annotate that instead. Once that changed, the same trace ID we'd been generating all along finally showed up as independently verified in X-Ray.
IoT Core as a pub/sub tunnel, not a device connection. Provisioning X.509 certs, a scoped IoT policy, and the Data-ATS endpoint by hand was a genuinely fiddly, multi-step process before it became reliable enough to build on top of.
CLI Terminal Screenshot


What it does now

Upload a file, and VaporTrace shows the event moving through your pipeline live a graph that lights up as each service processes it. If something fails, that node turns red with the real error and stack trace one click away. Edit the payload right in the dashboard, push it back into the pipeline, and watch a new, linked trace resolve all without opening the AWS console.
Local Dashboard


Who this is for

Any developer building on AWS with multiple connected services even just two who's tired of tab-switching between CloudWatch log groups trying to reconstruct what happened. You don't need to be an AWS expert to use it; you just need an AWS account and five minutes to deploy it.

What we learned

  • How to use IoT Core as a general-purpose pub/sub tunnel, well outside its usual "physical device" use case
  • The real difference between EventBridge's native Replay (resends an archived payload unmodified) and what we actually needed a fresh  PutEvents  call with corrected data
  • How AWS X-Ray's segment/subsegment model really works inside Lambda, including a genuine gotcha the docs don't make obvious
  • That a small, self-built trace/span protocol the same shape as OpenTelemetry is often the right-sized tool, without needing the full OTel SDK

What's next

  • Extending the same SDK pattern to a non-Lambda pipeline (S3 → SQS → ECS), using S3 object metadata to carry the trace ID where no free correlation ID exists
  • Automating the current manual IoT certificate setup into a single  vaportrace setup  command
It's also published as a real npm package ( npm install -g vaportrace ), so any developer can run it against their own AWS account.
Built for First Commit, the opening stop of WeMakeDevs' Bharat Builds Tour, Sept 17–20, 2026.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article