README.md
1# OpenCensus DropWizard Util for Java
2
3The *OpenCensus DropWizard Util for Java* provides an easy way to translate Dropwizard metrics to
4OpenCensus.
5
6## Quickstart
7
8### Prerequisites
9
10Assuming, you already have both the OpenCensus and Dropwizard client libraries setup and working
11inside your application.
12
13### Add the dependencies to your project
14
15For Maven add to your `pom.xml`:
16```xml
17<dependencies>
18 <dependency>
19 <groupId>io.opencensus</groupId>
20 <artifactId>opencensus-contrib-dropwizard</artifactId>
21 <version>0.17.0</version>
22 </dependency>
23</dependencies>
24```
25
26For Gradle add to your dependencies:
27```gradle
28compile 'io.opencensus:opencensus-dropwizard:0.17.0'
29```
30
31### And the following code:
32
33```java
34import java.util.Collections;
35
36public class YourClass {
37 // Create registry for Dropwizard metrics.
38 static final com.codahale.metrics.MetricRegistry codahaleRegistry =
39 new com.codahale.metrics.MetricRegistry();
40
41 // Create a Dropwizard counter.
42 static final com.codahale.metrics.Counter requests = codahaleRegistry.counter("requests");
43
44 public static void main(String[] args) {
45
46 // Increment the requests.
47 requests.inc();
48
49 // Hook the Dropwizard registry into the OpenCensus registry
50 // via the DropWizardMetrics metric producer.
51 io.opencensus.metrics.Metrics.getExportComponent().getMetricProducerManager().add(
52 new io.opencensus.contrib.dropwizard.DropWizardMetrics(
53 Collections.singletonList(codahaleRegistry)));
54
55 }
56}
57```
58
59## Translation to OpenCensus Metrics
60
61This section describes how each of the DropWizard metrics translate into OpenCensus metrics.
62
63### DropWizard Counters
64
65Given a DropWizard Counter with name `cache_evictions`, the following values are reported:
66
67* name: codahale_<initial_metric_name>_<initial_type> (ex: codahale_cache_evictions_counter)
68* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
69(ex: Collected from Dropwizard (metric=cache_evictions, type=com.codahale.metrics.Counter))
70* type: GAUGE_INT64
71* unit: 1
72
73Note: OpenCensus's CUMULATIVE_INT64 type represent monotonically increasing values. Since
74DropWizard Counter goes up/down, it make sense to report them as OpenCensus GAUGE_INT64.
75
76### DropWizard Gauges
77
78Given a DropWizard Gauge with name `line_requests`, the following values are reported:
79
80* name: codahale_<initial_metric_name>_<initial_type> (ex: codahale_line_requests_gauge)
81* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
82* type: GAUGE_INT64 or GAUGE_DOUBLE
83* unit: 1
84
85Note: For simplicity, OpenCensus uses GAUGE_DOUBLE type for any Number and GAUGE_INT64
86type for Boolean values.
87
88### DropWizard Meters
89
90Given a DropWizard Meter with name `get_requests`, the following values are reported:
91
92* name: codahale_<initial_metric_name>_<initial_type> (ex: codahale_get_requests_meter)
93* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
94* type: CUMULATIVE_INT64
95* unit: 1
96
97### DropWizard Histograms
98
99Given a DropWizard Histogram with name `results`, the following values are reported:
100
101* name: codahale_<initial_metric_name>_<initial_type> (ex: codahale_results_histogram)
102* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
103* type: SUMMARY
104* unit: 1
105
106### DropWizard Timers
107
108Given a DropWizard Timer with name `requests`, the following values are reported:
109* name: codahale_<initial_metric_name>_<initial_type> (ex: codahale_requests_timer)
110* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
111* type: SUMMARY
112* unit: 1
113