- 12 Jun 2024
- 8 Minutes to read
- Print
- PDF
Java
- Updated on 12 Jun 2024
- 8 Minutes to read
- Print
- PDF
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
Library/Framework | Versions |
4.1+ | |
4.0+ | |
1.6+ | |
2.0+ | |
Micronaut (basic support via Netty) | 1.0+ |
4.0+ | |
3.0+ | |
2.3, 3.0, 5.0 | |
2.3+ | |
5.0+ | |
3.0+ | |
2.3+ | |
1.4+ |
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
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:
Define a custom Gradle configuration for
javaagent
Declare the Traceable Java agent as a dependency using the custom configuration to download it from Maven Central
Set the -
javaagent
flag as the first element of thejvmArgs
list for therun
task. Use the custom configuration you defined to dynamically retrieve the path of the Java agent JAR on your system.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:
Use the Maven Dependency Plugin to download the agent from Maven Central and copy it to your project’s build directory
Add an
<argument>
to the Exec Maven Plugin configuration to set the -javaagent
flagmvn compile exec:exec
will now run your application with the Traceable Java agent attachedActionScript
<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:
Config file option | Environment variable | Java system property | Default value | Description |
---|---|---|---|---|
|
|
|
| The name of the service with which you wish to identify the service in the Traceable dashboard. |
|
|
|
| Defines the propagation format. The default is |
|
|
|
| When set to |
|
|
|
| URL of Traceable Platform Agent where the spans should be exported to. |
|
|
|
| Trace Reporter type to be used for exporting spans. Accepted values are: |
|
|
| ““ | The certificate file path used while setting up Traceable Agent for HTTPS communication with Traceable Platform Agent. |
|
|
|
| Turn on or off capturing of request headers in HTTP. |
|
|
|
| Turn on or off capturing of response headers in HTTP. |
|
|
|
| Turn on or off capturing of the request body in HTTP. |
|
|
|
| Turn on or off capturing of response body in HTTP. |
|
|
|
| Turn on or off capturing of request metadata in RPC. |
|
|
|
| Turn on or off capturing of response metadata in RPC. |
|
|
|
| Turn on or off capturing of the request body in RPC. |
|
|
|
| Turn on or off capturing of response body in RPC. |
|
|
|
| Enable fetching of remote configurations from Traceable agent. Remote configurations consist of blocking, sampling, and API naming configurations. |
|
|
|
| URL of Traceable Platform agent where the Remote config should be fetched from. |
|
|
| 30 | The time in seconds to poll the remote config service to fetch the latest rules. |
|
|
| ““ | The certificate file path used while setting up Traceable Agent for HTTPS communication with Traceable Platform Agent. |
|
|
|
| The size limit in bytes for the response from Traceable Platform Agent. |
|
|
|
| You can use this flag to fetch certificates from the default truststore of the operating system instead of providing the file above. |
|
|
|
| Enable blocking with the Tracing Agent. |
|
|
|
| Process request and response bodies for matching the blocking criteria. |
|
|
|
| Skip requests coming from internal (private) IP addresses. |
|
|
| 20 | The maximum level of recursions allowed while processing a nested rule. |
|
|
|
| Enable data evaluation by ModSecurity engine. |
|
|
|
| Enable region-based blocking. |
|
|
|
| Enable agent-side sampling. |
|
|
|
| Enable agent-side API discovery. |
|
|
|
| Use certificates provided in the Java Trust Store to authenticate HTTPS connections to the Traceable Platform agent. If the certificates are added to a custom trust store, make sure that the Java application points to this Java truststore,
|
|
|
| 403 | Response error code when a request is blocked. You can configure a value that you wish.
|
|
|
| Access Forbidden | Defines the response message when a request is blocked. |
|
|
|
| Defines the mode to specify where to log. The values can be:
|
|
|
|
| Defines the logging level. The values can be:
|
|
|
| 3 | Defines the maximum number used for logging. Each size will have a maximum size specified by value in |
|
|
| 10485760 bytes | Defines the maximum size of the log files in bytes. |
|
|
|
| Defines the path where the log file would be created. |
|
|
|
| Using this variable, you can enable global metrics. |
|
|
|
| Using this variable, you can enable logging for global metrics. |
|
|
| 1m | Defines the frequency for logging global metrics, for example, 60m, 3600s, 1h, etc. |
|
|
|
| Using this variable, you can enable endpoint-specific metrics. |
|
|
| 100 | Configure the maximum number of endpoints you wish to track for endpoint metrics. |
|
|
|
| Using this variable, you can enable or disable logging for specific endpoints. |
|
|
| 30m | Defines the frequency for logging endpoint-specific metrics, for example, 30m, 3600s, 1h, etc. |
Note for TRACECONTEXT
Other Tracing vendors are likely to use the TRACECONTEXT propagation format as well. If you already have an existing tracing solution and want to use Traceable alongside it, 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.
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 instrumentationservlet-ht
– Servlet, Spark Webokhttp-ht
- Okhttpgrpc-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.