Metrics (Trace Connected) For JavaScript

[AbhiPrasad]

Sentry is introducing metrics that let you send counters, gauges, and distributions from your code to track things like email.sent, checkout.failed, or queue.depth — and pivot directly into the related traces, logs, and errors when something looks off.

TraceConnectedMetrics.mp4

Note

To get early access to the Sentry metrics product and to see how it works, see the announcement post.

To use the new Metric APIs to send metrics directly to Sentry, you'll have to upgrade to 10.25.0 of the JavaScript SDK or higher.

Once the SDK is initialized, you can send metrics using the Sentry.metrics APIs.

The metrics namespace exposes three methods that you can use to capture different types of metric information: count, gauge, and distribution.

Sentry.metrics.count('checkout.failed', 1);
Sentry.metrics.gauge('queue.depth', 42);
Sentry.metrics.distribution('cart.amount_usd', 187.5);

You can also pass additional attributes directly to count, gauge, and distribution via the attributes object.

Sentry.metrics.count('checkout.failed', 1, {
  attributes: {
    "route": "/checkout",
    "tenant": "acme",
    "provider": "stripe",
  },
});

You can also set a unit on the metric

Sentry.metrics.distribution('cart.amount_usd', 187.5, {
  unit: 'usd',
  attributes: {
    currency: 'USD',
    tenant: 'acme',
  },
});

[ian-schu]

Hi folks,
Very excited about this feature – in a previous job I used metrics heavily (within Datadog) and it gave us a ton of power to monitor specific aspects of our app.

I've just set up metrics this morning in the app I currently operate, and they're working beautifully.

Two questions for you:

1. Are there plans to include Metrics as the basis for Alerts?
2. Are there plans to include Metrics as a dataset for dashboard widgets?

Both of these would really complete the package for us, in terms of using Sentry as our home base for observing our app in production. Thanks!

[Dhrumil-Sentry]

@ian-schu - We will have support for both Alerting and dashboard widgets based on Metrics - We're working towards having support by early Feb

getsentry/sentry#102275 (reply in thread)

[ian-schu]

Outstanding, thanks!

[pirate]

I love this new feature but after trying to implement it with claude code I ran into a hilarious issue.

Sentry has historically only accepted tags args to ehance events, and LLMs are extremely familiar with the Sentry APIs so they're very used to that pattern.

attributes is a new arg name that hasn't been used before, and claude code completely steadfastly refused to use attributes and instead kept renaming it to tags: {...} every time it encountered attributes: {...} in metrics calls.

I had to tell it not to do this about 20 times:

Sentry.metrics.distribution(metric, value, { unit, ...(attributes ? { tags: attributes } : {}) });

I will admit it was not my finest hour, I usually try not to swear at claude like this becuase it just makes it less effective.

I understand that you probably deliberately chose attributes to avoid confusion with event tags, but you may want to reconsider that choice just because of the sheer momentum and historic usage of tags.

[AbhiPrasad]

attributes behave differently than tags, both in the SDK and in the Sentry product.

Tags in Sentry can only have string values, and are restricted are limited to 200 characters (and have other restrictions like not being able to contain new line characters). This makes them much less flexible and easy to use. We couldn't change how tags work, because it would be a huge breaking change for the ecosystem (for example, sentry integrations might have hardcoded the tag limits themselves).

Attributes have no such limits. You can attach strings, numbers, booleans, arrays, objects values as you desire. You can also attach a unit to an attribute (not that useful for numeric attributes on metrics, but very useful for numeric attributes on logs). The attribute size limits are much larger as well.

Eventually the plan is that you can attach attributes to errors too, bringing the API improvements there. Right now only spans, logs, and metrics support attributes.

Unfortunately the LLMs hallucinating is a blocker here, but we are working on ways to improve this. For now I recommend updating your Agents.MD (or similar) or using a claude agent skill to document this accordingly.

[pirate]

I totally get it, it's unfortunate to be pinned by LLM behavior like this when the underlying feature actually is different.

I tried Agents.md/Claude.md already, it will not listen regardless of how strongly I word it. I've tried pasting the Sentry docs examples in, I've tried showing it examples in context with existing code using the correct pattern, it steadfastly refuses to use the word attributes and keeps changing it back to tags as soon as context gets long or I open a new session. (The screenshot I shared was just the most frustrating ending portion of a long session where I had already corrected it many times with more in-depth prompts explaining how tags and attributes are separate concepts.)

At this point even if I manually write all this code myself, it's a hazard because a future claude sub-agent will still try to incorrectly "correct" it, so I have to watch diffs like a hawk.

Perhaps you could accept tags as an alias for attributes in the metrics APIs? But only document attributes publicly so the LLMs eventually learn? I will also admit as a human it does seem like these are overlapping features somewhat, I wonder if the existing tags system could just be enhanced to allow other types and larger values? If events will eventually support both tags and attributes, I would probably wonder when I should use one vs the other in a lot of cases.

[pirate]

the only approach that is working for me so far is defining my own custom function to wrap it that doesn't include sentry in the name, and telling the LLM to use my custom function instead:

function incrementMetric(metric, value, unit, attributes) {
    Sentry.metrics.count(metric, value, {unit, attributes})  // Sentry.metrics.* is a brand new API that expects 'attributes' NOT 'tags', DO NOT CHANGE THIS, they are not interchangeable
}

[igorsantos07]

I'd like to request inclusion of pixel and megapixel units. I'd like to track how big are the pictures people are usually trying to upload on my application before we shrink it, as we've had a couple of troubles with canvas sizes in iOS.

It's also not clear from the docs what happens if we use an arbitrary unit name, instead of the "supported list".

[Dhrumil-Sentry]

Thanks a lot for this feedback - We're gonna start with the supported units listed - If you send an arbitrary unit name we'd store it and you can see it on the metric events too but we won't render/auto-scale charts etc based on that unit

[domusnextai]

First of all, super excited about the new Sentry.metrics APIs! The paradigm shift from tags to attributes makes total sense for long-term scalability.

I am trying to implement a real-time monitoring dashboard for IoT/Client device connection status (like MQTT/WebSocket persistence) using the gauge metric, but I hit a dead-end due to the current limitations of Dashboard aggregation functions.

📈 Our Use Case & Architecture
On our client devices, we report connection status via Sentry.metrics().gauge().

Frequency: Every 15 minutes as a heartbeat, OR immediately when the connection status changes.

Value: 1.0 for Online, 0.0 for Offline.

Attributes: Enclosed with device_id to identify unique hardware.

JavaScript
// When connected / heartbeat
Sentry.metrics.gauge('mqtt.online', 1.0, { attributes: { device_id: 'dev_123' } });

// When disconnected gracefully
Sentry.metrics.gauge('mqtt.online', 0.0, { attributes: { device_id: 'dev_123' } });
❌ The Problem: Lack of Time-Windowed State Aggregation
We want to build a widget to track "The exact number of concurrent online devices at any given moment".

Mathematically, the logic for each time bucket (e.g., a 5-minute interval) should be:

For each unique device_id, find its last reported value (0 or 1) within this window (or lookback window).

Count how many devices have a last value equal to 1.

Total Online Devices = ∑[last_value==1.0].

However, in the Sentry Dashboard / Application Metrics UI, there is no way to perform this.

avg(mqtt.online) completely distorts the reality. If a device flips from 1 to 0 in the same bucket, avg returns 0.5, which means nothing for a binary state.

last(mqtt.online) works if we Group by: device_id, but when we have thousands of devices, grouping by device ID crashes the UI/chart because it tries to render thousands of lines, instead of aggregating them into a single "Total Online Count" line.

We desperately need a function like count_if(mqtt.online == 1, group_by=device_id) or the ability to nested-aggregate: sum(last(mqtt.online) by device_id).

💡 Suggested Solutions / Feature Requests
Support last inside Equation / Nested Aggregations: Allow us to group by device_id on query A with last, and then write an Equation f1: sum(A) that collapses the groups into a single total count line.

Introduce Conditional Counter: Provide something like count_match(metric, value) or standard PromQL-like behaviors (last_over_time) for Gauges in Sentry Dashboards.

Accept State/Status as a native Metrics type: If Gauges are restricted to mathematical min/max/avg, maybe we need a status type metric that understands state persistence?

Would love to hear if this is on the roadmap for the upcoming Feb Dashboard overhaul!

Thanks!

[bcoe]

@domusnextai perhaps I'm misunderstanding, but could this also be achieved with something like COUNT DISTINCT:

COUNT DISTINCT(device_id) WHERE LAST(mqtt.online) === 1
COUNT DISTINCT(device_id) WHERE LAST(mqtt.online) === 0

Am I understanding correctly that what you're trying to achieve is not counting the same device more than once in a period? I may be misunderstanding.