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

See for example:

https://github.com/getsentry/sentry-java/blob/main/sentry-android-core/src/main/java/io/sentry/android/core/PhoneStateBreadcrumbsIntegration.java#L95-L97
https://github.com/getsentry/sentry-java/blob/main/sentry-android-core/src/main/java/io/sentry/android/core/AppComponentsBreadcrumbsIntegration.java#L75-L96

Nov 30 '20 07:11 ueman

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

Dec 10 '20 19:12 bruno-garcia

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

Dec 10 '20 19:12 ueman

Sure. Thanks for helping already with pointing it out.

Dec 10 '20 20:12 bruno-garcia

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.

Dec 11 '20 07:12 ueman

/cc @marandaneto

Jan 04 '21 15:01 bruno-garcia

Sentry frontend code for reference

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

Jan 04 '21 20:01 ueman

@lucas-zimerman for the Xamarin side

Jan 05 '21 03:01 bruno-garcia

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.

Jan 07 '21 09:01 marandaneto

@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.

Jan 13 '21 14:01 bruno-garcia

@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 😉

Jan 14 '21 08:01 priscilawebdev

So what exactly would need to be done here?

[ ] Collect all the different kinds of Breadcrumbs across repos. For example
- [x] Dart & Flutter
- [x] Java
- [x] Cocoa
- [x] .NET & Xamarin
- [x] Cordova, React-Native, JavaScript
- [x] Laravel
- [x] Python
- [ ] Rust
[ ] See which Breadcrumbs have a special design in Sentry & maybe look for Breadcrumbs which could profit from a special design
[ ] See what's identical and where it differs
[ ] Document findings

Apr 28 '21 14:04 ueman

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

Screenshot https://github.com/getsentry/sentry-cocoa/blob/88c5af0a004951f1ea3ac6274686534fde03f5b3/Sources/Sentry/SentrySystemEventsBreadcrumbs.m#L172-L179
Keyboard visibility https://github.com/getsentry/sentry-cocoa/blob/88c5af0a004951f1ea3ac6274686534fde03f5b3/Sources/Sentry/SentrySystemEventsBreadcrumbs.m#L147-L161

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

Logging https://github.com/getsentry/sentry-python/blob/4c09f3203d6d19789c6fa729a2e46557ad4ea913/sentry_sdk/integrations/logging.py
HTTP https://github.com/getsentry/sentry-python/blob/4c09f3203d6d19789c6fa729a2e46557ad4ea913/tests/integrations/stdlib/test_httplib.py#L29-L47

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

Apr 30 '21 16:04 ueman

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

Oct 13 '22 12:10 krystofwoldrich

develop
develop copied to clipboard

Breadcrumbs documentation for device events

🗺 Navigation

Navigation Lifecycle

Navigation Device

💻 System

❓ Concluding remarks & questions

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

develop develop copied to clipboard

Breadcrumbs documentation for device events

🗺 Navigation

Navigation Lifecycle

Navigation Device

💻 System

❓ Concluding remarks & questions

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

develop
develop copied to clipboard