fix(python): add otel-handler wrapper around otel-instrument (#1837)

* create `otel-handler` script

* add docs to mention `otel-handler` in `otel-instrument`

* include `otel-handler` in layer build

* update `sample-apps`

* update `Makefile` and unit tests

removing references to the old handler should be ok, because the new one should be a wrapper which just acts upon the old one

* update permissions and unit tests

unit tests actually required us to register both files so it worked as expected

Author: duncanista

python/sample-apps/aws-sdk/deploy/wrapper/main.tf

@@ -19,7 +19,7 @@ module "hello-lambda-function" {
   ])
 
   environment_variables = {
-    AWS_LAMBDA_EXEC_WRAPPER = "/opt/otel-instrument"
+    AWS_LAMBDA_EXEC_WRAPPER = "/opt/otel-handler"
   }
 
   tracing_mode = var.tracing_mode

python/sample-apps/template.yml

@@ -24,7 +24,7 @@ Resources:
         - AmazonS3FullAccess
       Environment:
         Variables:
-          AWS_LAMBDA_EXEC_WRAPPER: /opt/python/otel-instrument
+          AWS_LAMBDA_EXEC_WRAPPER: /opt/python/otel-handler
       Tracing: Active
       Layers:
         - !Ref OTelLayer

python/src/otel/Dockerfile

@@ -15,10 +15,12 @@ RUN mkdir -p /build && \
   rm -rf /build/tmp && \
   mv otel_sdk/otel_wrapper.py /build/python && \
   mv otel_sdk/otel-instrument /build && \
+  mv otel_sdk/otel-handler /build && \
   chmod 755 /build/otel-instrument && \
+  chmod 755 /build/otel-handler && \
   rm -rf /build/python/boto* && \
   rm -rf /build/python/urllib3* && \
   cd /build && \
-  zip -r opentelemetry-python-layer.zip otel-instrument python
+  zip -r opentelemetry-python-layer.zip otel-handler otel-instrument python
 
 CMD cp /build/opentelemetry-python-layer.zip /out/opentelemetry-python-layer.zip

python/src/otel/Makefile

@@ -9,5 +9,6 @@ build-OTelLayer:
 	rm -rf $(ARTIFACTS_DIR)/tmp
 	cp -r $(SDK)/* $(ARTIFACTS_DIR)/python
 	chmod 755 $(ARTIFACTS_DIR)/python/otel-instrument
+	chmod 755 $(ARTIFACTS_DIR)/python/otel-handler
 	rm -rf $(ARTIFACTS_DIR)/python/boto*
 	rm -rf $(ARTIFACTS_DIR)/python/urllib3*

python/src/otel/otel_sdk/otel-handler

@@ -0,0 +1,41 @@
+#!/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-handler`
+
+This script is a wrapper around the existing `otel-instrument` script to maintain
+backward compatibility while providing a more descriptive name.
+
+It simply forwards all arguments to the `otel-instrument` script.
+
+Usage
+-----
+Use this script exactly as you would use `otel-instrument`:
+
+.. code::
+
+    AWS_LAMBDA_EXEC_WRAPPER = /opt/otel-handler
+
+END_DOCUMENTATION
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Call the original otel-instrument script with all passed arguments
+exec "${SCRIPT_DIR}/otel-instrument" "$@"

python/src/otel/otel_sdk/otel-instrument

@@ -25,6 +25,10 @@ variables OpenTelemetry uses, and then initializing OpenTelemetry using the
 `opentelemetry-instrument` auto instrumentation script from the
 `opentelemetry-instrumentation` package.
 
+All other runtimes use the `otel-handler` script which is the equivalent of this.
+In the next major version, the contents of this script will be moved to the
+`otel-handler` script.
+
 Additionally, this configuration assumes the user is using packages conforming
 to the `opentelemetry-instrumentation` and `opentelemetry-sdk` specifications.
 

python/src/otel/tests/test_otel.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 """
-This file tests that the `otel-instrument` script included in this repository
+This file tests that the `otel-handler` script included in this repository
 successfully instruments OTel Python in a mock Lambda environment.
 """
 
@@ -94,7 +94,7 @@ def replace_in_file(filename, old_text, new_text):
 
 def mock_aws_lambda_exec_wrapper():
     """Mocks automatically instrumenting user Lambda function by pointing
-    `AWS_LAMBDA_EXEC_WRAPPER` to the `otel-instrument` script.
+    `AWS_LAMBDA_EXEC_WRAPPER` to the `otel-handler` script.
 
     TODO: It would be better if `moto`'s `mock_lambda` supported setting
     AWS_LAMBDA_EXEC_WRAPPER so we could make the call to Lambda instead.
@@ -107,7 +107,7 @@ def mock_aws_lambda_exec_wrapper():
     # with instrumentation. In this test we just make sure we can complete auto
     # instrumentation without error and the correct environment variabels are
     # set. A future improvement might have us run `opentelemetry-instrument` in
-    # this process to imitate `otel-instrument`, but our lambda handler does not
+    # this process to imitate `otel-handler`, but our lambda handler does not
     # call other instrumented libraries so we have no use for it for now.
 
     print_environ_program = (
@@ -118,7 +118,7 @@ def mock_aws_lambda_exec_wrapper():
 
     completed_subprocess = subprocess.run(
         [
-            os.path.join(INIT_OTEL_SCRIPTS_DIR, "otel-instrument"),
+            os.path.join(INIT_OTEL_SCRIPTS_DIR, "otel-handler"),
             "python3",
             "-c",
             print_environ_program,
@@ -128,7 +128,7 @@ def mock_aws_lambda_exec_wrapper():
         text=True,
     )
 
-    # NOTE: Because `otel-instrument` cannot affect this python environment, we
+    # NOTE: Because `otel-handler` cannot affect this python environment, we
     # parse the stdout produced by our test python program to update the
     # environment in this parent python process.
 
@@ -171,6 +171,11 @@ class TestAwsLambdaInstrumentor(TestBase):
     def setUpClass(cls):
         super().setUpClass()
         sys.path.append(INIT_OTEL_SCRIPTS_DIR)
+        replace_in_file(
+            os.path.join(INIT_OTEL_SCRIPTS_DIR, "otel-handler"),
+            'export LAMBDA_LAYER_PKGS_DIR="/opt/python"',
+            f'export LAMBDA_LAYER_PKGS_DIR="{TOX_PYTHON_DIRECTORY}"',
+        )
         replace_in_file(
             os.path.join(INIT_OTEL_SCRIPTS_DIR, "otel-instrument"),
             'export LAMBDA_LAYER_PKGS_DIR="/opt/python"',
@@ -198,6 +203,11 @@ def tearDown(self):
     def tearDownClass(cls):
         super().tearDownClass()
         sys.path.remove(INIT_OTEL_SCRIPTS_DIR)
+        replace_in_file(
+            os.path.join(INIT_OTEL_SCRIPTS_DIR, "otel-handler"),
+            f'export LAMBDA_LAYER_PKGS_DIR="{TOX_PYTHON_DIRECTORY}"',
+            'export LAMBDA_LAYER_PKGS_DIR="/opt/python"',
+        )
         replace_in_file(
             os.path.join(INIT_OTEL_SCRIPTS_DIR, "otel-instrument"),
             f'export LAMBDA_LAYER_PKGS_DIR="{TOX_PYTHON_DIRECTORY}"',