xref: /aosp_15_r20/external/opencensus-java/contrib/dropwizard5/README.md (revision a24ffb47c3166327784aa05b149974e82e8f71b8) 
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