
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

How it actually works, step by step
- You upload a file to a storage bucket (S3) in your AWS account.
- That upload automatically fires an "event" AWS's way of saying "something happened."
- A router (EventBridge) picks up that event and sends it to the right places in our case, two small programs (Lambda functions).
- One of those programs' only job is to relay the event out of AWS, through a tunnel (IoT Core), straight to your own laptop.
- The other program does the real work in our demo, a simple "process this order" task and reports back whether it succeeded or failed.
- 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.
- 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.

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.

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
PutEventscall 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 setupcommand
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.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article