Breadcrumbs documentation for device events #213

ueman · 2020-11-30T07:41:14Z

The documentation on breadcrumbs is missing device events like the ones which are used by Android.

See for example:

bruno-garcia · 2020-12-10T19:40:23Z

@ueman good catch. Is this something you'd like to contribute to?
We'd be happy to get a PR to address it.

ueman · 2020-12-10T19:50:04Z

No, I'm not knowledgeable enough on that topic. I've just stumbled across this missing pieces while working on getsentry/sentry-dart#203

bruno-garcia · 2020-12-10T20:02:19Z

Sure. Thanks for helping already with pointing it out.

ueman · 2020-12-11T07:29:46Z

On the Flutter side of https://github.com/getsentry/sentry-dart there are the following breadcrumbs:

🗺 Navigation

With the following extra data fields state, to_arguments, from_arguments. Also every data field is optional. The docs state that at least to and from are required, but from what I can tell it is not.

{
  "type": "navigation",
  "category": "navigation",
  "timestamp": "2016-04-20T20:55:53.845Z",
  "data": {
    "from": "/login",
    "from_arguments": "string or key-value-map",
    "to": "/dashboard",
    "to_arguments": "string or key-value-map",
    "state": "type of navigation, for example didPush"
  }
}

Navigation Lifecycle

This one doesn't really make sense to me. Why is category ui.lifecycle of type navigation?
It is copied from here just to be consistent.
Now that I do some research this should be analog to this.

{
  "type": "navigation",
  "category": "ui.lifecycle",
  "timestamp": "2016-04-20T20:55:53.845Z",
  "data": {
    "state": "new lifecycle state"
  }
}

Navigation Device

Same as above, why is it of type navigation?

{
  "message": "Screen size changed",
  "type": "navigation",
  "category": "device.screen",
  "timestamp": "2016-04-20T20:55:53.845Z",
  "data": {
    "new_pixel_ratio": 3,
    "new_height": 1920,
    "new_width": 1080,
  }
}

💻 System

This was created to mimic this. Again just to be consistent.
(I would love to have a dark breadcrumb in the UI for light/dark-mode changes)

{
  "message": "Platform brightness was changed to {dark|light}.",
  "type": "system",
  "category": "device.event",
  "timestamp": "2016-04-20T20:55:53.845Z",
  "data": {
    "action": "BRIGHTNESS_CHANGED_TO_{DARK|LIGHT}",
  }
}

{
  "message": "Text scale factor changed to {value}.",
  "type": "system",
  "category": "device.event",
  "timestamp": "2016-04-20T20:55:53.845Z",
  "data": {
    "action": "TEXT_SCALE_CHANGED_TO_{value}",
  }
}

{
  "message": "App had memory pressure. This indicates that the operating system would like applications to release caches to free up more memory.",
  "type": "system",
  "category": "device.event",
  "timestamp": "2016-04-20T20:55:53.845Z",
  "data": {
    "action": "LOW_MEMORY"
  }
}

❓ Concluding remarks & questions

It doesn't seem to be really consistent to me.

When do I have to use a type and when a category?
What sould I put inside the data field?
Which breadcrumbs have a visual representation and what do the look like?
When do I use a message for a breadcrumb?
Are there really any required breadcrumb fields?
Maybe also update this page?

I would really like to have examples for common breadcrumbs like navigation, lifecycle and system-events.
Maybe the client SDKs should have known types and category as constants, so that the user can reuse them more easily.

bruno-garcia · 2021-01-04T15:56:59Z

/cc @marandaneto

ueman · 2021-01-04T20:27:29Z

Sentry frontend code for reference

https://github.com/getsentry/sentry/blob/ea47737d936fcc1aea2ca051b714f6a58a3ae923/static/app/types/breadcrumbs.tsx

bruno-garcia · 2021-01-05T03:56:43Z

@lucas-zimerman for the Xamarin side

marandaneto · 2021-01-07T09:20:28Z

it's a bit confusing, true, but there's no guideline between type and category to be honest (afaik), they are open and nullable fields, our UI special case some of them and render nicely, but that's all, they are not documented either except a few of them like HTTP or click events, those are documented.

most of them are new values that we came up with for Android and iOS also to keep compatibility with older SDK versions.
I guess we'd be able to address this issue once we know which of them would be rendered nicely on the UI.

maybe @priscilawebdev would help.

bruno-garcia · 2021-01-13T14:38:04Z

@priscilawebdev is this something you can help us with? This seems to be a constant source of confusion to contributors and folks trying to implement a new SDK. Some clarifications on the docs could help here.

priscilawebdev · 2021-01-14T08:18:03Z

@bruno-garcia I'm glad you mentioned my name again because I was having trouble finding this issue ... Yes, I can help with that ... I just added this issue to my backlog and I will work on it as soon as I have some time 😉

ueman · 2021-04-28T14:18:21Z

ueman · 2021-04-30T16:43:24Z

Dart & Flutter

Already documented above

Java

Device Orientation

https://github.com/getsentry/sentry-java/blob/e1a7226bead691b2a824332f3d3a0930e68e33cc/sentry-android-core/src/main/java/io/sentry/android/core/AppComponentsBreadcrumbsIntegration.java#L89-L94

final Breadcrumb breadcrumb = new Breadcrumb();
breadcrumb.setType("navigation");
breadcrumb.setCategory("device.orientation");
breadcrumb.setData("position", orientation);
breadcrumb.setLevel(SentryLevel.INFO);

Low Memory

https://github.com/getsentry/sentry-java/blob/e1a7226bead691b2a824332f3d3a0930e68e33cc/sentry-android-core/src/main/java/io/sentry/android/core/AppComponentsBreadcrumbsIntegration.java#L108-L133

final Breadcrumb breadcrumb = new Breadcrumb();
breadcrumb.setType("system");
breadcrumb.setCategory("device.event");
breadcrumb.setMessage("Low memory");
breadcrumb.setData("action", "LOW_MEMORY");
breadcrumb.setLevel(SentryLevel.WARNING);

Lifecycle

https://github.com/getsentry/sentry-java/blob/e1a7226bead691b2a824332f3d3a0930e68e33cc/sentry-android-core/src/main/java/io/sentry/android/core/LifecycleWatcher.java#L120-L125

final Breadcrumb breadcrumb = new Breadcrumb();
breadcrumb.setType("navigation");
breadcrumb.setData("state", state);
breadcrumb.setCategory("app.lifecycle");
breadcrumb.setLevel(SentryLevel.INFO);

https://github.com/getsentry/sentry-java/blob/e1a7226bead691b2a824332f3d3a0930e68e33cc/sentry-android-core/src/main/java/io/sentry/android/core/LifecycleWatcher.java#L131-L135

final Breadcrumb breadcrumb = new Breadcrumb();
breadcrumb.setType("session");
breadcrumb.setData("state", state);
breadcrumb.setCategory("app.lifecycle");
breadcrumb.setLevel(SentryLevel.INFO);

Temperature Sensor

https://github.com/getsentry/sentry-java/blob/e1a7226bead691b2a824332f3d3a0930e68e33cc/sentry-android-core/src/main/java/io/sentry/android/core/TempSensorBreadcrumbsIntegration.java#L92-L99

final Breadcrumb breadcrumb = new Breadcrumb();
breadcrumb.setType("system");
breadcrumb.setCategory("device.event");
breadcrumb.setData("action", "TYPE_AMBIENT_TEMPERATURE");
breadcrumb.setData("accuracy", event.accuracy);
breadcrumb.setData("timestamp", event.timestamp);
breadcrumb.setLevel(SentryLevel.INFO);
breadcrumb.setData("degree", event.values[0]); // Celsius

Phone State

https://github.com/getsentry/sentry-java/blob/e1a7226bead691b2a824332f3d3a0930e68e33cc/sentry-android-core/src/main/java/io/sentry/android/core/PhoneStateBreadcrumbsIntegration.java#L94-L99

final Breadcrumb breadcrumb = new Breadcrumb();
breadcrumb.setType("system");
breadcrumb.setCategory("device.event");
breadcrumb.setData("action", "CALL_STATE_RINGING");
breadcrumb.setMessage("Device ringing");
breadcrumb.setLevel(SentryLevel.INFO);

System events

https://github.com/getsentry/sentry-java/blob/e1a7226bead691b2a824332f3d3a0930e68e33cc/sentry-android-core/src/main/java/io/sentry/android/core/SystemEventsBreadcrumbsIntegration.java#L176-L205

Here's a lot of different stuff.

Cocoa

Battery

https://github.com/getsentry/sentry-cocoa/blob/88c5af0a004951f1ea3ac6274686534fde03f5b3/Sources/Sentry/SentrySystemEventsBreadcrumbs.m#L78-L81

SentryBreadcrumb *crumb = [[SentryBreadcrumb alloc] initWithLevel:kSentryLevelInfo
                                                            category:@"device.event"];
crumb.type = @"system";
crumb.data = batteryData;

Device Orientation

https://github.com/getsentry/sentry-cocoa/blob/88c5af0a004951f1ea3ac6274686534fde03f5b3/Sources/Sentry/SentrySystemEventsBreadcrumbs.m#L127-L143

SentryBreadcrumb *crumb = [[SentryBreadcrumb alloc] initWithLevel:kSentryLevelInfo
                                                            category:@"device.orientation"];

UIDeviceOrientation currentOrientation = currentDevice.orientation;

// Ignore changes in device orientation if unknown, face up, or face down.
if (!UIDeviceOrientationIsValidInterfaceOrientation(currentOrientation)) {
    [SentryLog logWithMessage:@"currentOrientation is unknown." andLevel:kSentryLevelDebug];
    return;
}

if (UIDeviceOrientationIsLandscape(currentOrientation)) {
    crumb.data = @{ @"position" : @"landscape" };
} else {
    crumb.data = @{ @"position" : @"portrait" };
}
crumb.type = @"navigation";

System events

Xamarin

Xamarin Forms

Various System events

https://github.com/getsentry/sentry-xamarin/blob/63e764393415324f7fa0356e62d679d64f8d34ff/Src/Sentry.Xamarin.Forms/Internals/SentryXamarinFormsIntegration.cs

Theme changed
Logs
Navigation: Page appears, page disappears

Xamarin.iOS

https://github.com/getsentry/sentry-xamarin/blob/63e764393415324f7fa0356e62d679d64f8d34ff/Src/Sentry.Xamarin/Internals/NativeIntegration.ios.cs

Entered foreground, entered background
Low Memory Warning

Xamarin.Android

https://github.com/getsentry/sentry-xamarin/blob/63e764393415324f7fa0356e62d679d64f8d34ff/Src/Sentry.Xamarin/Internals/NativeIntegration.droid.cs

Activity Lifecycle

.NET

logging integrations

Cordova

none

React-Native

Touch events: https://github.com/getsentry/sentry-react-native/blob/c79e576a7d1c759c2c59b38030bb5440ca2c210d/src/js/touchevents.tsx

JavaScript

HTTP Breadcrumbs https://github.com/getsentry/sentry-javascript/blob/a6f8dc26a4c7ae2146ae64995a2018c8578896a6/packages/node/src/integrations/http.ts
Various events https://github.com/getsentry/sentry-javascript/blob/e80e0d818d0f3460eece94545ce8145cb18d176f/packages/utils/src/instrument.ts#L30-L39
- Console API
- Fetch API
- XHR API
- History API
- DOM API (click/typing)
- Error API
- UnhandledRejection API

Laravel

https://github.com/getsentry/sentry-laravel/blob/65ba0ea34ce124b48f50fb59b80c701bf76f4b12/src/Sentry/Laravel/EventHandler.php#L76-L109

SQL Queries
SQL Bindings
Logs
Queue Info
Commands (Artisan)

Navigation

https://github.com/getsentry/sentry-laravel/blob/65ba0ea34ce124b48f50fb59b80c701bf76f4b12/src/Sentry/Laravel/EventHandler.php#L223-L228

Integration::addBreadcrumb(new Breadcrumb(
    Breadcrumb::LEVEL_INFO,
    Breadcrumb::TYPE_NAVIGATION,
    'route',
    $routeName
));

Python

Sentry

Known types in Sentry
https://github.com/getsentry/sentry/blob/3deff6bd884a66ec711925f0984590a2075129e1/static/app/components/events/interfaces/breadcrumbs/getCrumbDetails.tsx#L18-L98

Documented types: https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/

Findings

There should be Low Memory Breadcrumb definition + icon
System events are not really consolidated and vary greatly in type, category and additional data.
- I think there's benefit in consolidation
There's no differentiation between user generated breadcrumbs and logs. I.e. Breadcrumbs generated via Logging integrations and Sentry.addBreadcrumb(new Breadcrumb(...)) called by the user directly
There's no guideline on which Breadcrumb should have which level/severity

krystofwoldrich · 2022-10-13T12:15:56Z

The breadcrumbs types should be added to https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/
And also the SDKs pages should be updated https://docs.sentry.io/platforms/android/enriching-events/breadcrumbs/#automatic-breadcrumbs

ueman mentioned this issue Dec 11, 2020

[sentry_flutter] Lifecycle breadcrumb is kinda wrong getsentry/sentry-dart#240

Closed

bruno-garcia added the up-for-grabs label Jan 4, 2021

ueman mentioned this issue Apr 27, 2021

Feature: Log print() calls as Breadcrumbs getsentry/sentry-dart#439

Merged

5 tasks

marandaneto added Platform: Android Platform: Cocoa Platform: .NET Platform: React-Native Platform: Dart labels Oct 7, 2022

marandaneto added this to Mobile & Cross Platform SDK Oct 7, 2022

marandaneto moved this to Needs Discussion in Mobile & Cross Platform SDK Oct 7, 2022

krystofwoldrich moved this from Needs Discussion to Backlog in Mobile & Cross Platform SDK Oct 13, 2022

kahest moved this from Backlog to Done in Mobile & Cross Platform SDK Dec 18, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Breadcrumbs documentation for device events #213

Breadcrumbs documentation for device events #213

ueman commented Nov 30, 2020 •

edited

Loading

bruno-garcia commented Dec 10, 2020

ueman commented Dec 10, 2020

bruno-garcia commented Dec 10, 2020

ueman commented Dec 11, 2020 •

edited

Loading

bruno-garcia commented Jan 4, 2021

ueman commented Jan 4, 2021 •

edited

Loading

bruno-garcia commented Jan 5, 2021

marandaneto commented Jan 7, 2021

bruno-garcia commented Jan 13, 2021

priscilawebdev commented Jan 14, 2021

ueman commented Apr 28, 2021 •

edited

Loading

ueman commented Apr 30, 2021 •

edited

Loading

krystofwoldrich commented Oct 13, 2022

Breadcrumbs documentation for device events #213

Breadcrumbs documentation for device events #213

Comments

ueman commented Nov 30, 2020 • edited Loading

bruno-garcia commented Dec 10, 2020

ueman commented Dec 10, 2020

bruno-garcia commented Dec 10, 2020

ueman commented Dec 11, 2020 • edited Loading

🗺 Navigation

Navigation Lifecycle

Navigation Device

💻 System

❓ Concluding remarks & questions

bruno-garcia commented Jan 4, 2021

ueman commented Jan 4, 2021 • edited Loading

bruno-garcia commented Jan 5, 2021

marandaneto commented Jan 7, 2021

bruno-garcia commented Jan 13, 2021

priscilawebdev commented Jan 14, 2021

ueman commented Apr 28, 2021 • edited Loading

ueman commented Apr 30, 2021 • edited Loading

Dart & Flutter

Java

Device Orientation

Low Memory

Lifecycle

Temperature Sensor

Phone State

System events

Cocoa

Battery

Device Orientation

System events

Xamarin

Xamarin Forms

Xamarin.iOS

Xamarin.Android

.NET

Cordova

React-Native

JavaScript

Laravel

Navigation

Python

Sentry

Findings

krystofwoldrich commented Oct 13, 2022

ueman commented Nov 30, 2020 •

edited

Loading

ueman commented Dec 11, 2020 •

edited

Loading

ueman commented Jan 4, 2021 •

edited

Loading

ueman commented Apr 28, 2021 •

edited

Loading

ueman commented Apr 30, 2021 •

edited

Loading