Java

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 and the request and response body. Traceable’s Java agent uses an OTLP exporter.

Before you begin

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

Note

Traceable also supports any framework that uses one of the supported frameworks as an underlying framework.

Setup

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

• Download using curl and attach using the command line

• Download from Maven central and attach using Gradle

• Download from Maven central and attach using Maven

Download using curl

Download and untar the Java agent by entering the following command:

curl -OL https://downloads.traceable.ai/agent/java/latest/javaagent-latest.tgz
tar -xzf javaagent-latest.tgz

 Run your application JAR with the traceable-agent from the command line:

export HT_CONFIG_FILE=/<path_to_config_file>/example-config.yaml; java -javaagent:/<path_to_java_agent>/javaagent.jar -jar app.jar

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 javaagent

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.

   ActionScript

   plugins {
       id 'application'
   }
   
   repositories {
       mavenCentral()
   }
   
   configurations {
       traceableAgent.extendsFrom runtimeOnly
   }
   
   dependencies {
       traceableAgent("ai.traceable.agent:javaagent:$traceableVersion")
   }
   
   application {
       // Define the main class for the application.
       mainClassName = 'com.example.Main'
   }
   
   run {
       jvmArgs = [
               "-javaagent:${configurations.traceableAgent.asPath}"
       ]
   }

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 project’s build directory

2. Add an <argument> to the Exec Maven Plugin configuration to set the -javaagent flag

3. mvn compile exec:execwill now run your application with the Traceable Java agent attached

   ActionScript

   <build>
       <plugins>
         <plugin>
           <artifactId>maven-dependency-plugin</artifactId>
           <version>3.1.2</version>
           <executions>
             <execution>
               <phase>compile</phase>
               <goals>
                 <goal>copy</goal>
               </goals>
               <configuration>
                 <artifactItems>
                   <artifactItem>
                     <groupId>ai.traceable</groupId>
                     <artifactId>javaagent</artifactId>
                     <version>${traceable.version}</version>
                     <classifier>all</classifier>
                   </artifactItem>
                 </artifactItems>
                 <outputDirectory>${project.build.directory}</outputDirectory>
               </configuration>
             </execution>
           </executions>
         </plugin>
   
         <plugin>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>exec-maven-plugin</artifactId>
           <version>3.0.0</version>
           <configuration>
             <executable>java</executable>
             <arguments>
               <argument>-javaagent:${project.build.directory}/javaagent-${hypertrace.version}-all.jar</argument>
               <argument>-classpath</argument>
               <classpath/>
               // Define the main class for the application
               <mainClass>com.example.Main</mainClass>
             </arguments>
           </configuration>
         </plugin>
       </plugins>
     </build>

Configure

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

• Method 1 – Configure a YAML file – Configure a YAML file with all the configurations 

• Method 2 – Provide configuration values as an environment variable – Provide the configuration as environment variables. This option overrides the configurations defined in the YAML file.

• Method 3 – Provide configuration values as Java system properties – Use Java’s-Dproperty=value method to set the configuration. This overrides the configurations set using the environment variables.

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 command output on the console. Run the above command separately for each Java application you want to use with Traceable’s Java agent. The following is a sample YAML file. For more configuration options, see Configuration variables.

service_name: java-service
propagationFormats:
  - TRACECONTEXT
reporting:
  trace_reporter_type: OTLP
  endpoint: http://<tpa_host>:4317
blocking_config:
  enabled: true
  modsecurity:
    enabled: true
  region_blocking:
    enabled: true
  evaluate_body: true
remote_config:
  enabled: true
  endpoint: <tpa_host>:5441
  poll_period_seconds: 20
api_discovery:
  enabled: true
sampling:
  enabled: true

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:

HT_CONFIG_FILE=/<path_to_config_file>/example-config.yaml java -javaagent:/<path_to_java_agent>/javaagent-1.1.2 -jar app.jar

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 JJava command. When you provide configuration through an environment variable, it overwrites the configuration values set using Method 1. The following is an example of providing the configuration as an environment variable. For more environment variables, see Configuration variables.

export HT_SERVICE_NAME=my_service_name HT_CONFIG_FILE=/<path_to_config_file>/example-config.yaml java -javaagent:/<path_to_java_agent>/javaagent.jar -jar app.jar

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. For more system properties, see Configuration variables.

java -Dht.service.name=my_service_name -javaagent:/<path_to_java_agent>/javaagent-1.1.2.jar -jar app.jar

Configuration variables

The following table lists all the available variables:

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.

Disable instrumentation

You can turn off instrumentation by running the following command:

java -Dotel.instrumentation.<instrumentation-name>.enabled=false -javaagent:/<path_to_java_agent>javaagent.jar -jar app.jar

 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 instrumentation also uses the core OpenTelemetry instrumentation names. For example, -Dotel.instrumentation.servlet.enabled=false disables all the servlet instrumentation, including core OpenTelemetry and Hypertrace.

Uninstall Java agent

To uninstall Traceable’s Java agent, restart your application without the javaagent argument or any of Traceable’s system properties.