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.