Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/palantir/tritium
Tritium is a library for instrumenting applications to provide better observability at runtime
https://github.com/palantir/tritium
instrumentation java octo-correct-managed
Last synced: about 17 hours ago
JSON representation
Tritium is a library for instrumenting applications to provide better observability at runtime
- Host: GitHub
- URL: https://github.com/palantir/tritium
- Owner: palantir
- License: apache-2.0
- Created: 2016-08-18T18:23:06.000Z (about 8 years ago)
- Default Branch: develop
- Last Pushed: 2024-04-12T22:25:49.000Z (7 months ago)
- Last Synced: 2024-04-14T16:07:53.881Z (7 months ago)
- Topics: instrumentation, java, octo-correct-managed
- Language: Java
- Homepage:
- Size: 3.31 MB
- Stars: 44
- Watchers: 260
- Forks: 12
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: changelog/0.15.0/pr-308.v2.yml
- License: LICENSE
Awesome Lists containing this project
README
# [Tritium](https://github.com/palantir/tritium)
Tritium is a library for instrumenting applications to provide better observability at runtime. Tritium allows for instrumentation of service interfaces through a Java proxy, providing call backs to extensible invocation event handlers. Two main invocation handlers currently provided are:
* Metrics - records aggregate service time and call rates using Dropwizard metrics
* Logging - logs individual service times
## Why Tritium?
Tritium gives us aggregate metrics for the various services exposed and consumed by a server.
* invocation response times (including min, average, max, percentile distribution, request count and 1, 5, and 15 rates)
* cache effectiveness (eviction count, hit count, hit ratio, load average millis, load failure count, load success count, miss count, miss ratio, request count)
These metrics can be exposed at the Dropwizard ``MetricsServlet`` and can be exported via any of the [Dropwizard provided reporters](http://metrics.dropwizard.io/3.1.0/manual/core/#reporters).
## Basic Usage
### Instrumenting a service using the Tritium annotation processor
The `tritium-processor` annotation processor must be applied to the annotation processor scope, and `tritium-annotations` must be available at both build and runtime.
Example using gradle, however all modern build systems are capable of registering annotation processors:
```gradle
dependencies {
implementation 'com.palantir.tritium:tritium-annotations'
annotationProcessor 'com.palantir.tritium:tritium-processor'
}
```
Apply the `@Instrument` annotation to methods on an interface. Only the annotated methods will be instrumented.
```java
interface Service {
@Instrument
String getGreeting();
}
```
You can also apply the `@Instrument` annotation to the interface itself to instrument all methods.
```java
@Instrument
interface Service {
String getGreeting();
}
```
If the interface is defined externally, a new interface may be defined which extends the target interface. The `@Instrument` annotation may be applied to either individual methods or the interface itself.
```java
interface DelegateSupplier extends Supplier {
@Instrument
@Override
String get();
}
```
```java
@Instrument
interface DelegateSupplier extends Supplier {}
```
This generates the `InstrumentedService` wrapper implementation equivalent to the legacy dynamic proxy, with less overhead.
```java
Service interestingService = ...
Service instrumentedService =
InstrumentedService.instrument(interestingService, environment.metrics());
```
### Instrumenting a service interface of a dropwizard application with default metrics timers and optional trace logging.
_Prefer using the annotation processor whenever possible_
```java
import com.palantir.tritium.Tritium;
Service interestingService = ...
Service instrumentedService = Tritium.instrument(Service.class,
interestingService, environment.metrics());
```
## Instrumenting a [Caffeine cache](https://github.com/ben-manes/caffeine/)
```java
import com.palantir.tritium.metrics.caffeine.CacheStats;
TaggedMetricRegistry taggedMetricRegistry = ...
Cache cache = CacheStats.of(taggedMetricRegistry, "unique-cache-name")
.register(stats -> Caffeine.newBuilder()
.recordStats(stats)
.build());
LoadingCache loadingCache = CacheStats.of(taggedMetricRegistry, "unique-loading-cache-name")
.register(stats -> Caffeine.newBuilder()
.recordStats(stats)
.build(key::length);
```
## Creating a metric registry with reservoirs backed by [HDR Histograms](https://hdrhistogram.github.io/HdrHistogram/).
HDR histograms are more useful if the service is long running, so the stats represents the lifetime of the server rather than using default exponential decay which can lead to some mis-interpretations of timings (especially higher percentiles and things like max dropping over time) if the consumer isn't aware of these assumptions.
Note that the Histogram collects metrics throughout the lifetime of the service.
### Dropwizard 0.9+ Integration
```java
@Override
public void initialize(Bootstrap bootstrap) {
super.initialize(bootstrap);
bootstrap.setMetricRegistry(MetricRegistries.createWithHdrHistogramReservoirs());
...
}
```
License
-------
This project is made available under the
[Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).