1*a24ffb47SSadaf Ebrahimi# OpenCensus Agent for Java 2*a24ffb47SSadaf Ebrahimi 3*a24ffb47SSadaf Ebrahimi[![Build Status][travis-image]][travis-url] 4*a24ffb47SSadaf Ebrahimi[![Windows Build Status][appveyor-image]][appveyor-url] 5*a24ffb47SSadaf Ebrahimi[![Maven Central][maven-image]][maven-url] 6*a24ffb47SSadaf Ebrahimi 7*a24ffb47SSadaf EbrahimiThe *OpenCensus Agent for Java* collects and sends latency data about your Java process to 8*a24ffb47SSadaf EbrahimiOpenCensus backends such as Zipkin, Stackdriver Trace, etc. for analysis and visualization. 9*a24ffb47SSadaf Ebrahimi 10*a24ffb47SSadaf Ebrahimi 11*a24ffb47SSadaf Ebrahimi## Features 12*a24ffb47SSadaf Ebrahimi 13*a24ffb47SSadaf EbrahimiThe *OpenCensus Agent for Java* is in an early development stage. The following features are 14*a24ffb47SSadaf Ebrahimicurrently implemented: 15*a24ffb47SSadaf Ebrahimi 16*a24ffb47SSadaf EbrahimiTODO(stschmidt): Update README.md along with implementation. 17*a24ffb47SSadaf Ebrahimi 18*a24ffb47SSadaf Ebrahimi 19*a24ffb47SSadaf Ebrahimi### Automatic context propagation for Executors 20*a24ffb47SSadaf Ebrahimi 21*a24ffb47SSadaf EbrahimiThe context of the caller of [Executor#execute](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executor.html#execute-java.lang.Runnable-) 22*a24ffb47SSadaf Ebrahimiis automatically propagated to the submitted Runnable. 23*a24ffb47SSadaf Ebrahimi 24*a24ffb47SSadaf Ebrahimi 25*a24ffb47SSadaf Ebrahimi### Automatic context propagation for Threads 26*a24ffb47SSadaf Ebrahimi 27*a24ffb47SSadaf EbrahimiThe context of the caller of [Thread#start](https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#start--) 28*a24ffb47SSadaf Ebrahimiis automatically propagated to the new thread. 29*a24ffb47SSadaf Ebrahimi 30*a24ffb47SSadaf Ebrahimi 31*a24ffb47SSadaf Ebrahimi### Preliminary support for tracing 32*a24ffb47SSadaf Ebrahimi 33*a24ffb47SSadaf EbrahimiAs a proof-of-concept, the agent wraps the execution of 34*a24ffb47SSadaf Ebrahimi[URL#getContent](https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#getContent--) in a new 35*a24ffb47SSadaf Ebrahimitrace span. 36*a24ffb47SSadaf Ebrahimi 37*a24ffb47SSadaf Ebrahimi 38*a24ffb47SSadaf Ebrahimi## Design Ideas 39*a24ffb47SSadaf Ebrahimi 40*a24ffb47SSadaf EbrahimiWe see tracing as a cross-cutting concern which the *OpenCensus Agent for Java* weaves into 41*a24ffb47SSadaf Ebrahimiexisting Java bytecode (the application and its libraries) at runtime, typically when first loading 42*a24ffb47SSadaf Ebrahimithe concerned bytecode. 43*a24ffb47SSadaf Ebrahimi 44*a24ffb47SSadaf EbrahimiThis approach allows us to instrument arbitrary code without having to touch the source code of the 45*a24ffb47SSadaf Ebrahimiapplication or its dependencies. Furthermore, we don't require the application owner to upgrade any 46*a24ffb47SSadaf Ebrahimiof the application's third-party dependencies to specific versions. As long as the interface (e.g. 47*a24ffb47SSadaf Ebrahimi[java.sql.Driver#connect](https://docs.oracle.com/javase/8/docs/api/java/sql/Driver.html#connect-java.lang.String-java.util.Properties-)) 48*a24ffb47SSadaf Ebrahimistays as-is across the supported versions, the Java agent's bytecode weaver will be able to 49*a24ffb47SSadaf Ebrahimiinstrument the code. 50*a24ffb47SSadaf Ebrahimi 51*a24ffb47SSadaf EbrahimiThe *OpenCensus Agent for Java* uses [Byte Buddy](http://bytebuddy.net/), a widely used and 52*a24ffb47SSadaf Ebrahimiwell-maintained bytecode manipulation library, for instrumenting selected Java methods at class 53*a24ffb47SSadaf Ebrahimiload-time. Which Java methods we want to intercept/instrument obviously depends on the library 54*a24ffb47SSadaf Ebrahimi(MongoDB vs. Redis, etc.) and the application. 55*a24ffb47SSadaf Ebrahimi 56*a24ffb47SSadaf Ebrahimi 57*a24ffb47SSadaf Ebrahimi## Installation and Usage 58*a24ffb47SSadaf Ebrahimi 59*a24ffb47SSadaf EbrahimiDownload the latest version of the *OpenCensus Agent for Java* `.jar` file 60*a24ffb47SSadaf Ebrahimifrom [Maven Central][maven-url]. Store it somewhere on disk. 61*a24ffb47SSadaf Ebrahimi 62*a24ffb47SSadaf EbrahimiTo enable the *OpenCensus Agent for Java* for your application, add the option 63*a24ffb47SSadaf Ebrahimi`-javaagent:path/to/opencensus-contrib-agent-X.Y.Z.jar` to the invocation of the `java` 64*a24ffb47SSadaf Ebrahimiexecutable as shown in the following example. Replace `X.Y.Z` with the actual version number. 65*a24ffb47SSadaf Ebrahimi 66*a24ffb47SSadaf Ebrahimi```bash 67*a24ffb47SSadaf Ebrahimijava -javaagent:path/to/opencensus-contrib-agent-X.Y.Z.jar ... 68*a24ffb47SSadaf Ebrahimi``` 69*a24ffb47SSadaf Ebrahimi 70*a24ffb47SSadaf Ebrahimi 71*a24ffb47SSadaf Ebrahimi## Configuration 72*a24ffb47SSadaf Ebrahimi 73*a24ffb47SSadaf EbrahimiThe *OpenCensus Agent for Java* uses [Typesafe's configuration 74*a24ffb47SSadaf Ebrahimilibrary](https://lightbend.github.io/config/) for all user-configurable settings. Please refer to 75*a24ffb47SSadaf Ebrahimi[reference.conf](src/main/resources/reference.conf) for the available configuration knobs and their 76*a24ffb47SSadaf Ebrahimidefaults. 77*a24ffb47SSadaf Ebrahimi 78*a24ffb47SSadaf EbrahimiYou can override the default configuration in [different 79*a24ffb47SSadaf Ebrahimiways](https://github.com/lightbend/config/blob/7cae92d3ae3ff9d06f1db43800232d2f73c6fe44/README.md#standard-behavior). 80*a24ffb47SSadaf EbrahimiFor example, to disable the automatic context propagation for Executors, add a system property as 81*a24ffb47SSadaf Ebrahimifollows: 82*a24ffb47SSadaf Ebrahimi 83*a24ffb47SSadaf Ebrahimi```bash 84*a24ffb47SSadaf Ebrahimijava -javaagent:path/to/opencensus-contrib-agent-X.Y.Z.jar \ 85*a24ffb47SSadaf Ebrahimi -Dopencensus.contrib.agent.context-propagation.executor.enabled=false \ 86*a24ffb47SSadaf Ebrahimi ... 87*a24ffb47SSadaf Ebrahimi``` 88*a24ffb47SSadaf Ebrahimi 89*a24ffb47SSadaf Ebrahimi 90*a24ffb47SSadaf Ebrahimi[travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master 91*a24ffb47SSadaf Ebrahimi[travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java 92*a24ffb47SSadaf Ebrahimi[appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true 93*a24ffb47SSadaf Ebrahimi[appveyor-url]: https://ci.appveyor.com/project/opencensusjavateam/opencensus-java/branch/master 94*a24ffb47SSadaf Ebrahimi[maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-agent/badge.svg 95*a24ffb47SSadaf Ebrahimi[maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-agent 96
