🗂 Environment variables use-cases

Running from terminal (UNIX)

When you manually run your app from a UNIX terminal, you can set the following types of variables:

Shell variables

Shell variables are defined as part of the execution command, and will be available only in the process for which they were defined.

For example, running a Python application while enabling Helios using shell variables will look like this:

AUTOWRAPT_BOOTSTRAP=helios HS_TOKEN=abc HS_SERVICE_NAME=my_service python my_app.py

This command sets 3 different variables (AUTOWRAPT_BOOTSTRAP, HS_TOKEN and HS_SERVICE_NAME) and runs the app.

Environment variables

Environment variables are defined prior to executing your application, and will be available for the process they were defined in, along with any other process spawn from it - i.e. your application.

For example, enabling Helios for a Node application using environment variables will look like this:

export NODE_OPTIONS="--require helios-opentelemetry-sdk"
export HS_TOKEN=abc
export HS_SERVICE_NAME=my_service

python my_app.py

These commands first set 3 different environment variables (NODE_OPTIONS, HS_TOKEN and HS_SERVICE_NAME) and the last command runs the app - in which these variables will be available.

Running with a Dockerfile

If your application is built and run from a Docker container, you can configure the necessary environment variables in your Dockerfile.

For example, enabling Helios for a Node application will look something like this:

FROM node:16.16.0-alpine

ENV NODE_OPTIONS="--require helios-opentelemetry-sdk"
ENV HS_TOKEN="<YOUR HELIOS TOKEN GOES HERE>"
ENV HS_SERVICE_NAME="my-node-service"
ENV HS_ENVIRONMENT="staging"

...

Dockerized Java application

If your Docker container runs a Java application, you'll need to copy to the container the Java agent JAR, define the required environment variables, and update your execution command:

FROM openjdk:8u332-jre

# Assuming the working directory includes your application's JAR "my-java-service.jar".
COPY opentelemetry-javaagent.jar ./
ENV OTEL_SERVICE_NAME="my-java-service"
ENV OTEL_EXPORTER_OTLP_HEADERS="Authorization=<YOUR HELIOS TOKEN GOES HERE>"
ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://collector.gethelios.dev/v1/traces"
ENV OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
ENV OTEL_RESOURCE_ATTRIBUTES="deployment.environment=staging"

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

Running with Docker Compose

If you use Docker Compose to build and run your application along with other applications, you can configure the environment variables in the docker-compose.yml file.

For example, enabling Helios for a service that's based on a Node application will look something like this:

services:
  my-node-service:
    image: my-node-image
    environment:
        NODE_OPTIONS: "--require helios-opentelemetry-sdk"
        HS_TOKEN: "<YOUR HELIOS TOKEN GOES HERE>"
        HS_SERVICE_NAME: "my-node-service"
        HS_ENVIRONMENT: "staging"

...

When you spin-up your Docker containers (docker compose up), these environment variables will be set and available for the Node application.

Running in Kubernetes

Of your application is being run inside a Kubernetes Pod, you can set environment variables for the containers that run in the Pod.

For example, enabling Helios for a Python application will look something like this:

apiVersion: v1
kind: Pod
metadata:
  name: my-python-service
spec:
  containers:
  - name: python-service-container
    image: python-service:latest
    env:
    - name: AUTOWRAPT_BOOTSTRAP
      value: helios
    - name: HS_TOKEN
      value: abc
    - name: HS_SERVICE_NAME
      value: my_service_in_kubernetes

When you spin-up your Kubernetes Pod, these environment variables will be set and available for the application.

Detailed installation Instructions

To learn more about initializing Helios and the required environment variables, see the detailed installation instructions.