Run your Container Images with Deepfactor

This article outlines the two different ways to run your application’s Docker containers with Deepfactor. If you are using Kubernetes to orchestrate and manage your Docker containers, please refer to this document.

Using the dfctl run Command

This method involves no changes to your container image. It is ideal for environments where a user prefers to keep the container image unchanged from QA/staging to production. Instead of using “docker run” to launch your container, you will use the “dfctl run” command. The advantage with this method is that you don’t need to modify your docker images to instrument them with Deepfactor.

Step 1: Download the Deepfactor docker volume initialization script.

curl https://repo.deepfactor.io/install-dfctl.sh | sh -

The above script installs the “deepfactor-runtime” package for your Linux distribution. If the package is already installed, the script will update the package to the latest version. If your machine is a docker host, then the script also creates a docker volume with the name “df-runtime” and copies over the Deepfactor runtime artifacts to this docker volume. If you clean the docker volumes on the host using the “docker volume prune” command, you will need to re-run this script to re-create the df-runtime docker volume before running any of your containers with Deepfactor.

Step 2: Set your auth token

export DF_RUN_TOKEN=<YOUR_DEEPFACTOR_TOKEN>

This token is needed to register your component and send telemetry to the Deepfactor Portal. You can get this token from the Deepfactor Portal UI. On the dashboard screen click on 'Run with Deepfactor' button on the right top.

Step 3: Run your docker container with Deepfactor

dfctl run -a "my application" -v --docker-run DOCKER_RUN_OPTIONS --image IMAGE:1.1
  • -a or --application (required) specify the name of your application

  • --docker-run (required) specify the full docker run command along with arguments you use to run your container. The docker run parameters must identify the container image with --image. Command arguments may follow after the image name.
  • -c or --component (optional) specify the name of your component. Defaults to APP_IMAGE without tag

  • --version (optional) specify the version of the component you are currently running. You can filter insights based on this version number from the UI. Defaults to APP_IMAGE tag

  • -p or --policy (optional) specify the alert policy for this component. This policy will be used to raise alerts for all active and future instances of this component.
  • --disable-stack-traces (optional) - This option is to disable stack traces. Stack traces are enabled by default.

  • --enable-method-tracing (optional) Deepfactor can enhance alerts by enabling language specific function or method tracing.  Click here to read how to enable them.
  • -l or --lang (deprecated) Deepfactor can enhance alerts by enabling language specific intercepts. This option is superseded by --disable-stack-traces and --enable-method-tracing.
  • -t or --tag (optional) specify comma separated key value pairs to tag this instance. You can filter such instances using tags. Example: -t "key1=value1,key2=value2"

  • -E or --env (optional) specify the environment in which you are running your component (Ex. staging, qa etc.). You can filter insights based on the environment you specify.

The above command mounts the df-runtime docker volume to the /opt/deepfactor directory in your container.

Note:

1. Please ensure you add --image before your image name.

2. Running docker image requires privileges. Hence you will have to run this command as a member of the docker group, as root or with sudo.  Use the -E option with sudo to preserve the environment variable DF_RUN_TOKEN for registration with the Deepfactor portal.

3. Applications could see a performance impact when run with Deepfactor since stack traces are enabled by default.

Adding Deepfactor to your container image

This method involves incorporating Deepfactor’s instrumentation library into the container image itself. This method is ideal for environments where a user wishes not to change his / her deployment command or install dfctl on the deployment machine. In this method, we take your docker image, add runtime support libraries (libdf.so) and create a new image. During deployment, you must use this newly created image with Deepfactor enabled instead of the original image. One advantage of this approach is that your deployment scripts/pipeline don’t need to change.


Step 1: Download Deepfactor Dockerfile

  1. Login to your Deepfactor Portal.
  2. Click on Run with Deepfactor.
  3. In the left sidebar, click on the Other Container Deployments option.
  4. Click the Download button to download the Docker file.

download_deepfactor_docker_file.png

This Dockerfile.df will run a multi-stage build to create a new image from your Docker image with runtime libraries included in /opt/Deepfactor.

Step 2: Build Docker Image With Deepfactor 

APP_IMAGE="my/image:tag";
docker build -t DF_INSTRUMENTED_IMAGE -f Dockerfile.df \
--build-arg "APP_IMAGE=${APP_IMAGE}" \
--build-arg "APP_IMAGE_ID=`docker inspect ${APP_IMAGE} --format '{{.Id}}'`" \
--build-arg "DF_APP_NAME=my application" .

In this step, we use the Dockerfile downloaded in Step 1 to create the new image with Deepfactor runtime included.

  • DF_INSTRUMENTED_IMAGE: name of the instrumented docker image. You have to deploy this image as part of your deployment pipeline.

run_deepfactor_instrumented_image.png

Step 3: Run the Deepfactor enabled Docker image

docker run DF_INSTRUMENTED_IMAGE

Use the same command as you would to run your original docker container, but use the Deepfactor enabled docker image we created in Step 2.

Where:

  • YOUR_IMAGE is the name of the docker image, generally of the form [registry][:port]/[image_path][:tag] you want to instrument with Deepfactor

  • DF_INSTRUMENTED_IMAGE is the name of the Deepfactor instrumented docker image

  • DF_APP_NAME (required) specify the name of your application

Options:

  • --build-arg "DF_COMPONENT=":(optional) This is the name of your component. Defaults to APP_IMAGE without tag
  • --build-arg "DF_COMPONENT_VERSION=":(optional) This is the version of your component. Defaults to APP_IMAGE tag
  • --build-arg "DF_APP_TAG=":(optional) specify comma separated key value pairs to tag instances of the current application or component build. You can filter such instances using tags. Example: -t "key1=value1,key2=value2"
  • --build-arg "DF_STACK_TRACES=disable": (optional) Stack traces are enabled by default. This option is to disable stack traces.
  • --build-arg "DF_METHOD_TRACING=enable" (optional) Deepfactor can enhance alerts by enabling language-specific function or method tracing.  Click here to read how to enable them.
  • --build-arg "DF_LSA=":(optional) Deepfactor can enhance alerts by enabling language-specific intercepts. This option is superseded by DF_STACK_TRACES and DF_METHOD_TRACING. Click Here to read how to enable them.
  • --build-arg "DF_ENV_NAME=":(optional) specify the environment in which you are running your component (Ex. staging, qa etc.). You can filter insights based on the environment you specify.
  • --build-arg "DF_IMAGE_ENTRYPOINT=`/opt/deepfactor/bin/df-get-entrypoint.sh $APP_IMAGE`":(optional) required if entrypoint libc does not match image OS distribution. This option will allow the build to attempt to automatically determine the libc of the image entrypoint. The df-get-entrypoint.sh script is provided with Deepfactor runtime image (public.ecr.aws/deepfactor/runtime:latest) or DF Installation Script.
  • --build-arg "DF_ENTRYPOINT_LIBC=":(optional) required if entrypoint libc does not match image OS distribution. Set to "glibc" or "musl". This option will override automatic libc detection performed when the DF_IMAGE_ENTRYPOINT option is used.
  • --build-arg "DF_ALERT_POLICY=":(optional) Please enter the name of the alert policy. If not set, the default policy will be used to generate alerts.

Note: Applications could see a performance impact when run with Deepfactor since stack traces are enabled by default.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.