From 89e4b204223f5db9aab22c621cba3d5454ffcc23 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Wed, 11 Feb 2026 15:30:24 +0100 Subject: [PATCH] Added metrics to Unity --- docs/platforms/unity/index.mdx | 1 + docs/platforms/unity/metrics/index.mdx | 34 ++++++++++ .../explore/metrics/getting-started/index.mdx | 5 ++ .../metrics/default-attributes/unity.mdx | 7 +++ platform-includes/metrics/options/unity.mdx | 63 +++++++++++++++++++ .../metrics/requirements/unity.mdx | 1 + platform-includes/metrics/setup/unity.mdx | 29 +++++++++ platform-includes/metrics/usage/unity.mdx | 42 +++++++++++++ 8 files changed, 182 insertions(+) create mode 100644 docs/platforms/unity/metrics/index.mdx create mode 100644 platform-includes/metrics/default-attributes/unity.mdx create mode 100644 platform-includes/metrics/options/unity.mdx create mode 100644 platform-includes/metrics/requirements/unity.mdx create mode 100644 platform-includes/metrics/setup/unity.mdx create mode 100644 platform-includes/metrics/usage/unity.mdx diff --git a/docs/platforms/unity/index.mdx b/docs/platforms/unity/index.mdx index 209abaa58384f..fdf7385f89f0a 100644 --- a/docs/platforms/unity/index.mdx +++ b/docs/platforms/unity/index.mdx @@ -30,6 +30,7 @@ Our Unity SDK builds on top of the [.NET SDK](/platforms/dotnet/) and extends it - [Offline Caching](/platforms/unity/configuration/options/#InitCacheFlushTimeout) stores event data to disk in case the device is not online - [Release Health](/platforms/unity/configuration/releases/) to keep track of crash-free users and sessions - [Structured Logging](/platforms/unity/logs/) to capture and send log messages with additional context +- [Metrics](/platforms/unity/metrics/) to track counters, gauges, and distributions - [Automatically adding breadcrumbs](/platforms/unity/enriching-events/breadcrumbs/#automatic-breadcrumbs) for - Unity's `Debug.Log` and `Debug.LogWarning` - Scene load, unload, active change diff --git a/docs/platforms/unity/metrics/index.mdx b/docs/platforms/unity/metrics/index.mdx new file mode 100644 index 0000000000000..34f656ab99d62 --- /dev/null +++ b/docs/platforms/unity/metrics/index.mdx @@ -0,0 +1,34 @@ +--- +title: Set Up Metrics +sidebar_title: Metrics +description: "Metrics allow you to send, view and query counters, gauges and distributions from your Unity game to track application health and drill down into related traces, logs, and errors." +sidebar_order: 5700 +beta: true +--- + +With Sentry Metrics, you can send counters, gauges, and distributions from your Unity game to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes. + + + This feature is currently in open beta. Features in beta are still in progress + and may have bugs. + + +## Requirements + + + +## Setup + + + +## Usage + + + +## Options + + + +## Default Attributes + + diff --git a/docs/product/explore/metrics/getting-started/index.mdx b/docs/product/explore/metrics/getting-started/index.mdx index 04b16f3eaa7b8..24108b5d31877 100644 --- a/docs/product/explore/metrics/getting-started/index.mdx +++ b/docs/product/explore/metrics/getting-started/index.mdx @@ -406,6 +406,11 @@ To set up Sentry Metrics, use the links below for supported SDKs. After it's bee label="Unreal Engine" url="/platforms/unreal/metrics/" /> +- ## Upcoming SDKs diff --git a/platform-includes/metrics/default-attributes/unity.mdx b/platform-includes/metrics/default-attributes/unity.mdx new file mode 100644 index 0000000000000..908cb85ce37c8 --- /dev/null +++ b/platform-includes/metrics/default-attributes/unity.mdx @@ -0,0 +1,7 @@ +The Sentry SDK for Unity automatically sets several default attributes on all metrics to provide context and improve debugging: + + + + + + diff --git a/platform-includes/metrics/options/unity.mdx b/platform-includes/metrics/options/unity.mdx new file mode 100644 index 0000000000000..3742bc6508e89 --- /dev/null +++ b/platform-includes/metrics/options/unity.mdx @@ -0,0 +1,63 @@ +#### EnableMetrics + +Set to `false` in order to disable the `SentrySdk.Experimental.Metrics` APIs. + +#### SetBeforeSendMetric + +To filter metrics, or update them before they are sent to Sentry, you can use the `SetBeforeSendMetric(Func)` option. If the callback returns `null`, the metric is not emitted. Attributes can also be updated in the callback delegate. + +```csharp +public override void Configure(SentryUnityOptions options) +{ + options.Experimental.SetBeforeSendMetric(static metric => + { + if (metric.Name == "removed-metric") + { + return null; + } + + metric.SetAttribute("extra", "foo"); + + return metric; + }); +} +``` + +or if you're manually initializing the SDK: + +```csharp +SentrySdk.Init(options => +{ + options.Dsn = "___PUBLIC_DSN___"; + options.Experimental.SetBeforeSendMetric(static metric => + { + if (metric.Name == "removed-metric") + { + return null; + } + + metric.SetAttribute("extra", "foo"); + + return metric; + }); +}); +``` + +The `beforeSendMetric` delegate receives a metric object, and should return the metric object if you want it to be sent to Sentry, or `null` if you want to discard it. + +The metric object of type `SentryMetric` has the following members: + +| Member | Type | Description | +|--------|------|-------------| +| `Timestamp` | `DateTimeOffset` | Timestamp indicating when the metric was emitted. | +| `TraceId` | `SentryId` | The trace ID of the trace this metric belongs to. | +| `Type` | `SentryMetricType` | The type of metric. One of `Counter`, `Gauge`, `Distribution`. | +| `Name` | `string` | The name of the metric. | +| `SpanId` | `SpanId?` | The span ID of the span that was active when the metric was emitted. | +| `Unit` | `string?` | The unit of measurement for the metric value. Applies to `Gauge` and `Distribution` only. | +| `TryGetValue(out TValue value)` | Method | Gets the numeric value of the metric. Returns `true` if the metric value is of type `TValue`, otherwise `false`. Supported numeric value types are `byte`, `short`, `int`, `long`, `float`, and `double`. | +| `TryGetAttribute(string key, out TAttribute value)` | Method | Gets the attribute value associated with the specified key. Returns `true` if the metric contains an attribute with the specified key and its value is of type `TAttribute`, otherwise `false`. | +| `SetAttribute(string key, TAttribute value)` | Method | Sets a key-value pair of data attached to the metric. Supported types are `string`, `char`, `bool`, integers up to a size of 64-bit signed, and floating-point numbers up to a size of 64-bit. | + +The numeric value of `SentryMetric` has the same numeric type that the metric was emitted with. +The supported numeric types are `byte`, `short`, `int`, `long`, `float`, and `double`. diff --git a/platform-includes/metrics/requirements/unity.mdx b/platform-includes/metrics/requirements/unity.mdx new file mode 100644 index 0000000000000..1158e0982a42f --- /dev/null +++ b/platform-includes/metrics/requirements/unity.mdx @@ -0,0 +1 @@ +Metrics for Unity are supported in Sentry SDK version `4.1.0` and above. diff --git a/platform-includes/metrics/setup/unity.mdx b/platform-includes/metrics/setup/unity.mdx new file mode 100644 index 0000000000000..f7daa90cee79e --- /dev/null +++ b/platform-includes/metrics/setup/unity.mdx @@ -0,0 +1,29 @@ +To enable metrics in your Unity game, you need to configure the Sentry SDK with metrics enabled. + +### Project Settings Configuration + +1. Inside the editor open: **Tools > Sentry > Advanced** +2. Under the **Metrics** section, check the **Enable Metrics** option + +### Programmatic Configuration + +Alternatively, you can enable metrics programmatically through the [configure callback](/platforms/unity/configuration/options/programmatic-configuration): + +```csharp +public override void Configure(SentryUnityOptions options) +{ + options.Experimental.EnableMetrics = true; +} +``` + +or if you're manually initializing the SDK: + +```csharp +SentrySdk.Init(options => +{ + options.Dsn = "___PUBLIC_DSN___"; + + // Enable metrics to be sent to Sentry + options.Experimental.EnableMetrics = true; +}); +``` diff --git a/platform-includes/metrics/usage/unity.mdx b/platform-includes/metrics/usage/unity.mdx new file mode 100644 index 0000000000000..40418ff708a55 --- /dev/null +++ b/platform-includes/metrics/usage/unity.mdx @@ -0,0 +1,42 @@ +Metrics are enabled by default. Once you initialize the SDK, you can send metrics using the `SentrySdk.Experimental.Metrics` APIs. + +The `SentryMetricEmitter` type exposes three method groups that you can use to capture different types of metric information: `Counter`, `Gauge`, and `Distribution`. + +All methods are generic, where the provided type argument defines the numeric value type that the metric is emitted with. +The supported numeric types are `byte`, `short`, `int`, `long`, `float`, and `double`. + +### Emit a Counter + +Counters are one of the more basic types of metrics and can be used to count certain event occurrences. + +To emit a counter, do the following: + +```csharp +// Record five total player interactions +SentrySdk.Experimental.Metrics.EmitCounter("player_interaction", 5, + new[] { new KeyValuePair("scene", "MainMenu"), new KeyValuePair("app_version", "1.0.0") }); +``` + +### Emit a Distribution + +Distributions help you get the most insights from your data by allowing you to obtain aggregations such as `p90`, `min`, `max`, and `avg`. + +To emit a distribution, do the following: + +```csharp +// Add '15.0' to a distribution used for tracking the loading times per scene. +SentrySdk.Experimental.Metrics.EmitDistribution("scene_load", 15.0, MeasurementUnit.Duration.Millisecond, + new[] { new KeyValuePair("scene", "Level1") }); +``` + +### Emit a Gauge + +Gauges let you obtain aggregates like `min`, `max`, `avg`, `sum`, and `count`. They can be represented in a more space-efficient way than distributions, but they can't be used to get percentiles. If percentiles aren't important to you, we recommend using gauges. + +To emit a gauge, do the following: + +```csharp +// Add '15.0' to a gauge used for tracking the loading times for a scene. +SentrySdk.Experimental.Metrics.EmitGauge("scene_load", 15.0, MeasurementUnit.Duration.Millisecond, + new[] { new KeyValuePair("scene", "Level1") }); +```