Meteor 3.6 Instrumentation: what it is and what you get from it
Meteor 3.6 ships a supported, read-only event stream for methods, publications and DDP connections. Here's what it exposes, what UptimeClarity does with it, and how to turn it on.
Every Meteor APM has the same dirty secret: to see what your server is doing,
it has to monkey-patch Meteor. It wraps Meteor.methods, swaps out
Meteor.publish, and reaches into DDP internals that were never meant to be
public. It works, but every Meteor release is a chance for it to quietly break.
Meteor 3.6 changes that. It ships an official instrumentation package: a
supported, read-only stream of lifecycle events for methods, publications and
DDP connections. It's a seam for tools like ours to build on, rather than a
monitoring tool itself.
This post covers what the package exposes, what UptimeClarity now does with it, and how to turn it on.
What Meteor 3.6 added
Add the package to your app:
meteor add instrumentationIt emits nine events:
| Event | Fires when |
|---|---|
method.start / method.end / method.error | A method begins, resolves, or throws |
publication.start / publication.ready | A publication's handler begins, or it calls this.ready() |
publication.stop / publication.error | A subscription is torn down, or the publication errors |
ddp.connection.open / ddp.connection.close | A client connects or disconnects |
Each method and publication event carries a traceId shared between its start
and its end, plus connectionId and userId. Completion events include
durationMs. Inside a method, Instrumentation.currentContext() hands you the
same traceId, so your own logs can line up with the events.
It's also careful by default. Arguments, results and client IPs aren't captured
unless you opt in. Accounts methods such as login and createUser are always
redacted. A listener that throws can never break the method it's watching. And
an operator can switch everything off with METEOR_INSTRUMENTATION_DISABLED=1.
What UptimeClarity does with it
Upgrade to uptimeclarity:agent 1.7.0 and add the package. The agent detects
it automatically, with nothing to configure. Here's what you get on top of the
method, publication and MongoDB monitoring you already had.
How long clients stay subscribed
Publication monitoring used to stop at time to ready. Now publication.stop
tells us how long each subscription actually lived. The new Subscriptions
page shows median and P95 lifetime per publication. A publication whose
subscriptions live 40 hours is a very different cost from one that churns
every few seconds, and now you can see which one you have.
Publication errors that never throw
Calling this.error(new Meteor.Error('not-authorized')) doesn't throw, so
patch-based agents never see it. Meteor's publication.error event does. Those
errors now count toward each publication's error rate.
A thrown error reaches that event too. The agent already reports throws with
a full stack trace, and the shared traceId makes sure the same failure is
never counted twice.
Hung methods
Every method.start should be followed by an end or error with the same
traceId. When one isn't, the method is stuck: an awaited call that never
resolved, a lock, a slow external API with no timeout. The agent tracks every
method in flight. Any call still running after 30 seconds (configurable with
hungMethodMs) is flagged once and shows up in the Hung methods table.
You also get a live methods in flight gauge per host, plus how long the oldest current call has been running.
Live DDP connections
The new DDP page shows live connections and subscriptions across every host, the top publications by subscriber count, and how long connections stay open (median and P95). Connections opened per interval make reconnect storms after a deploy easy to spot.
One trace ID across logs and outbound HTTP
The agent stamps the method's traceId onto everything that method does:
its method event, console and Log.* output, and any fetch() it makes. That
outbound call also carries the ID downstream as the X-Trace-Id header. When a
method is slow, you can follow it into the third-party API it was waiting on.
Why we didn't throw away our own hooks
The obvious move would be to drop the monkey-patching and rely entirely on the new events. We didn't, on purpose.
Meteor's *.error events carry a safe summary of the error: name, message,
and the Meteor.Error code and reason. They deliberately don't include a
stack trace, and our Errors tab is built on stack traces. So method and
publication timing still come from the agent's own hooks on every Meteor
version, and the Instrumentation events fill in what those hooks can't see.
That has a nice side effect: adding or removing the package never shifts your existing numbers. Your method P95 from last month and from today come from the same measurement.
Your data stays your call
The agent never calls Instrumentation.configure(). If you haven't opted in to
capturing arguments, results or client IPs, they're not captured, and the agent
doesn't forward them even when you have. It records whether a call came from a
client or the server and whether a user was logged in, but never the user ID
itself.
If METEOR_INSTRUMENTATION_DISABLED is set, the agent respects it and keeps
running on its own hooks. Each host reports which mode it's in, and you can see
it on the host detail page and the DDP page.
Turning it on
-
Upgrade Meteor to 3.6 and the agent to 1.7.0:
meteor update --release 3.6 meteor add uptimeclarity:[email protected] -
Add the instrumentation package:
meteor add instrumentation -
Deploy. Within about a minute, the DDP page should show your hosts as Meteor Instrumentation. Subscription lifetimes appear as subscriptions end.
Not ready for 3.6 yet? Upgrading the agent alone still gets you live connection and subscription counts on the DDP page, plus client-vs-server attribution on every method and publication.