This article outlines the two different ways to run your application’s Docker containers with DeepFactor Observability enabled. 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 in any way to enable DeepFactor Observability.
Step 1: Download the DeepFactor docker volume initialization script.
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
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" -c "my component" --version "1.1.1" -v --docker-run DOCKER_RUN_OPTIONS --image IMAGE
-a or --application (required) specify the name of your application
-c or --component (required) specify the name of your component
- --docker-run (required) specify the full docker run command along with arguments you use to run your container. Please note this should be the last argument of dfctl run command. Also the docker run parameters must identify the container image with --image. e.g.
dfctl run -a app-name -c component-name -v "1.1" --docker-run -p 4000:4000 -v docker-vol:/opt/path --image image-repo:latest
--version (optional) specify the version of the component you are currently running. You can filter insights based on this version number from the UI
-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"
The above command mounts the df-runtime docker volume to the /opt/deepfactor directory in your container.
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 root or with sudo. Use the -E option with sudo to preserve the environment variable DF_RUN_TOKEN for registration with the DeepFactor portal.
Adding DeepFactor to your docker image
This method involves incorporating DeepFactor’s Observability 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 a file (libdf.so) and create a new image. During deployment, you must use this newly created image with DeepFactor enabled instead of the original image. The advantage of this approach is that your deployment scripts / pipeline don’t need to change.
Step 1: Download DeepFactor Dockerfile
This Dockerfile will run a multi stage build to create a new image from your Docker image with libdf.so included. Please note that you will need to identify the base image of your docker image (alpine or other linux distributions) and download the appropriate Dockerfile.
For docker images derived from Alpine (3.9 and above) base image, click on the following link to download the Dockerfile:
For docker images derived from one of these base images: Ubuntu (18.04, 20.04), Debian 10, CentOS (7, 8), Amazon Linux (1, 2), RedHat (7.X, 8.X), Linux Mint (18.X, 19.X and 20.X), click on the following link to download the Dockerfile:
Step 2: Build Docker Image With DeepFactor
docker build -t DF_INSTRUMENTED_IMAGE -f Dockerfile.df --build-arg "APP_IMAGE=YOUR_IMAGE" --build-arg "DF_APP_NAME=my application" --build-arg "DF_COMPONENT=my component" .
In this step, we use the Dockerfile downloaded in Step 1 to create the new image with libdf.so included.
- DF_INSTRUMENTED_IMAGE: name of the instrumented docker image. You have to deploy this image as part of your deployment pipeline.
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.
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
DF_COMPONENT (required) specify the name of your component