Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# Changelog

## Unreleased

### Features

- Experimental session replay on Android ([#2948](https://github.com/getsentry/sentry-unity/pull/2948)):
- Set `options.Experimental.SessionReplay.SessionSampleRate` or `OnErrorSampleRate` in code,
in the options used both at build time and at runtime.
- The Android SDK records the game, and errors captured in C# send the replay of the moments before them,
like native errors do.
- Session replay requires runtime initialization of the Android SDK and adds the Kotlin standard library to the build.
- By default, the Android SDK captures the frames; with `Capture = SessionReplayCapture.Unity`,
Unity captures them instead.

## 4.13.0

### Behavioral Changes
Expand Down
5 changes: 4 additions & 1 deletion build/native-sdks.targets
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,7 @@
<RemoveDir Directories="$(SentryAndroidRoot)sentry/build/libs" ContinueOnError="true" />
<RemoveDir Directories="$(SentryAndroidRoot)sentry-android-core/build" ContinueOnError="true" />
<RemoveDir Directories="$(SentryAndroidRoot)sentry-android-ndk/build" ContinueOnError="true" />
<RemoveDir Directories="$(SentryAndroidRoot)sentry-android-replay/build" ContinueOnError="true" />

<!-- Build sentry-native NDK from source and publish it to ~/.m2 so Gradle's
mavenLocal() can resolve it (when the version isn't on Maven Central). -->
Expand All @@ -302,16 +303,18 @@
<!-- IgnoreExitCode: Gradle may report BUILD SUCCESSFUL yet the JVM exits with code -1 due to
the Kotlin compiler daemon terminating unexpectedly. The Error checks below validate the
actual build outputs, so we can safely ignore the exit code here. -->
<Exec WorkingDirectory="$(SentryAndroidRoot)" Command="./gradlew -PsentryAndroidSdkName=sentry.native.android.unity :sentry-android-core:assembleRelease :sentry-android-ndk:assembleRelease :sentry:jar --no-daemon --stacktrace --warning-mode none" IgnoreExitCode="true" />
<Exec WorkingDirectory="$(SentryAndroidRoot)" Command="./gradlew -PsentryAndroidSdkName=sentry.native.android.unity :sentry-android-core:assembleRelease :sentry-android-ndk:assembleRelease :sentry-android-replay:assembleRelease :sentry:jar --no-daemon --stacktrace --warning-mode none" IgnoreExitCode="true" />

<ItemGroup>
<AndroidSdkArtifacts Include="$(SentryAndroidRoot)sentry-android-ndk/build/outputs/aar/sentry-android-ndk-release.aar" />
<AndroidSdkArtifacts Include="$(SentryAndroidRoot)sentry-android-core/build/outputs/aar/sentry-android-core-release.aar" />
<AndroidSdkArtifacts Include="$(SentryAndroidRoot)sentry-android-replay/build/outputs/aar/sentry-android-replay-release.aar" />
<AndroidJarArtifacts Include="$(SentryAndroidRoot)sentry/build/libs/sentry*.jar" />
</ItemGroup>

<Error Condition="!Exists('$(SentryAndroidRoot)sentry-android-ndk/build/outputs/aar/sentry-android-ndk-release.aar')" Text="sentry-android-ndk-release.aar not found. The Gradle build likely failed." />
<Error Condition="!Exists('$(SentryAndroidRoot)sentry-android-core/build/outputs/aar/sentry-android-core-release.aar')" Text="sentry-android-core-release.aar not found. The Gradle build likely failed." />
<Error Condition="!Exists('$(SentryAndroidRoot)sentry-android-replay/build/outputs/aar/sentry-android-replay-release.aar')" Text="sentry-android-replay-release.aar not found. The Gradle build likely failed." />
<Error Condition="@(AndroidJarArtifacts->Count()) == 0" Text="sentry.jar not found. The Gradle build likely failed." />

<Copy SourceFiles="@(AndroidSdkArtifacts)" DestinationFiles="@(AndroidSdkArtifacts->'$(SentryAndroidArtifactsDestination)%(Filename)%(Extension)')" />
Expand Down
54 changes: 54 additions & 0 deletions docs/agent-guides/platform-android.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,60 @@

The Java layer disables duplicate screenshots, auto-session tracking, activity lifecycle breadcrumbs, and user-interaction breadcrumbs/tracing because Unity/.NET owns them.

## Session Replay (Experimental)

- `options.Experimental.SessionReplay` is set from code, with no editor UI.
Replay is enabled when `SessionSampleRate` or `OnErrorSampleRate` is above 0.
- Packaging:
- `sentry-android-replay-release.aar` ships in `Sentry~` next to the other artifacts.
- `GradleSetup` adds it to `unityLibrary/build.gradle` only when replay is enabled in the build-time options,
together with `org.jetbrains.kotlin:kotlin-stdlib` from Maven, at the version sentry-android-replay builds with.
- Without replay, the Sentry dependency block is unchanged.
- Adding and clearing recognize both variants of the block,
so a persisted Gradle project follows replay and native support being toggled.
- Replay is runtime-init only:
- `SentryJava.Init` configures the replay options: sample rates, quality,
and SurfaceView capture when sentry-java captures the frames, since Unity renders into a SurfaceView.
- Build-time and external initialization log that replay is ignored.
- A missing replay library logs an error asking to enable replay in the build-time options.
- Unity capture (`Capture = SessionReplayCapture.Unity`):
- Without `SystemInfo.supportsAsyncGPUReadback`, `SentryJava.Init` logs a warning and sentry-java captures instead.
- `UnityReplayRecorder` replaces the `ReplayIntegration` sentry-java added with one built through JNI
around a custom `Recorder`: a Unity `AndroidJavaProxy`, returned by a `kotlin.jvm.functions.Function0` proxy.
- sentry-java calls the recorder on Android's UI thread, which only updates flags and the frame config.
- sentry-java never sends a custom recorder a frame config. After each start or reset,
and when Unity's screen size changes, Unity's main thread asks the UI thread to call `onWindowSizeChanged`
with the activity window's size, and sentry-java computes the config from it.
Before the window is laid out, Unity's screen size stands in once, and a later frame asks again.
- It gets the window's size, not `Screen.width/height`, which can be a lower render resolution:
sentry-java scales recorded touches, which are in window pixels, by that config.
- At the config's frame rate, Unity's main thread captures the screen at end of frame,
blits it top-down into an RGBA render texture at the recording size (`SentryScreenshot.BlitScreen`)
and reads it back with `AsyncGPUReadback`.
- A worker thread attached to the JVM copies each frame into a new `ARGB_8888` bitmap
and calls `onScreenshotRecorded`.
- A started recorder captures until it's paused: sentry-java only resumes a paused one.
- `proguard-sentry-unity.pro` keeps the replay classes Unity reaches through JNI and proxies,
and the classes in the JNI signatures it looks up (`ICurrentDateProvider`, `Integration`, `Function0`, `Function1`):
keeping a method doesn't keep the classes in its signature, so minified builds would rename them.
- Replays for C# errors:
- sentry-java samples and starts the replay itself.
- `AndroidReplaySession` is the .NET SDK's replay session: the replay id of the dynamic sampling context
comes from the Java scope.
- The .NET client calls `captureReplay` for each error event
and puts the returned replay id on that event's dynamic sampling context.
Other events get the Java scope's current replay id.
- Background and foreground:
- Unity builds don't start androidx's process lifecycle (the `lifecycle-process` startup provider isn't in the
manifest), so the Java SDK doesn't see the app go to the background.
When it isn't running, Unity's pause and resume drive the replay instead.
- A pause is the replay's manual pause. sentry-java resumes a replay paused for the background
when the device reconnects, which happens in the background too, but not a manually paused one.
- Resuming moves the replay's timeline to the return, so no segment covers the time away.
- After a background longer than `AutoSessionTrackingInterval`, the replay is resumed and then ended right away
(`onAppForegrounded(true)`), so it ends at the pause without a segment for the time away, and a new one starts.
- Unity capture drops frames read back or handed over after the pause, so none lands after the pause segment.

## Constraints

- Android native ANR and C# ANR monitor different threads; both can report one full hang.
Expand Down
18 changes: 18 additions & 0 deletions package-dev/Plugins/Android/proguard-sentry-unity.pro
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,22 @@
-keep class io.sentry.protocol.** { *; }
-keep class io.sentry.android.core.internal.util.AndroidConnectionStatusProvider { *; }
-keep class io.sentry.android.core.internal.util.NetworkConnection { *; }
# Experimental session replay: options, the replay controller and the recorder Unity can provide.
-keep class io.sentry.SentryReplayOptions { *; }
-keep class io.sentry.SentryReplayOptions$SentryReplayQuality { *; }
-keep interface io.sentry.ReplayController { *; }
-keep class io.sentry.transport.CurrentDateProvider { *; }
-keep class io.sentry.android.replay.ReplayIntegration { *; }
-keep interface io.sentry.android.replay.Recorder { *; }
-keep class io.sentry.android.replay.ScreenshotRecorderConfig { *; }
-keep interface kotlin.jvm.functions.Function0 { *; }
# The classes in the JNI signatures of the ReplayIntegration constructor and SentryOptions.addIntegration.
-keep interface io.sentry.transport.ICurrentDateProvider { *; }
-keep interface io.sentry.Integration { *; }
-keep interface kotlin.jvm.functions.Function1 { *; }
# Unity checks whether androidx's process lifecycle runs, to pause the replay itself when it doesn't.
-keep class androidx.lifecycle.ProcessLifecycleOwner { *; }
-keep class androidx.lifecycle.Lifecycle { *; }
-keep class androidx.lifecycle.Lifecycle$State { *; }
-dontwarn androidx.lifecycle.**
-dontwarn io.sentry.**
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ PlayerSettings:
vrSettings:
enable360StereoCapture: 0
isWsaHolographicRemotingEnabled: 0
enableFrameTimingStats: 0
enableFrameTimingStats: 1
enableOpenGLProfilerGPURecorders: 1
useHDRDisplay: 0
D3DHDRBitDepth: 0
Expand Down
151 changes: 151 additions & 0 deletions samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
#if UNITY_ANDROID && !UNITY_EDITOR
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;

// Spins a cube above the sample's UI, so session replays show motion, and logs frame timings to logcat under the
// 'ReplayBenchmark' tag, to compare session replay's capture modes (see SentryOptionConfiguration).
// Android players only. The GPU and per-thread timings need 'Frame Timing Stats' in the player settings.
public class ReplayBenchmark : MonoBehaviour
{
private const string LogTag = "ReplayBenchmark";
private const float WarmUpSeconds = 5f;
private const float ReportSeconds = 10f;
// A layer of its own, so the cube's camera and light leave the sample's scenes alone.
private const int CubeLayer = 31;

private readonly List<float> _frameTimes = new();
private readonly FrameTiming[] _timings = new FrameTiming[1];
private double _cpuMainMs;
private double _cpuRenderMs;
private double _gpuMs;
private int _timingCount;
private float _collectFrom;
private float _nextReport;
private Transform _cube;
private string _mode;
private AndroidJavaClass _log;

[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterSceneLoad)]
private static void Spawn()
{
var benchmark = new GameObject("ReplayBenchmark");
DontDestroyOnLoad(benchmark);
benchmark.AddComponent<ReplayBenchmark>();
}

private void Start()
{
Application.targetFrameRate = 60;
_mode = $"replay={SentryOptionConfiguration.GetLaunchExtra("sentry_replay") ?? "error"} " +
$"capture={SentryOptionConfiguration.GetLaunchExtra("sentry_replay_capture") ?? "java"}";
_log = new AndroidJavaClass("android.util.Log");
_collectFrom = Time.realtimeSinceStartup + WarmUpSeconds;
_nextReport = _collectFrom + ReportSeconds;

var texture = new RenderTexture(256, 256, 16);

var cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
cube.layer = CubeLayer;
cube.transform.SetParent(transform);
cube.transform.position = new Vector3(0, -1000, 0);
// A shader that builds always include. The primitive's default material doesn't make it into the player.
var shader = Shader.Find("Legacy Shaders/Diffuse");
var cubeRenderer = cube.GetComponent<Renderer>();
if (shader != null)
{
cubeRenderer.material = new Material(shader);
}
cubeRenderer.material.color = new Color(1f, 0.45f, 0.1f);
_cube = cube.transform;

var cubeCamera = new GameObject("ReplayBenchmarkCamera").AddComponent<Camera>();
cubeCamera.transform.SetParent(transform);
cubeCamera.transform.position = _cube.position + new Vector3(0, 0, -2.5f);
cubeCamera.cullingMask = 1 << CubeLayer;
cubeCamera.clearFlags = CameraClearFlags.SolidColor;
cubeCamera.backgroundColor = new Color(0.1f, 0.5f, 0.9f);
cubeCamera.targetTexture = texture;

var cubeLight = new GameObject("ReplayBenchmarkLight").AddComponent<Light>();
cubeLight.transform.SetParent(transform);
cubeLight.type = LightType.Directional;
cubeLight.cullingMask = 1 << CubeLayer;
cubeLight.transform.rotation = Quaternion.Euler(40, -30, 0);

// Above the sample's UI, in the top right corner.
var canvas = new GameObject("ReplayBenchmarkCanvas").AddComponent<Canvas>();
canvas.transform.SetParent(transform);
canvas.renderMode = RenderMode.ScreenSpaceOverlay;
canvas.sortingOrder = 1000;
var image = new GameObject("ReplayBenchmarkCube").AddComponent<RawImage>();
image.texture = texture;
image.raycastTarget = false;
var rect = image.rectTransform;
rect.SetParent(canvas.transform, false);
rect.anchorMin = rect.anchorMax = rect.pivot = new Vector2(1, 1);
rect.anchoredPosition = new Vector2(-16, -16);
rect.sizeDelta = new Vector2(220, 220);
}

private void Update()
{
_cube.Rotate(new Vector3(30, 60, 15) * Time.deltaTime);

var now = Time.realtimeSinceStartup;
if (now < _collectFrom)
{
return;
}

_frameTimes.Add(Time.unscaledDeltaTime * 1000f);
FrameTimingManager.CaptureFrameTimings();
if (FrameTimingManager.GetLatestTimings(1, _timings) > 0)
{
#if UNITY_2022_1_OR_NEWER
_cpuMainMs += _timings[0].cpuMainThreadFrameTime;
_cpuRenderMs += _timings[0].cpuRenderThreadFrameTime;
#else
_cpuMainMs += _timings[0].cpuFrameTime;
#endif
_gpuMs += _timings[0].gpuFrameTime;
_timingCount++;
}

if (now >= _nextReport)
{
Report();
_nextReport = now + ReportSeconds;
}
}

private void Report()
{
if (_frameTimes.Count == 0)
{
return;
}

var sum = 0f;
foreach (var frameTime in _frameTimes)
{
sum += frameTime;
}

_frameTimes.Sort();
var p95 = _frameTimes[Mathf.Min(_frameTimes.Count - 1, (int)(_frameTimes.Count * 0.95f))];
var timings = _timingCount == 0
? "frame timing stats off"
: $"cpu main {_cpuMainMs / _timingCount:F2} ms, " +
$"cpu render {_cpuRenderMs / _timingCount:F2} ms, " +
$"gpu {_gpuMs / _timingCount:F2} ms";
_log.CallStatic<int>("i", LogTag,
$"{_mode} frames {_frameTimes.Count}, frame avg {sum / _frameTimes.Count:F2} ms, " +
$"p95 {p95:F2} ms, {timings}");

_frameTimes.Clear();
_cpuMainMs = _cpuRenderMs = _gpuMs = 0;
_timingCount = 0;
}
}
#endif
11 changes: 11 additions & 0 deletions samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,55 @@ public override void Configure(SentryUnityOptions options)
// - Miss some early errors that happen before the SDK initialized
#if UNITY_ANDROID
options.AndroidNativeInitializationType = NativeInitializationType.Runtime;
ConfigureSessionReplay(options);
#elif UNITY_IOS
options.IosNativeInitializationType = NativeInitializationType.Runtime;
#endif

Debug.Log("SentryOptionConfigure finished.");
}

#if UNITY_ANDROID
// Experimental session replay. Enabled at build time, so the build carries the replay library. At runtime, launch
// extras pick the mode: `adb shell am start -n <package>/com.unity3d.player.UnityPlayerActivity
// --es sentry_replay off|session|error --es sentry_replay_capture java|unity`. Without them, replays are sent for
// errors, with frames the Android SDK captures.
private static void ConfigureSessionReplay(SentryUnityOptions options)
{
var mode = Application.isEditor ? null : GetLaunchExtra("sentry_replay");
var capture = Application.isEditor ? null : GetLaunchExtra("sentry_replay_capture");
var replay = options.Experimental.SessionReplay;
switch (mode)
{
case "off":
break;
case "session":
replay.SessionSampleRate = 1.0;
break;
default:
replay.OnErrorSampleRate = 1.0;
break;
}

replay.Capture = capture == "unity" ? SessionReplayCapture.Unity : SessionReplayCapture.SentryJava;

Debug.Log($"Session replay mode: {mode ?? "error"}, capture: {replay.Capture}");
}

internal static string GetLaunchExtra(string name)
{
try
{
using var player = new AndroidJavaClass("com.unity3d.player.UnityPlayer");
using var activity = player.GetStatic<AndroidJavaObject>("currentActivity");
using var intent = activity.Call<AndroidJavaObject>("getIntent");
return intent.Call<string>("getStringExtra", name);
}
catch (Exception e)
{
Debug.LogWarning($"Failed to read the launch extra '{name}': {e.Message}");
return null;
}
}
#endif
}
31 changes: 31 additions & 0 deletions src/Sentry.Unity.Android/AndroidReplaySession.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
using System;
using Sentry.Internal;

namespace Sentry.Unity.Android;

/// <summary>
/// The replay that the Android SDK records, for the events captured in C#.
/// </summary>
internal sealed class AndroidReplaySession : IReplaySession
{
private readonly ISentryJava _sentryJava;

public AndroidReplaySession(ISentryJava sentryJava) => _sentryJava = sentryJava;

// The replay id on the native scope, not the recording's: a replay buffered for errors only gets one once an
// error captured it.
public SentryId? ActiveReplayId => ToReplayId(_sentryJava.GetReplayId());

public SentryId? CaptureReplay(SentryEvent @event) => ToReplayId(_sentryJava.CaptureReplay());

// The native SDK's empty id (all zeros) means no replay.
private static SentryId? ToReplayId(string? replayId)
{
if (replayId is null || !Guid.TryParse(replayId, out var guid) || guid == Guid.Empty)
{
return null;
}

return new SentryId(guid);
}
}
Loading
Loading