Java tracing and performance monitoring

LogSense agent is leveraging the https://opentracing.io/ initiative for creating a vendor-neutral APIs and instrumentation for distributed tracing. The source code is available at logsense-opentracing-agent GitHub repository and it is based on a LogSense-dedicated tracer, OpenTracing Java specialagent and a set of related libraries. This allows to use several instrumentations that allow to track:


  • Java Web Servlet API


  • Concurrent API

  • OkHttp3

  • ElasticSearch

  • RxJava2

  • Kafka

  • Cassandra

  • Apache Camel

  • Mongo

  • Hazelcast

  • and many more

It is also to possible to use OpenTracing API and add custom tracing in code. Due to the vendor-neutral property of OpenTracing, it’s easy to plug many Tracer outputs.

Step 1: Download the agent JAR

Download the logsense-opentracing-agent-1.1.9.jar file that includes the agent with all its dependencies

Step 2: Include the agent and config when running JVM

The options for JVM need to be modified to include additional pieces of information, location of the JAR file with agent and name of the tracer:

-Dsa.tracer=logsense -javaagent:/path/to/logsense-opentracing-agent-1.1.9.jar

In many cases this can be done by amending JAVA_OPTIONS environment variable or editing the actual script running the application.

Step 3: Providing the LOGSENSE_TOKEN

The token is needed to authenticate the data by Logsense and it can be found in the User portal

There are several options how it can be provided to the app

  • Option 1: As Java property, e.g. by adding -Dlogsense.token=ENTER-TOKEN to JVM options

  • Option 2: As environment variable, by setting LOGSENSE_TOKEN=ENTER-TOKEN

  • Option 3: By providing it inside a properties file, which location is provided by Java property: -Dlogsense.config=/path/to/logsense.properties. The file needs to include logsense.token=ENTER-TOKEN

Step 4: (Optional) adding service name

It is possible to identify each instance with logsense.service.name parameter, which can be provided either as a Java property (-Dlogsense.service.name=…​) or as environment variable (LOGSENSE_SERVICE_NAME=…​).


Following are some examples how all of this can be put together

Using environment variable:

$ LOGSENSE_TOKEN=aaa-111-bbb-222-ccc java -Dsa.tracer=logsense -javaagent:logsense-opentracing-agent-1.1.9.jar -jar myapp.jar

Using Java property:

$ java -Dsa.tracer=logsense -javaagent:logsense-opentracing-agent-1.1.9.jar -Dlogsense.token=aaa-111-bbb-222-ccc -jar myapp.jar

Using config file:

$ cat logsense.properties

$ java -Dsa.tracer=logsense -javaagent:logsense-opentracing-agent-1.1.9.jar -Dlogsense.config=logsense.properties -jar myapp.jar

Additional steps for WebLogic and WebSphere

In case of some application servers, Java 2 security options need to be updated:


Edit WEBLOGIC_HOME/wlserver/server/lib/weblogic.policy and add following entry:

grant codeBase "file:/path/to/logsense-opentracing-agent-1.1.9.jar" {
    permission java.security.AllPermission;


Edit WEBSPHERE_HOME/java/jre/lib/security/java.policy and add following entry:

grant codeBase "file:/path/to/logsense-opentracing-agent-1.1.9.jar" {
    permission java.security.AllPermission;
    permission java.net.SocketPermission "logs.logsense.com", "connect,accept,resolve";