Home | History | Annotate | Download | only in dropwizard 
      1 # OpenCensus DropWizard Util for Java
      2 
      3 The *OpenCensus DropWizard Util for Java* provides an easy way to translate Dropwizard metrics to
      4 OpenCensus.
      5 
      6 ## Quickstart
      7 
      8 ### Prerequisites
      9 
     10 Assuming, you already have both the OpenCensus and Dropwizard client libraries setup and working
     11 inside your application.
     12 
     13 ### Add the dependencies to your project
     14 
     15 For 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 
     26 For Gradle add to your dependencies:
     27 ```gradle
     28 compile 'io.opencensus:opencensus-dropwizard:0.17.0'
     29 ```
     30 
     31 ### And the following code:
     32 
     33 ```java
     34 import java.util.Collections;
     35 
     36 public 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 
     61 This section describes how each of the DropWizard metrics translate into OpenCensus metrics.
     62 
     63 ### DropWizard Counters
     64 
     65 Given 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 
     73 Note: OpenCensus's CUMULATIVE_INT64 type represent monotonically increasing values. Since
     74 DropWizard Counter goes up/down, it make sense to report them as OpenCensus GAUGE_INT64.
     75 
     76 ### DropWizard Gauges
     77 
     78 Given 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 
     85 Note: For simplicity, OpenCensus uses GAUGE_DOUBLE type for any Number and GAUGE_INT64
     86 type for Boolean values.
     87 
     88 ### DropWizard Meters
     89 
     90 Given 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 
     99 Given 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 
    108 Given 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