Java
  • 12 Jun 2024
  • 8 Minutes to read
  • PDF

Java

  • PDF

Article summary

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

Apache HttpAsyncClient

4.1+

Apache HttpClient

4.0+

gRPC

1.6+

JAX-RS Client

2.0+

Micronaut (basic support via Netty)

1.0+

Netty

4.0+

OkHttp

3.0+

Servlet

2.3, 3.0, 5.0

Spark Web Framework

2.3+

Spring Webflux

5.0+

Vert.x

3.0+

Struts

2.3+

Undertow

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:

  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

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

service_name

HT_SERVICE_NAME

ht.service.name

-

The name of the service with which you wish to identify the service in the Traceable dashboard.

propagation_formats

HT_PROPAGATION_FORMATS

ht.propagation.formats

TRACECONTEXT

Defines the propagation format. The default is TRACECONTEXT. The options are TRACECONTEXT and B3.

reporting.secure

HT_REPORTING_SOURCE

ht.reporting.secure

false

When set to true a secure connection is established to send spans to the Traceable Platform Agent.

reporting.endpoint

HT_REPORTING_ENDPOINT

ht.reporting.endpoint

http://localhost:4317

URL of Traceable Platform Agent where the spans should be exported to.
http://traceable-agent:4317

reporting.trace_reporter_type

HT_REPORTING_TRACE_REPORTER_TYPE

ht.reporting.trace.reporter.type

OTLP

Trace Reporter type to be used for exporting spans.

Accepted values are: OTLP and ZIPKIN

reporting.cert_file

HT_REPORTING_CERT_FILE

ht.reporting.cert.file

““

The certificate file path used while setting up Traceable Agent for HTTPS communication with Traceable Platform Agent.

data_capture.http_headers.request

HT_DATA_CAPTURE_HTTP_HEADERS_REQUEST

ht.data.capture.http.headers.request

true

Turn on or off capturing of request headers in HTTP.

data_capture.http_headers.response

HT_DATA_CAPTURE_HTTP_HEADERS_RESPONSE

ht.data.capture.http.headers.response

true

Turn on or off capturing of response headers in HTTP.

data_capture.http_body.request

HT_DATA_CAPTURE_HTTP_BODY_REQUEST

ht.data.capture.http.body.request

true

Turn on or off capturing of the request body in HTTP.

data_capture.http_body.response

HT_DATA_CAPTURE_HTTP_BODY_RESPONSE

ht.data.capture.http.body.response

true

Turn on or off capturing of response body in HTTP.

data_capture.rpc_metadata.request

HT_DATA_CAPTURE_RPC_METADATA_REQUEST

ht.data.capture.rpc.metadata.request

true

Turn on or off capturing of request metadata in RPC.

data_capture.rpc_metadata.response

HT_DATA_CAPTURE_RPC_METADATA_RESPONSE

ht.data.capture.rpc.metadata.response

true

Turn on or off capturing of response metadata in RPC.

data_capture.rpc_body.request

HT_DATA_CAPTURE_RPC_BODY_REQUEST

ht.data.capture.rpc.body.request

true

Turn on or off capturing of the request body in RPC.

data_capture.rpc_body.response

HT_DATA_CAPTURE_RPC_BODY_RESPONSE

ht.data.capture.rpc.body.response

true

Turn on or off capturing of response body in RPC.

remote.enabled

TA_REMOTE_CONFIG_ENABLED

ta.remote.config.enabled

true

Enable fetching of remote configurations from Traceable agent. Remote configurations consist of blocking, sampling, and API naming configurations.

remote.endpoint

TA_REMOTE_CONFIG_ENDPOINT

ta.remote.config.endpoint

true

URL of Traceable Platform agent where the Remote config should be fetched from.
traceable-agent:5441

remote.poll_period_seconds

TA_REMOTE_CONFIG_POLL_PERIOD_SECONDS

ta.remote.config.poll.period.seconds

30

The time in seconds to poll the remote config service to fetch the latest rules.

remote.cert_file

TA_REMOTE_CONFIG_CERT_FILE

ta.remote.config.cert_file

““

The certificate file path used while setting up Traceable Agent for HTTPS communication with Traceable Platform Agent.

remote.grpc_max_call_recv_msg_size

TA_REMOTE_CONFIG_ENABLED

ta.remote.config.grpc.max.call.recv.msg.size

32 * 1024 * 1024

The size limit in bytes for the response from Traceable Platform Agent.

remote.use_secure_connection

TA_REMOTE_CONFIG_USE_SECURE_CONNECTION

ta.remote.config.use_secure_connection

false

You can use this flag to fetch certificates from the default truststore of the operating system instead of providing the file above.

blocking.enabled

TA_BLOCKING_CONFIG_ENABLED

ta.blocking.config.enabled

true

Enable blocking with the Tracing Agent.

blocking.evaluate_body

TA_BLOCKING_CONFIG_EVALUATE_BODY

ta.blocking.config.evalutate_body

true

Process request and response bodies for matching the blocking criteria.

blocking.skip_internal_request

TA_BLOCKING_CONFIG_SKIP_INTERNAL_REQUEST

ta.blocking.config.skip.internal.request

true

Skip requests coming from internal (private) IP addresses.

blocking.max_recursion_depth

TA_BLOCKING_CONFIG_MAX_RECURSION_DEPTH

ta.blocking.config.max.recursion.depth

20

The maximum level of recursions allowed while processing a nested rule.

blocking.modsecurity.enabled

TA_BLOCKING_CONFIG_MODSECURITY_ENABLED

ta.blocking.config.modsecurity.enabled

true

Enable data evaluation by ModSecurity engine.

blocking.region.enabled

TA_BLOCKING_CONFIG_REGION_ENABLED

ta.blocking.config.region.blocking.enabled

true

Enable region-based blocking.

sampling.enabled

TA_SAMPLING_ENABLED

ta.sampling.enabled

true

Enable agent-side sampling.

api_discovery.enabled

TA_API_DISCOVERY_ENABLED

ta.api.discovery.enabled

true

Enable agent-side API discovery.

javaagent.import_jks_certs

TA_JAVAAGENT_IMPORT_JKS_CERTS

ta.javaagent.import.jks.certs

false

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, -Djavax.net.ssl.trustStore= <path/to/truststore>

-javax.net.ssl.trustStorePassword=<truststore-password>

blocking.response_status_code

TA_BLOCKING_CONFIG_RESPONSE_STATUS_CODE

ta.blocking.config.response.status.code

403

Response error code when a request is blocked. You can configure a value that you wish.

Note

Make sure that the status code is between 400 and 499 including both the number.

blocking.response_message

TA_BLOCKING_CONFIG_RESPONSE_MESSAGE

ta.blocking.config.response.message

Access Forbidden

Defines the response message when a request is blocked.

logging.log_mode

TA_LOGGING_MODE

ta.logging.mode

LOG_MODE_STDOUT

Defines the mode to specify where to log. The values can be:

  • LOG_MODE_NONE

  • LOG_MODE_STDOUT

  • LOG_MODE_FILE

logging.log_level

TA_LOOGING_LEVEL

ta.logging.level

LOG_LEVEL_INFO

Defines the logging level. The values can be:

  • LOG_LEVEL_TRACE

  • LOG_LEVEL_DEBUG

  • LOG_LEVEL_INFO

  • LOG_LEVEL_WARN

  • LOG_LEVEL_ERROR

  • LOG_LEVEL_CRITICAL

logging.log_file.max_files

TA_LOGGING_LOG_FILE_MAX_FILES

ta.logging.log.file.max.files

3

Defines the maximum number used for logging. Each size will have a maximum size specified by value in logging.log_file.max_file_size configuration.

logging.log_file.max_file_size

TA_LOGGING_LOG_FILE_MAX_FILE_SIZE

ta.logging.log.file.max.file.size

10485760 bytes

Defines the maximum size of the log files in bytes.

logging.log_file.file_path

TA_LOGGING_LOG_FILE_FILE_PATH

ta.logging.log.file.file.path

/var/traceable/log/libtraceable-javaagent.log

Defines the path where the log file would be created.

metrics_config.enabled

TA_METRICS_ENABLED

ta.metrics.enabled

false

Using this variable, you can enable global metrics.

metrics_config.logging.enabled

TA_METRICS_LOGGING_ENABLED

ta.metrics.logging.enabled

false

Using this variable, you can enable logging for global metrics.

metrics_config.logging.frequency

TA_METRICS_LOGGING_FREQUENCY

ta.metrics.logging.frequency

1m

Defines the frequency for logging global metrics, for example, 60m, 3600s, 1h, etc.

metrics_config.endpoint_config.enabled

TA_METRICS_ENDPOINT_ENABLED

ta.metrics.endpoint.enabled

false

Using this variable, you can enable endpoint-specific metrics.

metrics_config.endpoint_config.max_endpoints

TA_METRICS_ENDPOINT_MAX_ENDPOINTS

ta.metrics.endpoint.max.endpoints

100

Configure the maximum number of endpoints you wish to track for endpoint metrics.

metrics_config.endpoint_config.logging.enabled

TA_METRICS_ENDPOINT_LOGGING_ENABLED

ta.metrics.endpoint.logging.enabled

false

Using this variable, you can enable or disable logging for specific endpoints.

metrics_config.endpoint_config.logging.frequency

TA_METRICS_ENDPOINT_LOGGING_FREQUENCY

ta.metrics.endpoint.logging.frequency

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 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.


Was this article helpful?

What's Next