Python installation instructions

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

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

Installing Helios in your Python microservice

Navigate to your project's root directory, and install the latest Helios OpenTelemetry SDK:

pip install helios-opentelemetry-sdk

Configuring Helios through environment variables

Define the following environment variables when running your service:

export AUTOWRAPT_BOOTSTRAP=helios # TODO: Variable should be set before process starts.
export HS_TOKEN=<API_TOKEN> # TODO: Replace value with API token from Helios.
export HS_SERVICE_NAME=<SERVICE_NAME> # TODO: Replace value with service name.
export HS_ENVIRONMENT="<ENVIRONMENT_NAME>" # TODO: Replace value with service environment.

Configuring Helios in the code

Alternatively, it is possible to configure Helios in the code itself.
In your project's __init__.py file, paste the following code snippet before all other imports:

from helios import initialize

initialize(
    api_token=<API_TOKEN>,        # TODO: Insert API token from Helios.
    service_name=<SERVICE_NAME>,  # TODO: Insert service name.
    enabled=True,                 # Defaults to False if omitted.
    environment=<ENVIRONMENT>,    # Defaults to os.environ.get('DEPLOYMENT_ENV') if omitted.
    commit_hash=<COMMIT_HASH>,    # Defaults to os.environ.get('COMMIT_HASH') if omitted.
)

Deploying Helios in an AWS Lambda function

To achieve complete observability & monitoring over AWS Lambda functions, install Helios using one of the mechanisms supported below.

Helios supports propagating the OTel context through various Lambda triggers, such as API Gateway, SQS, EventBridge, etc.

Configure automatically using Helios' AWS Lambda layer

  1. Get the latest version of Helios' auto-instrumentation Lambda layer.
    In Helios app go to the user menu on the top right corner and select Settings > General.
    Copy the Python AWS Lambda Layer (ARN).
  2. Add the ARN to your Lambda function.
  3. Make sure the following environment variables are configured:
AWS_LAMBDA_EXEC_WRAPPER=/opt/python/helios-instrument  
HS_TOKEN=<API_TOKEN> # TODO: Replace value with API token from Helios.
HS_ENVIRONMENT=<ENVIRONMENT_NAME> # TODO: Replace value with Lambda function environment.

Note: The service name is automatically populated with the function name.

Configure manually

In your Lambda handler main file, add the following:

from helios import initialize, instrument_lambda

initialize(
    api_token=<API_TOKEN>,        # TODO: Insert API token from Helios.
    enabled=True,                 # Defaults to False if omitted.
    environment=<ENVIRONMENT>,    # Defaults to os.environ.get('DEPLOYMENT_ENV') if omitted.
    commit_hash=<COMMIT_HASH>,    # Defaults to os.environ.get('COMMIT_HASH') if omitted.
)

@instrument_lambda
def lambda_handler(event, context):   
    # Your lambda implementation

Note: The service name is automatically populated with the function name.

Deploying Helios in a Kubernetes (K8s) 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.

See more configuration options here.

๐Ÿ‘

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.