Hypertrace OpenTelemetry Java agent

Hypertrace distribution of OpenTelemetry Java agent.

This agent supports these frameworks and adds following capabilities:

• capture request and response headers
• capture request and response bodies
• server request headers/bodies evaluation in agent filter that can result in request blocking. The filter implementation will be pluggable.

List of supported frameworks with additional capabilities:

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	3.0+
Spark Web Framework	2.3+
Spring Webflux	5.0+
Vert.x	3.0+ (4 not supported yet)
Struts	2.3+

Adding custom filter implementation

Custom filter implementations can be added via FilterProvider SPI (Java service loader). The providers can be disabled at startup via ht.filter.provider.<provider-class-name>.disabled=true.

Build

make init-submodules build

The final artifact is in javaagent/build/libs/hypertrace-agent-<version>-all.jar

Run & Configure

Download the latest version.

HT_REPORTING_ENDPOINT=http://localhost:5442 java -javaagent:javaagent/build/libs/hypertrace-agent-<version>-all.jar -jar app.jar

If TPA is configured with TLS server

HT_REPORTING_ENDPOINT=https://localhost:5443 java -javaagent:javaagent/build/libs/hypertrace-agent-<version>-all.jar -jar app.jar

By default the agent uses Otlp exporter.

The configuration precedence order

1. OpenTelemetry Agent's trace config file OTEL_TRACE_CONFIG/otel.trace.config
2. OpenTelemetry system properties and env variables
3. Hypertrace configuration with the following precedence order:
   1. system properties
   2. environment variables, TODO add link to agent-config repo
   3. configuration file, specified HT_CONFIG_FILE=example-config.yaml

Disable instrumentation at startup

Instrumentations can be disabled by -Dotel.instrumentation.<instrumentation-name>.enabled=false.

The following instrumentation names disable only Hypertrace instrumentations, not core OpenTelemetry:

• ht - all Hypertrace instrumentations
• servlet-ht - Servlet, Spark Web
• okhttp-ht - Okhttp
• grpc-ht - gRPC

The Hypertrace instrumentations use also the core OpenTelemetry instrumentation names so for example -Dotel.instrumentation.servlet.enabled=false disables all servlet instrumentations including core OpenTelemetry and Hypertrace.

Test

Tests use docker via Testcontainers.org.

When running tests from IDE set SMOKETEST_JAVAAGENT_PATH env variable.

make test

Further Reference

Read more in our 'Introducing Hypertrace Java Agent' blog post.