search

getsentry / develop

https://develop.sentry.dev
Other
56 stars 224 forks source link

Breadcrumbs documentation for device events #213

Open ueman opened 3 years ago

ueman commented 3 years ago

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

See for example:

bruno-garcia commented 3 years ago

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

ueman commented 3 years ago

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

bruno-garcia commented 3 years ago

Sure. Thanks for helping already with pointing it out.

ueman commented 3 years ago

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.

  1. When do I have to use a type and when a category?
  2. What sould I put inside the data field?
  3. Which breadcrumbs have a visual representation and what do the look like?
  4. When do I use a message for a breadcrumb?
  5. Are there really any required breadcrumb fields?
  6. 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 commented 3 years ago

/cc @marandaneto

ueman commented 3 years ago

Sentry frontend code for reference

bruno-garcia commented 3 years ago

@lucas-zimerman for the Xamarin side

marandaneto commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

@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 commented 3 years ago

So what exactly would need to be done here?

ueman commented 3 years ago

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

Xamarin.iOS

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

Xamarin.Android

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

.NET

Cordova

React-Native

JavaScript

Laravel

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

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

krystofwoldrich commented 2 years ago

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