otel-instrument

#!/bin/bash

set -ef -o pipefail

# Copyright The OpenTelemetry Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

: <<'END_DOCUMENTATION'
`otel-instrument`

This script configures and sets up OpenTelemetry Python with the values we
expect will be used by the common user. It does this by setting the environment
variables OpenTelemetry uses, and then initializing OpenTelemetry using the
`opentelemetry-instrument` auto instrumentation script from the
`opentelemetry-instrumentation` package.

Additionally, this configuration assumes the user is using packages conforming
to the `opentelemetry-instrumentation` and `opentelemetry-sdk` specifications.

DO NOT use this script for anything else besides SETTING ENVIRONMENT VARIABLES.

See more:
https://docs.aws.amazon.com/lambda/latest/dg/runtimes-modify.html#runtime-wrapper

Usage
-----
We expect this file to be at the root of a Lambda Layer. Having it anywhere else
seems to mean AWS Lambda cannot find it.

In the configuration of an AWS Lambda function with this file at the
root level of a Lambda Layer:

.. code::

    AWS_LAMBDA_EXEC_WRAPPER = /opt/otel-instrument

END_DOCUMENTATION

# Use constants to access the environment variables we want to use in this
# script.

# See more:
# https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime

# - Reserved environment variables

# - - $AWS_LAMBDA_FUNCTION_NAME
# - - $LAMBDA_RUNTIME_DIR

# - Unreserved environment variables

# - - $PYTHONPATH

# Update the python paths for packages with `sys.path` and `PYTHONPATH`

# - We know that the path to the Lambda Layer OpenTelemetry Python packages are
#   well defined, so we can add them to the PYTHONPATH.
#
#   See more:
#   https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html#configuration-layers-path

export LAMBDA_LAYER_PKGS_DIR="/opt/python";

# - Set Lambda Layer python packages in PYTHONPATH so `opentelemetry-instrument`
#   script can find them (it needs to find `opentelemetry` to find the auto
#   instrumentation `run()` method later)

export PYTHONPATH="$LAMBDA_LAYER_PKGS_DIR:$PYTHONPATH";

# - Set Lambda runtime python packages in PYTHONPATH so
#   `opentelemetry-instrument` script can find them during auto instrumentation
#   and instrument them.

export PYTHONPATH="$LAMBDA_RUNTIME_DIR:$PYTHONPATH";

# Configure OpenTelemetry Python with environment variables

# - We leave `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to its default. This is
#   `http://localhost:4318/v1/traces` because we are using the HTTP exporter

# - If OTEL_EXPORTER_OTLP_PROTOCOL is not set by user, the default exporting protocol is http/protobuf.
if [ -z "${OTEL_EXPORTER_OTLP_PROTOCOL}" ]; then
    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
fi

# - Set the service name

if [ -z "${OTEL_SERVICE_NAME}" ]; then
    export OTEL_SERVICE_NAME=$AWS_LAMBDA_FUNCTION_NAME;
fi

# - Set the propagators

if [[ -z "$OTEL_PROPAGATORS" ]]; then
  export OTEL_PROPAGATORS="tracecontext,baggage,xray"
fi

# - Set the Resource Detectors (Resource Attributes)
#
#   TODO: waiting on OTel Python support for configuring Resource Detectors from
#   an environment variable. Replace the bottom code with the following when
#   this is possible. We will have to download `opentelemetry-sdk-extension-aws`
#   when that happens to get the resource detector.
#
#   export OTEL_RESOURCE_DETECTORS="aws_lambda";
#
#   In the meantime, if doing manual instrumentation, (which means we CANNOT use
#   this script) we could do the following:
#
#   import opentelemetry.trace as trace
#   from opentelemetry.sdk.trace import TracerProvider
#   from opentelemetry.sdk.extension.aws.resource._lambda import (
#       AwsLambdaResourceDetector,
#   )
#   from opentelemetry.sdk.resources import get_aggregated_resources
#   trace.set_tracer_provider(
#       TracerProvider(
#           resource=get_aggregated_resources(
#               [
#                   AwsLambdaResourceDetector(),
#               ]
#           ),
#       )
#   )

export LAMBDA_RESOURCE_ATTRIBUTES="cloud.region=$AWS_REGION,cloud.provider=aws,faas.name=$AWS_LAMBDA_FUNCTION_NAME,faas.version=$AWS_LAMBDA_FUNCTION_VERSION,faas.instance=$AWS_LAMBDA_LOG_STREAM_NAME";

if [ -z "${OTEL_RESOURCE_ATTRIBUTES}" ]; then
    export OTEL_RESOURCE_ATTRIBUTES=$LAMBDA_RESOURCE_ATTRIBUTES;
else
    export OTEL_RESOURCE_ATTRIBUTES="$LAMBDA_RESOURCE_ATTRIBUTES,$OTEL_RESOURCE_ATTRIBUTES";
fi


# - Uses the default `OTEL_PROPAGATORS` which is set to `tracecontext,baggage`

# - Use a wrapper because AWS Lambda's `python3 /var/runtime/bootstrap.py` will
#   use `imp.load_module` to load the function from the `_HANDLER` environment
#   variable. This RELOADS the module and REMOVES any instrumentation patching
#   done earlier. So we delay instrumentation until `bootstrap.py` imports
#   `otel_wrapper.py` at which we know the patching will be picked up.
#
#   See more:
#   https://docs.python.org/3/library/imp.html#imp.load_module

export ORIG_HANDLER=$_HANDLER;
export _HANDLER="otel_wrapper.lambda_handler";

# - Call the upstream auto instrumentation script

exec python3 $LAMBDA_LAYER_PKGS_DIR/bin/opentelemetry-instrument "$@"