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