Home | History | Annotate | only in /external/opencensus-java/contrib/agent
Up to higher level directory
NameDateSize
build.gradle22-Oct-20208.1K
README.md22-Oct-20204.1K
src/22-Oct-2020

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 
      7 The *OpenCensus Agent for Java* collects and sends latency data about your Java process to
      8 OpenCensus backends such as Zipkin, Stackdriver Trace, etc. for analysis and visualization.
      9 
     10 
     11 ## Features
     12 
     13 The *OpenCensus Agent for Java* is in an early development stage. The following features are
     14 currently implemented:
     15 
     16 TODO(stschmidt): Update README.md along with implementation.
     17 
     18 
     19 ### Automatic context propagation for Executors
     20 
     21 The 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 is automatically propagated to the submitted Runnable.
     23 
     24 
     25 ### Automatic context propagation for Threads
     26 
     27 The context of the caller of [Thread#start](https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#start--)
     28 is automatically propagated to the new thread.
     29 
     30 
     31 ### Preliminary support for tracing
     32 
     33 As 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
     35 trace span.
     36 
     37 
     38 ## Design Ideas
     39 
     40 We see tracing as a cross-cutting concern which the *OpenCensus Agent for Java* weaves into
     41 existing Java bytecode (the application and its libraries) at runtime, typically when first loading
     42 the concerned bytecode.
     43 
     44 This approach allows us to instrument arbitrary code without having to touch the source code of the
     45 application or its dependencies. Furthermore, we don't require the application owner to upgrade any
     46 of 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-))
     48 stays as-is across the supported versions, the Java agent's bytecode weaver will be able to
     49 instrument the code.
     50 
     51 The *OpenCensus Agent for Java* uses [Byte Buddy](http://bytebuddy.net/), a widely used and
     52 well-maintained bytecode manipulation library, for instrumenting selected Java methods at class
     53 load-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 
     59 Download the latest version of the *OpenCensus Agent for Java* `.jar` file
     60 from [Maven Central][maven-url]. Store it somewhere on disk.
     61 
     62 To 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`
     64 executable as shown in the following example. Replace `X.Y.Z` with the actual version number.
     65 
     66 ```shell
     67 java -javaagent:path/to/opencensus-contrib-agent-X.Y.Z.jar ...
     68 ```
     69 
     70 
     71 ## Configuration
     72 
     73 The *OpenCensus Agent for Java* uses [Typesafe's configuration
     74 library](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
     76 defaults.
     77 
     78 You can override the default configuration in [different
     79 ways](https://github.com/lightbend/config/blob/7cae92d3ae3ff9d06f1db43800232d2f73c6fe44/README.md#standard-behavior).
     80 For example, to disable the automatic context propagation for Executors, add a system property as
     81 follows:
     82 
     83 ```shell
     84 java -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