Java installation instructions

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

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"]

Take the latest Helios java jar version from here.

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.

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://collector.heliosphere.io/traces
quarkus.opentelemetry.tracer.exporter.otlp.headers=Authorization=<API_TOKEN>

πŸ‘

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


Did this page help you?