Skip to content

Commit bc0b6bd

Browse files
bitsandfoxesbitsandfoxes
authored
feat(Unity): Added Metrics (#16356)
1 parent fcd7a5b commit bc0b6bd

File tree

8 files changed

+182
-0
lines changed

8 files changed

+182
-0
lines changed

‎docs/platforms/unity/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Our Unity SDK builds on top of the [.NET SDK](/platforms/dotnet/) and extends it
3030
- [Offline Caching](/platforms/unity/configuration/options/#InitCacheFlushTimeout) stores event data to disk in case the device is not online
3131
- [Release Health](/platforms/unity/configuration/releases/) to keep track of crash-free users and sessions
3232
- [Structured Logging](/platforms/unity/logs/) to capture and send log messages with additional context
33+
- [Metrics](/platforms/unity/metrics/) to track counters, gauges, and distributions
3334
- [Automatically adding breadcrumbs](/platforms/unity/enriching-events/breadcrumbs/#automatic-breadcrumbs) for
3435
- Unity's `Debug.Log` and `Debug.LogWarning`
3536
- Scene load, unload, active change

‎docs/platforms/unity/metrics/index.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Set Up Metrics
3+
sidebar_title: Metrics
4+
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."
5+
sidebar_order: 5700
6+
beta: true
7+
---
8+
9+
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.
10+
11+
<Alert>
12+
This feature is currently in open beta. Features in beta are still in progress
13+
and may have bugs.
14+
</Alert>
15+
16+
## Requirements
17+
18+
<PlatformContent includePath="metrics/requirements" />
19+
20+
## Setup
21+
22+
<PlatformContent includePath="metrics/setup" />
23+
24+
## Usage
25+
26+
<PlatformContent includePath="metrics/usage" />
27+
28+
## Options
29+
30+
<PlatformContent includePath="metrics/options" />
31+
32+
## Default Attributes
33+
34+
<PlatformContent includePath="metrics/default-attributes" />

‎docs/product/explore/metrics/getting-started/index.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -406,6 +406,11 @@ To set up Sentry Metrics, use the links below for supported SDKs. After it's bee
406406
label="Unreal Engine"
407407
url="/platforms/unreal/metrics/"
408408
/>
409+
- <LinkWithPlatformIcon
410+
platform="unity"
411+
label="Unity"
412+
url="/platforms/unity/metrics/"
413+
/>
409414

410415
## Upcoming SDKs
411416

‎platform-includes/metrics/default-attributes/unity.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
The Sentry SDK for Unity automatically sets several default attributes on all metrics to provide context and improve debugging:
2+
3+
<Include name="metrics/default-attributes/core" />
4+
5+
<Include name="metrics/default-attributes/server" />
6+
7+
<Include name="metrics/default-attributes/user" />

‎platform-includes/metrics/options/unity.mdx‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
#### EnableMetrics
2+
3+
Set to `false` in order to disable the `SentrySdk.Experimental.Metrics` APIs.
4+
5+
#### SetBeforeSendMetric
6+
7+
To filter metrics, or update them before they are sent to Sentry, you can use the `SetBeforeSendMetric(Func<SentryMetric, SentryMetric?>)` option. If the callback returns `null`, the metric is not emitted. Attributes can also be updated in the callback delegate.
8+
9+
```csharp
10+
public override void Configure(SentryUnityOptions options)
11+
{
12+
options.Experimental.SetBeforeSendMetric(static metric =>
13+
{
14+
if (metric.Name == "removed-metric")
15+
{
16+
return null;
17+
}
18+
19+
metric.SetAttribute("extra", "foo");
20+
21+
return metric;
22+
});
23+
}
24+
```
25+
26+
or if you're manually initializing the SDK:
27+
28+
```csharp
29+
SentrySdk.Init(options =>
30+
{
31+
options.Dsn = "___PUBLIC_DSN___";
32+
options.Experimental.SetBeforeSendMetric(static metric =>
33+
{
34+
if (metric.Name == "removed-metric")
35+
{
36+
return null;
37+
}
38+
39+
metric.SetAttribute("extra", "foo");
40+
41+
return metric;
42+
});
43+
});
44+
```
45+
46+
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.
47+
48+
The metric object of type `SentryMetric` has the following members:
49+
50+
| Member | Type | Description |
51+
|--------|------|-------------|
52+
| `Timestamp` | `DateTimeOffset` | Timestamp indicating when the metric was emitted. |
53+
| `TraceId` | `SentryId` | The trace ID of the trace this metric belongs to. |
54+
| `Type` | `SentryMetricType` | The type of metric. One of `Counter`, `Gauge`, `Distribution`. |
55+
| `Name` | `string` | The name of the metric. |
56+
| `SpanId` | `SpanId?` | The span ID of the span that was active when the metric was emitted. |
57+
| `Unit` | `string?` | The unit of measurement for the metric value. Applies to `Gauge` and `Distribution` only. |
58+
| `TryGetValue<TValue>(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`. |
59+
| `TryGetAttribute<TAttribute>(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`. |
60+
| `SetAttribute<TAttribute>(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. |
61+
62+
The numeric value of `SentryMetric` has the same numeric type that the metric was emitted with.
63+
The supported numeric types are `byte`, `short`, `int`, `long`, `float`, and `double`.

‎platform-includes/metrics/requirements/unity.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Metrics for Unity are supported in Sentry SDK version `4.1.0` and above.

‎platform-includes/metrics/setup/unity.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
To enable metrics in your Unity game, you need to configure the Sentry SDK with metrics enabled.
2+
3+
### Project Settings Configuration
4+
5+
1. Inside the editor open: **Tools > Sentry > Advanced**
6+
2. Under the **Metrics** section, check the **Enable Metrics** option
7+
8+
### Programmatic Configuration
9+
10+
Alternatively, you can enable metrics programmatically through the [configure callback](/platforms/unity/configuration/options/programmatic-configuration):
11+
12+
```csharp
13+
public override void Configure(SentryUnityOptions options)
14+
{
15+
options.Experimental.EnableMetrics = true;
16+
}
17+
```
18+
19+
or if you're manually initializing the SDK:
20+
21+
```csharp
22+
SentrySdk.Init(options =>
23+
{
24+
options.Dsn = "___PUBLIC_DSN___";
25+
26+
// Enable metrics to be sent to Sentry
27+
options.Experimental.EnableMetrics = true;
28+
});
29+
```

‎platform-includes/metrics/usage/unity.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
Metrics are enabled by default. Once you initialize the SDK, you can send metrics using the `SentrySdk.Experimental.Metrics` APIs.
2+
3+
The `SentryMetricEmitter` type exposes three method groups that you can use to capture different types of metric information: `Counter`, `Gauge`, and `Distribution`.
4+
5+
All methods are generic, where the provided type argument defines the numeric value type that the metric is emitted with.
6+
The supported numeric types are `byte`, `short`, `int`, `long`, `float`, and `double`.
7+
8+
### Emit a Counter
9+
10+
Counters are one of the more basic types of metrics and can be used to count certain event occurrences.
11+
12+
To emit a counter, do the following:
13+
14+
```csharp
15+
// Record five total player interactions
16+
SentrySdk.Experimental.Metrics.EmitCounter("player_interaction", 5,
17+
new[] { new KeyValuePair<string, object>("scene", "MainMenu"), new KeyValuePair<string, object>("app_version", "1.0.0") });
18+
```
19+
20+
### Emit a Distribution
21+
22+
Distributions help you get the most insights from your data by allowing you to obtain aggregations such as `p90`, `min`, `max`, and `avg`.
23+
24+
To emit a distribution, do the following:
25+
26+
```csharp
27+
// Add '15.0' to a distribution used for tracking the loading times per scene.
28+
SentrySdk.Experimental.Metrics.EmitDistribution("scene_load", 15.0, MeasurementUnit.Duration.Millisecond,
29+
new[] { new KeyValuePair<string, object>("scene", "Level1") });
30+
```
31+
32+
### Emit a Gauge
33+
34+
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.
35+
36+
To emit a gauge, do the following:
37+
38+
```csharp
39+
// Add '15.0' to a gauge used for tracking the loading times for a scene.
40+
SentrySdk.Experimental.Metrics.EmitGauge("scene_load", 15.0, MeasurementUnit.Duration.Millisecond,
41+
new[] { new KeyValuePair<string, object>("scene", "Level1") });
42+
```

0 commit comments

Comments
 (0)