RxDogTag

Automatic tagging of RxJava 2 originating subscribe points for onError() investigation.

License	License The Apache Software License, Version 2.0
GroupId	GroupId com.uber.rxdogtag2
ArtifactId	ArtifactId rxdogtag
Last Version	Last Version 2.0.1
Release Date	Release Date Oct 26, 2020
Type	Type jar
Description	Description RxDogTag Automatic tagging of RxJava 2 originating subscribe points for onError() investigation.
Project URL	Project URL https://github.com/uber/RxDogTag/
Source Code Management	Source Code Management https://github.com/uber/RxDogTag/

Download rxdogtag

Filename	Size
rxdogtag-2.0.1.pom
rxdogtag-2.0.1.jar	20 KB
rxdogtag-2.0.1-sources.jar	15 KB
rxdogtag-2.0.1-javadoc.jar	33 KB
Browse

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/com.uber.rxdogtag2/rxdogtag/ -->
<dependency>
    <groupId>com.uber.rxdogtag2</groupId>
    <artifactId>rxdogtag</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/com.uber.rxdogtag2/rxdogtag/
implementation 'com.uber.rxdogtag2:rxdogtag:2.0.1'

Gradle Kotlin

// https://jarcasting.com/artifacts/com.uber.rxdogtag2/rxdogtag/
implementation ("com.uber.rxdogtag2:rxdogtag:2.0.1")

Apache Buildr

'com.uber.rxdogtag2:rxdogtag:jar:2.0.1'

Apache Ivy

<dependency org="com.uber.rxdogtag2" name="rxdogtag" rev="2.0.1">
  <artifact name="rxdogtag" type="jar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='com.uber.rxdogtag2', module='rxdogtag', version='2.0.1')
)

Scala SBT

libraryDependencies += "com.uber.rxdogtag2" % "rxdogtag" % "2.0.1"

Leiningen

[com.uber.rxdogtag2/rxdogtag "2.0.1"]

Dependencies

compile (1)

Group / Artifact	Type	Version
io.reactivex.rxjava3 : rxjava	jar	3.0.0

test (2)

Group / Artifact	Type	Version
junit : junit	jar	4.12
com.google.truth : truth	jar	1.0.1

Project Modules

There are no modules declared in this project.

RxDogTag

RxDogTag is a utility to tag originating subscribe points in RxJava 2+ observers, with the goal of surfacing their subscribe locations for error reporting/investigation later in the event of an unhandled error. This is only for RxJava observers that do not implement onError().

Download

If you're targeting RxJava 2:

implementation("com.uber.rxdogtag:rxdogtag:x.y.z")

If you're targeting RxJava 3:

implementation("com.uber.rxdogtag2:rxdogtag:x.y.z")

Setup

Install early in your application lifecycle via RxDogTag.install(). This will install the necessary hooks in RxJavaPlugins. Note that these will replace any existing plugins at the hooks it uses. See the JavaDoc for full details of which plugins it uses.

Example

Consider the following classic RxJava error:

Observable.range(0, 10)
    .subscribeOn(Schedulers.io())
    .map(i -> null)
    .subscribe();

This is a fairly common case in RxJava concurrency. Without tagging, this yields the following trace:

io.reactivex.exceptions.OnErrorNotImplementedException: The exception was not handled due to missing onError handler in the subscribe() method call. Further reading: https://github.com/ReactiveX/RxJava/wiki/Error-Handling | The mapper function returned a null value.
	at io.reactivex.internal.functions.Functions$OnErrorMissingConsumer.accept(Functions.java:704)
	at io.reactivex.internal.functions.Functions$OnErrorMissingConsumer.accept(Functions.java:701)
	at io.reactivex.internal.observers.LambdaObserver.onError(LambdaObserver.java:77)
	at io.reactivex.internal.observers.BasicFuseableObserver.onError(BasicFuseableObserver.java:100)
	at io.reactivex.internal.observers.BasicFuseableObserver.fail(BasicFuseableObserver.java:110)
	at io.reactivex.internal.operators.observable.ObservableMap$MapObserver.onNext(ObservableMap.java:59)
	at io.reactivex.internal.operators.observable.ObservableSubscribeOn$SubscribeOnObserver.onNext(ObservableSubscribeOn.java:58)
	at io.reactivex.internal.operators.observable.ObservableScalarXMap$ScalarDisposable.run(ObservableScalarXMap.java:248)
	at io.reactivex.internal.operators.observable.ObservableJust.subscribeActual(ObservableJust.java:35)
	at io.reactivex.Observable.subscribe(Observable.java:12090)
	at io.reactivex.internal.operators.observable.ObservableSubscribeOn$SubscribeTask.run(ObservableSubscribeOn.java:96)
	at io.reactivex.Scheduler$DisposeTask.run(Scheduler.java:578)
	at io.reactivex.internal.schedulers.ScheduledRunnable.run(ScheduledRunnable.java:66)
	at io.reactivex.internal.schedulers.ScheduledRunnable.call(ScheduledRunnable.java:57)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.access$201(ScheduledThreadPoolExecutor.java:180)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:293)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
	at java.lang.Thread.run(Thread.java:748)
Caused by: java.lang.NullPointerException: The mapper function returned a null value.
	at io.reactivex.internal.functions.ObjectHelper.requireNonNull(ObjectHelper.java:39)
	at io.reactivex.internal.operators.observable.ObservableMap$MapObserver.onNext(ObservableMap.java:57)
	... 14 more

This is basically impossible to investigate if you're looking at a crash report from the wild.

Now the same error with RxDogTag enabled:

io.reactivex.exceptions.OnErrorNotImplementedException: The mapper function returned a null value.

Caused by: java.lang.NullPointerException: The mapper function returned a null value.
	at anotherpackage.ReadMeExample.complex(ReadMeExample.java:55)
	at [[ ↑↑ Inferred subscribe point ↑↑ ]].(:0)
	at [[ ↓↓ Original trace ↓↓ ]].(:0)
	at io.reactivex.internal.functions.ObjectHelper.requireNonNull(ObjectHelper.java:39)
	at io.reactivex.internal.operators.observable.ObservableMap$MapObserver.onNext(ObservableMap.java:57)
	at io.reactivex.internal.operators.observable.ObservableSubscribeOn$SubscribeOnObserver.onNext(ObservableSubscribeOn.java:58)
	at io.reactivex.internal.operators.observable.ObservableScalarXMap$ScalarDisposable.run(ObservableScalarXMap.java:248)
	at io.reactivex.internal.operators.observable.ObservableJust.subscribeActual(ObservableJust.java:35)
	at io.reactivex.Observable.subscribe(Observable.java:12090)
	at io.reactivex.internal.operators.observable.ObservableSubscribeOn$SubscribeTask.run(ObservableSubscribeOn.java:96)
	at io.reactivex.Scheduler$DisposeTask.run(Scheduler.java:578)
	at io.reactivex.internal.schedulers.ScheduledRunnable.run(ScheduledRunnable.java:66)
	at io.reactivex.internal.schedulers.ScheduledRunnable.call(ScheduledRunnable.java:57)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.access$201(ScheduledThreadPoolExecutor.java:180)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:293)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
	at java.lang.Thread.run(Thread.java:748)

Now we have the example subscribe line at ReadMeExample.java:55. It may not be a silver bullet to root-causing why the exception occurred, but at least you know where it's emanating from.

The subscribe line reported should also retrace and group well for crash reporting. As we use our own in-house reporter though, we're very open to feedback on how this can be improved for other solutions.

More examples and details can be found in the wiki

Configuration

RxDogTag has an alternative RxDogTag.builder() API to facilitate added configuration, such as annotation control, stacktrace element location, and more.

Custom handlers

In the event of custom observers that possibly decorate other observer types, this information can be passed to RxDogTag via the ObserverHandler interface. This interface can be used to unwrap these custom observers to reveal their delegates and their potential behavior. Install these via the RxDogTag.Builder#addObserverHandlers(...) overloads that accept handlers.

Ignored packages

RxDogTag needs to ignore certain packages (such as its own or RxJava's) when inspecting stack traces to deduce the subscribe point. You can add other custom ones via RxDogTag.Builder#addIgnoredPackages(...).

AutoDispose support

AutoDispose is a library for automatically disposing streams, and works via its own decorating observers under the hood. AutoDispose can work with RxDogTag via its delegateObserver() APIs on the AutoDisposingObserver interfaces. Support for this is available via separate rxdogtag-autodispose artifact and its AutoDisposeObserverHandler singleton instance.

RxDogTag.builder()
    .configureWith(AutoDisposeConfigurer::configure)
    .install();

If you're targeting RxJava 2:

implementation("com.uber.rxdogtag:rxdogtag-autodispose:x.y.z")

If you're targeting RxJava 3:

implementation("com.uber.rxdogtag2:rxdogtag-autodispose:x.y.z")

Development

Javadocs for the most recent release can be found here: https://uber.github.io/RxDogTag/0.x/rxdogtag/com.uber.rxdogtag/

Snapshots of the development version are available in Sonatype's snapshots repository.

License

Copyright (C) 2019 Uber Technologies

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Uber Open Source

Open Source Software at Uber

Versions

Version
2.0.1 Oct 26, 2020
2.0.0 Mar 8, 2020

RxDogTag

License

GroupId

ArtifactId

Last Version

Release Date

Type

Description

Project URL

Source Code Management

Download rxdogtag

How to add to project

Dependencies

compile (1)

test (2)

Project Modules

RxDogTag

Download

Setup

Example

Configuration

Custom handlers

Ignored packages

AutoDispose support

Development

License

Uber Open Source

Versions