https://github.com/spotify/futuristic-feline
futuristic-feline is a library for detecting blocking Java futures at runtime
https://github.com/spotify/futuristic-feline
futures java
Last synced: 10 months ago
JSON representation
futuristic-feline is a library for detecting blocking Java futures at runtime
- Host: GitHub
- URL: https://github.com/spotify/futuristic-feline
- Owner: spotify
- License: apache-2.0
- Created: 2021-03-15T20:26:40.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-23T18:08:05.000Z (over 1 year ago)
- Last Synced: 2025-06-26T02:45:57.152Z (about 1 year ago)
- Topics: futures, java
- Language: Java
- Homepage:
- Size: 669 KB
- Stars: 12
- Watchers: 15
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-java - Futuristic Feline
README
# futuristic-feline
[](https://github.com/spotify/futuristic-feline/blob/main/LICENSE)
[](https://maven-badges.herokuapp.com/maven-central/com.spotify/futuristic-feline)
futuristic-feline is a library for detecting blocking Java futures at runtime. It is inspired by the excellent [BlockHound](https://github.com/reactor/BlockHound).
Writing asynchronous code is hard and blocking futures can lead to thread pool starvation. This has been a common source of incidents at Spotify and we monitor our services with this library to detect and fix services at risk.
## What does it do?
futuristic-feline detects when `Future.get()`, `CompletableFuture.get`, or `CompletableFuture.join` is called in a blocking fashion. That is, if they are called before being completed. futuristic-feline does this by injecting a check into these methods using byte code manipulation, and provides a callback function where you can act on any blocking calls, for example by collecting metrics or failing.
For example, the following will print to stdout on any blocking calls:
```java
Feline.addConsumerLast(System.out::println);
```
or throw an exception:
```java
Feline.addConsumerLast(call -> {throw new RuntimeException(call);});
```
To get started, add a dependency on:
```xml
com.spotify
futuristic-feline
$VERSION
```
## Metrics integration
It is often useful to create a metric for the rate of blocking calls. At Spotify we have built this into our service framework using [semantic-metrics](https://github.com/spotify/semantic-metrics).
If you use a different metrics collection framework, it should be straight-forward to integrate futuristic-feline. We're happy to accept contributions for other framework integrations.
### semantic-metrics integration
Add a dependency on:
```xml
com.spotify
futuristic-feline-semantic-metrics
$VERSION
```
Then install the `FelineMetricsRecorder`:
```java
FelineMetricsRecorder.install(new SemanticMetricRegistry());
```
This will create a meter tagged with `what: blocking-calls` and `call`
referring to the class and method name that called the blocking
`Future` or `CompletableFuture` method.
There is also a tag with `thread_name` referring to the thread that called
the blocking method. To prevent a metrics cardinality explosion, this
name is sanitized by replacing all integers with the character `N`.
Similarly, there's a meter to measure total time blocked:
`what: blocking-calls-time` measured in nano-seconds (also tagged with `unit: ns`)
with the same tags as above (`call` and `thread_name`).
You can customize how the caller is identified by
injecting a custom `CallFinder` to the `FelineMetricsRecorder` - take a look at the
code in `com.spotify.feline.FelineMetricsRecorder` for more detail.
## JUnit integration
Feline can also be used to detect blocking futures in your tests. We provide integration with Junit 4 and 5.
### JUnit 4
When using JUnit 4, you can add automatic detection of blocking calls to all tests by adding a dependency on:
```xml
com.spotify
futuristic-feline-junit4
$VERSION
test
```
And registering `FelineRunListener` with your JUnit runs. One way of doing this is with the Maven Surefire plugin:
```xml
maven-surefire-plugin
2.22.2
listener
com.spotify.feline.FelineRunListener
```
This will inject a `RunListener` that will fail tests on any blocking calls.
### JUnit 5
When using JUnit 5 (not vintage), you can add automatic detection of blocking calls to all tests simply by adding a dependency on:
```xml
com.spotify
futuristic-feline-junit5
$VERSION
test
```
This will inject a `TestExecutionListener` that will fail tests on any blocking calls.
### Ignoring blocking calls in tests
It's sometimes convenient to have blocking calls within your test methods themselves. In this case, you can ignore blocking calls by annotating your method:
```java
@Test
@IgnoreBlocking
public void ignoreBlockingJoin() {
final CompletableFuture future = CompletableFuture.runAsync(RUNNABLE);
// blocking, but works since we're ignoring blocking calls
future.join();
}
```
Note that this will still fail as `@IgnoreBlocking` only applies to the annotated method:
```
@Test
@IgnoreBlocking
public void indirectIgnoreBlockingJoin() {
blockingCall();
}
private void blockingCall() {
final CompletableFuture future = CompletableFuture.runAsync(RUNNABLE);
future.join();
}
```
## Development notes
### Test failures when IntelliJ's debugger is attached
If you are working on futuristic-feline and have a need to attach IntelliJ's debugger to a test, you might find that all tests that depend on applying FelineTransformer are failing for mysterious reasons.
It seems that in some versions of IntelliJ, the debugger will attach an agent of its own to the Java process that it launches to run tests, which interferes with how Feline sets up its own agent.
This can be easily addressed by opening IntelliJ's settings and under Build, Execution, Deployment > Debugger > Async Stack Traces, uncheck the box for "Instrumenting Agent":
References:
- https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000166640-Running-Debug-in-Java-can-t-find-CaptureAgent
- https://www.jetbrains.com/help/idea/async-stacktraces.html
## Code of Conduct
This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.
[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md
## Ownership
The Weaver squad is currently owning this project internally.
We are currently in the evaluating process of the ownership of this and other OSS Java libraries.
The ownership takes into account **ONLY** security maintenance.
This repo is also co-owned by other people:
* [mattnworb](https://github.com/mattnworb)
* [spkrka](https://github.com/spkrka)