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-dropwizard5</artifactId>
21 <version>0.28.3</version>
22 </dependency>
23</dependencies>
24```
25
26For Gradle add to your dependencies:
27```groovy
28compile 'io.opencensus:opencensus-contrib-dropwizard5:0.28.3'
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 io.dropwizard.metrics5.MetricRegistry codahaleRegistry =
39 new io.dropwizard.metrics5.MetricRegistry();
40
41 // Create a Dropwizard counter.
42 Map<String, String> tags = new HashMap<>();
43 tags.put("tag1", "value1");
44 tags.put("tag2", "value2");
45 static final io.dropwizard.metrics5.Counter requests =
46 codahaleRegistry.counter(new MetricName("requests", tags));
47
48 public static void main(String[] args) {
49
50 // Increment the requests.
51 requests.inc();
52
53 // Hook the Dropwizard registry into the OpenCensus registry
54 // via the DropWizardMetrics metric producer.
55 io.opencensus.metrics.Metrics.getExportComponent().getMetricProducerManager().add(
56 new io.opencensus.contrib.dropwizard.DropWizardMetrics(
57 Collections.singletonList(codahaleRegistry)));
58
59 }
60}
61```
62
63## Translation to OpenCensus Metrics
64
65This section describes how each of the DropWizard metrics translate into OpenCensus metrics.
66
67### DropWizard Counters
68
69Given a DropWizard Counter with name `cache_evictions`, the following values are reported:
70
71* name: dropwizard5_<initial_metric_name>_<initial_type> (ex: codahale_cache_evictions_counter)
72* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
73(ex: Collected from Dropwizard (metric=cache_evictions, type=io.dropwizard.metrics5.Counter))
74* type: GAUGE_INT64
75* unit: 1
76* labels: metrics tags are converted to label keys/values
77
78Note: OpenCensus's CUMULATIVE_INT64 type represent monotonically increasing values. Since
79DropWizard Counter goes up/down, it make sense to report them as OpenCensus GAUGE_INT64.
80
81### DropWizard Gauges
82
83Given a DropWizard Gauge with name `line_requests`, the following values are reported:
84
85* name: dropwizard5_<initial_metric_name>_<initial_type> (ex: codahale_line_requests_gauge)
86* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
87* type: GAUGE_INT64 or GAUGE_DOUBLE
88* unit: 1
89* labels: metrics tags are converted to label keys/values
90
91
92Note: For simplicity, OpenCensus uses GAUGE_DOUBLE type for any Number and GAUGE_INT64
93type for Boolean values.
94
95### DropWizard Meters
96
97Given a DropWizard Meter with name `get_requests`, the following values are reported:
98
99* name: dropwizard5_<initial_metric_name>_<initial_type> (ex: codahale_get_requests_meter)
100* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
101* type: CUMULATIVE_INT64
102* unit: 1
103* labels: metrics tags are converted to label keys/values
104
105
106### DropWizard Histograms
107
108Given a DropWizard Histogram with name `results`, the following values are reported:
109
110* name: dropwizard5_<initial_metric_name>_<initial_type> (ex: codahale_results_histogram)
111* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
112* type: SUMMARY
113* unit: 1
114* labels: metrics tags are converted to label keys/values
115
116
117### DropWizard Timers
118
119Given a DropWizard Timer with name `requests`, the following values are reported:
120* name: dropwizard5_<initial_metric_name>_<initial_type> (ex: codahale_requests_timer)
121* description: Collected from Dropwizard (metric=<metric_name>, type=<class_name>)
122* type: SUMMARY
123* unit:
124* labels: metrics tags are converted to label keys/values
125
126