Search…
Java
Traceable's Java agent is based on OpenTelemetry. The topic provides information on multiple methods to install and configure the agent.
Traceable’s Java tracing agent or Java agent is based on OpenTelemetery and enhances the Spans within a Trace with security-focused attributes. Traceable’s agent can capture all the traffic that flows through your Java application including request and response headers along with the body of the request and response. You can either attach the Java agent to your application statically or dynamically.
Exporter - Traceable's Java agent uses Zipkin exporter.
The topic covers:

Prerequisites

The following prerequisites are required for installing Traceable's Java agent:
    The Java agent requires Java 8 or above.
    Traceable Platform Agent - Make sure that the Traceable platform agent's address is available to the applications being instrumented

Supported frameworks

Library/Framework
Versions
gRPC
1.6+
2.0+
Micronaut (basic support via Netty)
1.0+
Netty
4.0+
OkHttp
3.0+
Servlet
2.3+
5.0+
Vert.x
3.0+
Struts
2.3+

Setup

You can attach the Java agent using dynamic or static attach.

Dynamic attach

You can dynamically attach the Java agent to your application only if your Java application is running in a Kubernetes environment. Traceable’s Kubernetes sidecar installation installs the agent-attacher. For more information on sidecar installation, see Traceable in Kubernetes with sidecar.

Static attach

Complete the following steps to attach or load Traceable’s Java agent and do a static attach. In the static attach deployment method the Java application is started along with a Java agent. You can choose one of the following three methods to statically attach the Java agent:

Download using curl

Download and untar the Java agent by entering the following command:
1
curl -OL https://downloads.traceable.ai/agent/java/latest/javaagent-latest.tgz
2
tar -xzf javaagent-latest.tgz
Copied!
Run your application JAR with the traceable-agent from the command line:
1
export=HT_CONFIG_FILE=/<path_to_config_file>/example-config.yaml; java -javaagent:/<path_to_java_agent>/javaagent.jar -jar app.jar
Copied!

Download from Maven Central and attach using Gradle

If you want to attach the Traceable agent to the runtask of a Gradle project leveraging the Application Plugin, complete the following steps:
    1.
    Define a custom Gradle configuration for traceable-agent
    2.
    Declare the Traceable Java agent as a dependency using the custom configuration to download it from Maven Central
    3.
    Set the -javaagent flag as the first element of the jvmArgs list for the run task. Use the custom configuration you defined to dynamically retrieve the path of the Java agent JAR on your system.
    4.
    gradle run will now run your application with the Traceable Java agent attached.
1
plugins {
2
id 'application'
3
}
4
5
repositories {
6
mavenCentral()
7
}
8
9
configurations {
10
traceableAgent.extendsFrom runtimeOnly
11
}
12
13
dependencies {
14
traceableAgent("ai.traceable.agent:javaagent:$traceableVersion")
15
}
16
17
application {
18
// Define the main class for the application.
19
mainClassName = 'com.example.Main'
20
}
21
22
run {
23
jvmArgs = [
24
"-javaagent:${configurations.traceableAgent.asPath}"
25
]
26
}
Copied!

Download from Maven Central and attach using Maven

If you want to attach the Traceable agent to the exec task of a Maven project leveraging the Exec Maven Plugin, complete the following steps:
    1.
    Use the Maven Dependency Plugin to download the agent from Maven Central and copy it to your projects build directory
    2.
    Add an <argument> to the Exec Maven Plugin configuration to set the -javaagent flag
    3.
    mvn compile exec:exec will now run your application with the Traceable Java agent attached
1
<build>
2
<plugins>
3
<plugin>
4
<artifactId>maven-dependency-plugin</artifactId>
5
<version>3.1.2</version>
6
<executions>
7
<execution>
8
<phase>compile</phase>
9
<goals>
10
<goal>copy</goal>
11
</goals>
12
<configuration>
13
<artifactItems>
14
<artifactItem>
15
<groupId>ai.traceable.agent</groupId>
16
<artifactId>javaagent</artifactId>
17
<version>${traceable.version}</version>
18
<classifier>all</classifier>
19
</artifactItem>
20
</artifactItems>
21
<outputDirectory>${project.build.directory}</outputDirectory>
22
</configuration>
23
</execution>
24
</executions>
25
</plugin>
26
27
<plugin>
28
<groupId>org.codehaus.mojo</groupId>
29
<artifactId>exec-maven-plugin</artifactId>
30
<version>3.0.0</version>
31
<configuration>
32
<executable>java</executable>
33
<arguments>
34
<argument>-javaagent:${project.build.directory}/javaagent-${hypertrace.version}-all.jar</argument>
35
<argument>-classpath</argument>
36
<classpath/>
37
// Define the main class for the application
38
<mainClass>com.example.Main</mainClass>
39
</arguments>
40
</configuration>
41
</plugin>
42
</plugins>
43
</build>
Copied!

Configure

You can configure the Java agent using one of the following three methods:

Method 1 - Configure a YAML file

You can use the following sample YAML file, for example, example-config.yaml to configure Traceable’s Java agent. If you do not provide the configuration file, the Java agent takes the inbuilt default values which you can see in the output of the command on the console. Run the above command separately for each Java application that you want to instrument with Traceable’s Java agent.
1
serviceName: service_name
2
reporting:
3
endpoint: http://hostname:4317 # See https://docs.traceable.ai/install/traceable-agent
4
traceReporterType: ZIPKIN
5
opa:
6
endpoint: http://hostname:8181/ # See https://docs.traceable.ai/install/traceable-agent
7
pollPeriodSeconds: 30
Copied!
The following table explains the various configuration options.
Option
Description
serviceName
The name of the service that you want it to be identified with on Traceable’s dashboard.
propagationFormats
Defines the propagation format. Default is set as TRACECONTEXT. Options are TRACECONTEXT and B3
endpoint
Traceable agent's URL along with the port number.
    http://hostname:9411/api/v2/spans - Zipkin reporter
secure
Set it to true if you want to connect to the endpoint over TLS. The default value is true.
opa: endpoint
URL of Traceable agent where it is running on port number 8181.
pollPeriodSeconds
The time in seconds to poll the OPA service to fetch the blocking rules.
dataCapture:
    httpHeaders (request and response)
    httpBody (request and response)
    rpcMetadata (request and response)
    rpcBody (request and response)
    httpHeaders -Enable or disable capturing of request and response headers in HTTP
    httpBody - Enable or disable capturing of request and response body in HTTP
    rpcMetadata -Enable or disable capturing of request and response metadata in RPC
    rpcBody -Enable or disable capturing of request and response body in RPC
Other Tracing vendors are likely to use the TRACECONTEXT propagation format as well. If you already have an existing Tracing solution and would like to use Traceable along side it, then you must reconfigure Traceable to use the B3 propagation format. This will ensure Traceable is not competing for the Traceparent and will avoid broken correlations from service to service.

Load the Java agent

After you have completed the configuration file, run the following command to instrument your Java application with Traceable’s Java agent:
1
HT_CONFIG_FILE=/<path_to_config_file>/example-config.yaml java -javaagent:/<path_to_java_agent>/javaagent-1.0.1.jar -jar app.jar
Copied!

Method 2 - Provide configuration values as an environment variable

You can configure the Java agent by providing the configuration as an environment variable to the java command. When you provide configuration through an environment variable, it overwrites the configuration values set using Method 1. Following is an example of providing the configuration as an environment variable.
1
export HT_SERVICE_NAME=my_service_name HT_CONFIG_FILE=/<path_to_config_file>/example-config.yaml java -javaagent:/<path_to_java_agent>/hypertrace-agent-all.jar -jar app.jar
Copied!
Environment variable
Description
HT_SERVICE_NAME
Identifies the service or process on Traceable’s dashboard.
HT_REPORTING_ENDPOINT
The address of the Traceable agent where traces are reported, for example:
    http://hostname:9411/api/v2/spans - ZIPKIN reporter
The hostname is the host where the Traceable agent is deployed.
HT_REPORTING_SECURE
When true, connect to endpoints over TLS.
HT_REPORTING_OPA_ENDPOINT
The address of the Traceable agent with a reporting node 8181, for example, http://hostname:8181/. OPA endpoint is required to fetch Web application firewall configurations.
HT_REPORTING_OPA_POLL_PERIOD_SECONDS
The poll period in seconds to query the OPA service.
HT_REPORTING_TRACE_REPORTER_TYPE
This is an optional environmental variable.
HT_DATA_CAPTURE_HTTP_BODY_REQUEST
When set to true, capture the body of the HTTP request
HT_DATA_CAPTURE_HTTP_BODY_RESPONSE
When set to true, captures the body of the HTTP response
HT_DATA_CAPTURE_HTTP_HEADERS_REQUEST
When set to true, captures the header of the HTTP request
HT_DATA_CAPTURE_HTTP_HEADERS_RESPONSE
When set to true, captures the header of the HTTP response
HT_DATA_CAPTURE_RPC_METADATA_REQUEST
When set to true, captures the RPC metadata of the request
HT_DATA_CAPTURE_RPC_METADATA_RESPONSE
When set to true, captures the RPC metadata of the response
HT_DATA_CAPTURE_RPC_BODY_REQUEST
When set to true, captures the RPC body of the request
HT_DATA_CAPTURE_RPC_BODY_RESPONSE
When set to true, captures the RPC body of the response
Given Traceable is built on OpenTelemetry, you can also use the OTEL environment variables. Below is a small subset of what you can configure. The full list can be found here.

Method 3 - Provide configuration values as java system properties

You can also use Java’s -Dproperty=value method to set the configuration values. When you set the value using this method, it overwrites the values set using both Method 1 and 2. Following is an example of using Java’s -D flag:
1
java -Dht.service.name=my_service_name -javaagent:/<path_to_java_agent>/javaagent-1.0.1.jar -jar app.jar
Copied!

Verify deployment

To verify the deployment of the Java agent, log into your Traceable Dashboard and click on Services. If the deployment was successful, you will see your service listed under the Name column.

Java agent performance

    No boundless memory allocation.
    Trace processing and reporting happen on a background thread.
    Additional libraries are loaded into the application and can be found here.
    Typical CPU and JVM Heap usage is < 2%.

Additional Reading

Traceable is built upon the foundation of OpenTelemetry using our own open-sourced project HyperTrace.

Disabling instrumentation

You can disable instrumentation by running the following command:
1
java -Dotel.instrumentation.<instrumentation-name>.enabled=false -javaagent:/<path_to_java_agent>/hypertrace-agent-all.jar -jar app.jar
Copied!
The following instrumentation names disable only Hypertrace instrumentation, not the core OpenTelemetery:
    ht - All Hypertrace instrumentation
    servlet-ht - Servlet, Spark Web
    okhttp-ht - Okhttp
    grpc-ht - Okhttp
The Hypertrace instrumentations also use the core OpenTelemetry instrumentation names. For example -Dotel.instrumentation.servlet.enabled=false disables all the servlet instrumentations including core OpenTelemetry and Hypertrace.
Last modified 1mo ago