meteor

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 instrumentation

It emits nine events:

EventFires when
method.start / method.end / method.errorA method begins, resolves, or throws
publication.start / publication.readyA publication's handler begins, or it calls this.ready()
publication.stop / publication.errorA subscription is torn down, or the publication errors
ddp.connection.open / ddp.connection.closeA 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

  1. Upgrade Meteor to 3.6 and the agent to 1.7.0:

    meteor update --release 3.6
    meteor add uptimeclarity:[email protected]
  2. Add the instrumentation package:

    meteor add instrumentation
  3. 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.

Install the agent or read how instrumentation works.