Performance Telemetry

Capture built-in FPS, memory, and battery telemetry with the Ansight .NET SDK, tune sampling cadence and retention, and choose the right default memory channels per platform.

This page is about numeric telemetry channels. For application logs and timeline events, see Capturing Logs.

What Ansight Captures By Default

When you use Options.Default, Ansight starts with:

  • sample frequency: 500ms
  • retention window: 10 minutes
  • FPS tracking enabled
  • default memory channels for the current platform
  • battery level tracking disabled

An empty Options.CreateBuilder().Build() uses the same sample frequency, retention, memory channels, and battery default, but it does not enable FPS unless you call WithFramesPerSecond() or use an all-in-one setup extension such as WithAnsightSdk(...) or UseAnsight<App>().

That gives Ansight Studio a live and recorded memory telemetry stream without requiring any optional tool packages. Add FPS and battery channels explicitly when those graphs matter.

Minimal Setup

using Ansight;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .Build();

Runtime.InitializeAndActivate(options);

That setup gives you FPS plus the platform-default memory channels.

WithFramesPerSecond() is shown explicitly here because empty builder setup does not enable FPS by itself. The all-in-one setup extensions enable FPS for you.

Tune Sampling And Retention

Use the builder when you want a tighter or looser telemetry stream:

using Ansight;

var options = Options.CreateBuilder()
    .WithSampleFrequencyMilliseconds(250)
    .WithRetentionPeriodSeconds(900)
    .WithFramesPerSecond()
    .Build();

Runtime.InitializeAndActivate(options);
  • Lower sample intervals produce a denser telemetry stream and more overhead.
  • Higher retention keeps more metrics buffered for the active session.

Memory Channels

DefaultMemoryChannels is a flags enum:

  • ManagedHeap
  • NativeHeap
  • ResidentSetSize
  • PhysicalFootprint
  • All

Platform defaults:

  • Android: ManagedHeap | NativeHeap | ResidentSetSize
  • iOS and Mac Catalyst: ManagedHeap | PhysicalFootprint
  • other targets: ManagedHeap

Battery Level

Battery level telemetry is opt-in because it reads a platform battery API at the configured sample cadence.

using Ansight;

var options = Options.CreateBuilder()
    .WithBatteryLevel()
    .Build();

Runtime.InitializeAndActivate(options);

When supported, the SDK adds the reserved Battery Level channel and records the current charge percentage from 0 to 100.

Platform support:

  • Android: reads BatteryManager through the current application context.
  • iOS and Mac Catalyst: enables UIDevice.BatteryMonitoringEnabled while the runtime is active and restores the previous setting when deactivated.
  • other targets: no battery samples are emitted.

To keep all-in-one setup but add battery tracking, enable it in the setup callback:

builder.UseAnsight<App>(ansight =>
{
    ansight.WithBatteryLevel();
});

Use WithoutBatteryLevel() to explicitly disable the channel when starting from shared option code.

Replace The Default Memory Set

Use WithDefaultMemoryChannels(...) when you want a known, explicit memory profile:

using Ansight;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .WithDefaultMemoryChannels(DefaultMemoryChannels.All)
    .Build();

Runtime.InitializeAndActivate(options);

Remove Specific Default Channels

Use WithoutDefaultMemoryChannels(...) when you want to trim the built-in platform defaults instead of replacing them outright:

using Ansight;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .WithoutDefaultMemoryChannels(DefaultMemoryChannels.NativeHeap)
    .Build();

Runtime.InitializeAndActivate(options);

Custom Metrics

Register custom channels with AddAdditionalChannel(...) or WithAdditionalChannels(...), then record samples with Runtime.Metric(value, channelId).

using System.Drawing;
using Ansight;
using Ansight.Telemetry.Channels;

const byte QueueDepthChannel = 42;

var options = Options.CreateBuilder()
    .AddAdditionalChannel(new Channel(
        QueueDepthChannel,
        "Sync queue depth",
        Color.FromArgb(88, 166, 255)))
    .Build();

Runtime.InitializeAndActivate(options);
Runtime.Metric(value: 17, channel: QueueDepthChannel);

Do not use reserved channel ids. The SDK reserves built-in memory channels, FPS, lifecycle, battery level, and byte.MaxValue for unspecified events.

What Ansight Studio Does With Telemetry

Ansight Studio uses these channels to render live and recorded time-series charts for:

  • FPS
  • built-in memory channels
  • battery level, when enabled and supported
  • any additional metric channels you register

Telemetry is also available in captured sessions and can be included in downstream analysis workflows.

For most teams:

  1. Start with the built-in defaults.
  2. Keep the sample interval at 500ms unless you are diagnosing short spikes.
  3. Extend retention only when you need longer local sessions in memory.
  4. Pair telemetry with Screen Views and App Lifecycle so the graphs have session context.
  5. Add WithBatteryLevel() only when battery state is relevant to the session you are diagnosing.