#FPS tracking in Unity

12 messages · Page 1 of 1 (latest)

rancid raven Jun 9, 2025, 6:49 PM

Hi there!

We're a game dev company using Sentry in Unity.
We implemented fps (framerate) tracking as Gauge in the Metrics API that was sunset.
It was fulfilling our needs perfectly..

Our goal is to track framerate across builds, build types, branches, game state, etc, so we can understand what our build performance better and be able to track when it gets worse.
We send fps reports ~twice per minute. Being a small company, I calculate we'd send up to ~200k 'reports' per month.

It looks like the traces/spans API can still address our needs though.
We just add a 'metric' to the span and send a new 'transaction' every time with this single span.

As I understand, that's not what this API was designed for..
Are there any drawbacks to doing it this way? I assume some extra data would be sent that we don't really need..
Anything I'm missing?

We'd need to switch to the new span-based plan (we're still on the 100k transactions one)

split riverBOT Jun 9, 2025, 6:49 PM

Hi @rancid raven. I'm happy to dig into this for you! I'll check my internal sources for answers to your question! :wave:

You're correct that the Sentry traces/spans API was not designed for high-frequency, periodic metric reporting like FPS tracking, and there are some important drawbacks and considerations to be aware of:

Drawbacks of Using Transactions/Spans for FPS Tracking

Not Designed for High-Frequency Metrics
Sentry's tracing model is built around capturing meaningful user or system actions (like scene loads, button clicks, or network requests), not for sending frequent, regular metrics like FPS. Creating a transaction or span for each FPS report (even at 2 per minute per user) can quickly add up and may not scale well, especially as your user base grows. This can lead to increased network usage, higher ingestion costs, and potential performance overhead in your game client [Understanding the Unity lifecycle: finding key points for instrumentation].
Extra Data Overhead
Each transaction and span carries additional metadata (context, tags, timestamps, etc.) that you may not need for simple FPS reporting. This means more data is sent and stored than necessary for your use case [Developer Documentation: Inability to Batch Transactions].
Inefficient Batching
Sentry's ingestion model does not support batching multiple transactions in a single request. Each FPS report would result in a separate network request, which is inefficient and could be a drain on bandwidth and device resources [Developer Documentation: Inability to Batch Transactions].

Product Model Fit
Sentry maintainers and contributors have discussed that using transactions/spans for per-frame or high-frequency measurements is not ideal. The recommended approach is to aggregate such data over larger periods and report summary statistics, rather than sending a transaction for each measurement. This is especially relevant in game loops, where defining meaningful transaction boundaries is challenging [Unity SDK Issue: Add Profiling (Lite) functionality].
Potential for Messy Data
If you try to represent the entire game session as a single transaction, it can look messy in the Sentry UI and may not provide the actionable insights you want [Unity SDK Issue: Add Profiling (Lite) functionality].

Current State and Alternatives

The Metrics API you were using has been deprecated, and there is ongoing work to improve how metrics are handled in Sentry, especially for use cases like yours. However, as of now, there is no direct replacement for high-frequency, lightweight metric reporting in the Unity SDK [Unity SDK Issue: Metrics not being attached to Spans].
Profiling (which can record frame rates and other performance data) is available in Sentry, but it's not yet integrated into the Unity SDK as it is for native mobile platforms [How can I track frame rates?].

Recommendations

Avoid sending a transaction for every FPS report. Instead, consider aggregating FPS data over a session or a meaningful period (e.g., average/min/max FPS per level or per session) and sending it as a single transaction or as part of a custom event.
Monitor Sentry Unity SDK updates. There is active discussion about adding better support for performance metrics and profiling in Unity, but no ETA yet [Unity SDK Issue: FPS and App Start Monitoring].
If you must use transactions/spans, be aware of the overhead and potential cost implications, and try to minimize the frequency and volume of data sent.

If your primary goal is to track FPS trends across builds and game states, you may want to supplement Sentry with a dedicated analytics or telemetry solution for high-frequency metrics until Sentry's Unity SDK offers more suitable support.

Summary:
Using Sentry transactions/spans for periodic FPS reporting is technically possible but not recommended due to inefficiency, extra data overhead, and product model mismatch. Aggregating and reporting summary statistics less frequently is a better fit for Sentry's current capabilities in Unity. Keep an eye on SDK updates for improved metric support in the future.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@rancid raven Our robots are still learning and improving, please let us know if this response was correct by reacting below.

rancid raven Jun 9, 2025, 6:54 PM

I'm less interested in tracking this in Live builds, more for development.
With a small team, scale should not be an issue. At most 200k spans per month.
On live we'd have a random sample chance to limit it to some similar number just to make sure perf doesn't degrade. So maybe 400k total. For fun lets' double say to 1M, it's still well under 10M available.. right?

Perf in client is indeed a concern, I'll check the cost on my end.

@split river ?

split riverBOT Jun 9, 2025, 6:58 PM

Let me check the knowledge base for you again. One moment! :books:

You're correct that the Sentry Metrics API (which supported lightweight, high-frequency reporting like FPS as a Gauge) has been sunset and is no longer available in the Unity SDK. The new span-based metrics approach in Sentry is fundamentally different: it derives metrics from span data, rather than allowing you to push custom metrics directly.

Drawbacks and Considerations:

Not Designed for High-Frequency Metrics:
The traces/spans API is intended for capturing meaningful transactions and their sub-operations (spans), not for periodic, high-frequency reporting like FPS. Sending a new transaction every time you want to report FPS (even at 2 per minute per user) can quickly add up, especially as your user base grows. This could lead to increased data volume, higher costs, and potential performance overhead in your game client. Sentry maintainers have noted that per-frame or high-frequency measurements are not a good fit for the tracing model, and recommend aggregating such data over longer periods instead [Unity SDK Issue: Add Profiling (Lite) functionality].
Extra Data Overhead:
Each transaction and span includes additional metadata (context, tags, timestamps, etc.) that you may not need for simple FPS reporting. This means more data is sent and stored than necessary for your use case.
No Batching:
Sentry does not support batching multiple transactions in a single request, so each FPS report would result in a separate network request, which is inefficient [Unity SDK Issue: Add Profiling (Lite) functionality].

Product Model Fit:
The new span-based metrics solution does not support sending standalone custom metrics as the old Metrics API did. Instead, it derives aggregations from span data, and there is no support for custom "push" metrics in the new model [Metrics Beta Ended on October 7th, Request for Transition Plan for Metrics Beta Users].

What You Might Be Missing:

No Direct Replacement Yet:
There is currently no direct replacement in Sentry for the lightweight, high-frequency custom metrics reporting you were doing with the Metrics API. The Unity SDK team is aware of this gap and has discussed internally how to address it, but there is no ETA for a new solution [Unity SDK Issue: FPS and App Start Monitoring].
Profiling (for Frame Rate):
Sentry's profiling feature can record frame rates and other performance data, but as of now, this is not yet available in the Unity SDK as it is for native mobile platforms [How can I track frame rates?].

Recommendation:
If you continue with the span-based approach, aggregate your FPS data over a session or meaningful period (e.g., average/min/max FPS per level or session) and send it as a single transaction or event, rather than sending a transaction for every FPS measurement. This will reduce overhead and better fit Sentry's current capabilities.

Summary:
Using the traces/spans API for periodic FPS reporting is possible but not recommended due to inefficiency, extra data overhead, and product model mismatch. There is no direct replacement for the Metrics API in Unity at this time, and you may want to supplement Sentry with another telemetry solution for high-frequency metrics until Sentry's Unity SDK offers more suitable support.