Java installation instructions

Use the installation instructions below if you're installing Helios in a standard Java service.

Get your Java services auto-instrumented with Helios by following the installation instructions provided below.

Automatic instrumentation with Java uses a Java agent JAR that can be attached to any Java 8+ application.

Installing Helios in your Java microservice

Download the Helios Java SDK opentelemetry-javaagent.jar. The JAR file contains the agent and all automatic instrumentation packages.

Then, place the JAR in your preferred directory.

Configuring Helios through environment variables

The agent is highly configurable. One option is to pass configuration properties via environment variables:

HS_SERVICE_NAME="<SERVICE_NAME>" \ # TODO: Replace value with service name.
HS_TOKEN="<API_TOKEN>" \ # TODO: Replace value with API token from Helios.
HS_ENVIRONMENT=<ENVIRONMENT_NAME> \ # TODO: Replace with service environment.
JAVA_TOOL_OPTIONS=-javaagent:<path/to/helios-opentelemetry-javaagent.jar>

The above is running the application with the java agent using env var, another option to run the agent can be with a runtime property:

java -javaagent:<path/to/opentelemetry-javaagent.jar> -jar myapp.jar

You can also add the jar to your docker file and then run it with the above javaagent command:

ADD https://github.com/helios/opentelemetry-java-instrumentation/releases/download/v<LATEST_VERSION>/opentelemetry-javaagent.jar ./

CMD ["java", "-javaagent:opentelemetry-javaagent.jar", "-jar", "YOUR_APPLICATION_JAR_LOCATION"]

Configuring Helios in Quarkus applications

To export OpenTelemetry data from your Quarkus application, simply define the following properties in your application.properties file:

quarkus.opentelemetry.tracer.exporter.otlp.endpoint=https://grpccollector.gethelios.dev:4317
quarkus.opentelemetry.tracer.exporter.otlp.headers=Authorization=<API_TOKEN>

Deploying Helios in a Kubernetes cluster

It's possible to install and update the Helios OpenTelemetry SDK in a centralized manner when running multiple containers, via deployment with Kubernetes operator. Don't hesitate to reach out if you're interested in using this path.

๐Ÿ“˜

Java & OpenTelemetry

For more information about automatic and manual instrumentation with Java see the OpenTelemetry documentation.

To see the full range of configuration options, see Agent Configuration.

๐Ÿ‘

All set

After setup is complete and once the service is up and running, it will show up in the Helios application.

Troubleshooting tips

Installing the Helios OpenTelemetry SDK is usually a simple process; nonetheless, we've aggregated here some useful tips based on common issues we've encountered in the field so that you can complete the installation quickly.

Turn debug mode on

The Helios SDK support a debug mode through the environment variable HS_DEBUG.
Once debug mode is enabled, search for the Helios initialization prints. This will help verify (or refute) the successful installation of Helios in your microservice.

Dependencies

Automatic instrumentation uses Java agent so for the most basic use cases there is no need to install dependencies (either with Maven or Gradle).

Disabling specific Java instrumentations

Disabling specific instrumentations (e.g., Akka or Jedis) can be done by settings an environment variable: OTEL_INSTRUMENTATION_[NAME]_ENABLED to false. See the full list of instrumentations that can be disabled here: https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/#suppressing-specific-agent-instrumentation