Skip to main content

Configuring the CLI for docker analysis

info

Type greenframe help if you are lost!

Greenframe works out of the box for docker, to run an analysis on a kubernetes cluster please check the dedicated part.

Using a Configuration File

At the root of your project, create a .greenframe.yml file :

baseURL: YOUR_APP_BASE_URL
scenarios:
- path: PATH_TO_YOUR_SCENARIO_FILE
name: My first scenario
threshold: 0.1
projectName: YOUR_PROJECT_NAME
samples: 3
distant: false
useAdblock: true
containers:
- "CONTAINER_NAME"
- "ANOTHER_CONTAINER_NAME"
databaseContainers:
- "DATABASE_CONTAINER_NAME"

Then in the same folder, GreenFrame CLI will automatically take the configuration file.

baseURL: Your app base URL (e.g http://localhost:3000), note that page.goto in your scenario method will be affected by this base url.

scenarios: Enter a list of scenarios that you want to run.

  • path: Absolute path regarding to the configuration file to locate your scenario.
  • name: Add a name to your scenario to identify it inside the GreenFrame app.
  • threshold: in Wh, the scenario will fail if the consumption passes this limit.

projectName: A name of your project, if the project doesn't exist, it will be created. It's used to manage the history of your project. If you omit it, GreenFrame CLI will search a PROJECT_NAME env variable or will take the name of your project.

samples: (default: 3) Number between 2 and 10 of runs of your scenarios. A high number will improve the duration of your CI but will also increase the precision.

distant: (default: false) Distant mode is used to run an analysis by using GreenFrame Server. Use this mode if your CI is unstable and if between 2 sames analyses you have a big difference. By using this mode you cannot track other containers than the browser.

useAdblock: (default: false) useAdblock allow you to block third party scripts like ads or trackers. Use this mode if you want to analyze an app which contains third party scripts and if you encounter difficulties or simply just want to ignore their costs.

containers: A list of your server containers name (like api, proxy or cache system) that you want to measure during an analysis. Enter the same name as you see it when typing docker ps, you can also fix it inside the docker-compose with by using the container_name field

databaseContainers: A list of your database containers name (like PostgreSQL or mongoDB) that you want to measure during an analysis. Enter the same name as you see it when typing docker ps, you can also fix it inside the docker-compose with by using the container_name field

dockerdHost: (default: unix:///var/run/docker.sock) The docker daemon host.

dockerdPort: (default: 2375) The docker daemon port.

Using Another Configuration File

You can specify another location for your .greenframe.yml file by using the -C command:

Example : greenframe analyze -C ./another_folder/.greenframe.ci.yml

Running a GreenFrame Analysis with Custom Hosts

Sometimes your app should run on a specific URL in local which is not localhost. You have wrote in your /etc/hosts a mapping between 127.0.0.1 and your specific URL.

GreenFrame CLI cannot access to this mapping and you should pass it to the CLI during an analyze in order to let the CLI to access to theses URLs.

In your .greenframe.yml you can add the following lines:

extraHosts:
- "extra-host.com"
- "another.extra-host.com"

Running a Scenario in debug mode

To debug a scenario with a real browser, use the open command:

greenframe open SCENARIO BASEURL

Example : greenframe open ./scenario.js http://localhost:3000

A Chromium or Google chrome browser is required to be installed on your computer to execute this command correctly. If it's not the case you can install chromium by typing the following command :

sudo apt-get install chromium-browser

Running analysis on kubernetes

info

Even if we analyze an application running on a kubernetes cluster, the execution of the scenario is still using Docker (to launch the headless browser), the server on which the analyze is launch must have Docker installed.

Configuration file

Greenframe can perform an analysis on a kubernetes cluster. To do so, you need to add some specific configuration to your .greenframe.yml file.

//...
kubeContainers:
- "demo:name=app"
kubeDatabaseContainers:
- "demo:name=db"
kubeConfig: "/path/to/kube/config"

kubeContainers: A list of your server containers name. It takes the form of namespace:label[/container_name]. The container name is optional. If none is provided, we do an analysis at the pod level (and this is the recommended way to use GreenFrame). If you need to analyze a container inside a pod, specify the container name (for example "demo:name=app/api").

info

You can find the name of the containers by running kubctl get pods -n NAMESPACE -o json and looking for the spec.containers.name field.

kubeDatabaseContainers: A list of the database containers names. It takes the form of namespace:label[/container_name]. The container name is optional. If none is provided, we do an analysis at the pod level (and this is the recommended way to use GreenFrame). If you need to analyze a container inside a pod, specify the container name (for example "demo:name=db/postgres").

kubeConfig: The path to your kube config file. If a default config exists in your environment (usually ~/.kube/config) this configuration becomes optional.

The other fields are the same as the ones described above.

Kubernetes configuration

Once your configuration file is set up, you need to configure your kubernetes cluster to allow Greenframe to perform an analysis. To do so, run :

greenframe kube-config

This command will deploy a cadvisor daemonset on your cluster. This daemonset collects stats and exposes them to greenframe.

Greenframe daemonset architecture

You are now ready to perform your first k8s analysis.

CLI Commands

analyze

You can directly pass options as analyze command parameters to override how your analysis will be performed.

Using One Line Command

If for some reasons you don't want to perform an analysis by using a .greenframe.yml you can specify the baseURL of your project and the path to your scenario file directly in one command:

Example: greenframe analyze scenario.js http://localhost:3000

info

Please note by using one line command, you can't run multiple scenarios.

--projectName Option

To follow evolution of your analysis made on GreenFrame, use --projectName or -p to identify your project in GreenFrame.

The project name can be passed as the GREENFRAME_PROJECT_NAME environment variable in the CI environment.

If the project name is not specified through the command option or the environment variable, GreenFrame will automatically retrieve your git's project name and use it as the project name. Please note that the command must be executed in the corresponding git project for this to work.

Example: greenframe analyze scenario.js http://localhost:3000 --projectName my_awesome_project

--threshold Option

When using greenframe analyze in a CI environment, you typically want the build to fail if the carbon footprint exceeds a predefined threshold in Watt.hours. Use the --threshold option (or -t) for that.

Example : greenframe analyze scenario.js http://localhost:3000 --threshold 0.05

--commitMessage Option

When using greenframe analyze in a CI environment, you want to know for which commit GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the commit message detection by using the --commitMessage option (or -c).

Example : greenframe analyze scenario.js http://localhost:3000 --commitMessage "Add login feature"

--commitId Option

When using greenframe analyze in a CI environment, you want to know for which commit GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the commit ID detection by using the --commitId option.

Example : greenframe analyze scenario.js http://localhost:3000 --commitId "SHA1_COMMIT_ID"

info

Please note if this variable is not set, you will not be able to perform automatic comparison with your default git branch. This git branch can be configured per project inside your settings directly in the application.

--branchName Option

When using greenframe analyze in a CI environment, you want to know for which branch GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the branch name detection by using the --branchName option (or -b).

Example : greenframe analyze scenario.js http://localhost:3000 --branchName "feat/login"

--samples Option

When using greenframe analyze in a CI environment, you might want to change the number of samples that are performed by the analysis in order to improve the precision. Use the --samples option (or -s). Its default value is 3.

Example : greenframe analyze scenario.js http://localhost:3000 --samples 5

--distant Option

When using greenframe analyze in a CI environment, you must have docker installed. The analysis will be performed locally and the GreenFrame CLI will start a container in order to run your scenario.

It's fast but if you have an unstable CI environment (e.g : Free tier), you might want to use a more stable runner.

GreenFrame provides you with distant workers to run with your CLI. By passing --distant (or -d) the GreenFrame CLI will execute this analysis on our servers.

Example : greenframe analyze scenario.js http://localhost:3000 --distant

info

Please take in account that your analysis can be queued for a certain amount of time before being executed with the distant mode.

--useAdblock Option

Analyze an app containing third party scripts (ads or trackers) can encounter errors or slow analysis due to the weight of theses scripts. If you want to ignore them you can disable it by using our embedded adblocker.

Example : greenframe analyze scenario.js http://localhost:3000 --useAdblock

info

Please take in account that we use a predefined list of third party script to block. It's possible than your ads or tracker will not be blocked.

--configFile Option

If your configuration file is located to another path or is named differently than .greenframe.yml, you can provide a path to this file by using the --configFile or -C argument.

Example: greenframe analyze --configFile ./config/mygreenframefile.yml

--kubeConfig Option

If you need to specify a specific kube config, you can use the kubeConfig of -K option.

Example: greenframe analyze --kubeConfig ~/.kube/config.staging

--dockerdHost Option

If you need to specify a specific docker host, you can use the dockerdHost option.

--dockerdPort Option

If you need to specify a specific docker port, you can use the dockerdPort option.

kube-config

This command is kubernetes-specific and helps configure the cluster to let Greenframe monitor its activity and perform an analysis.

--configFile Option

If your configuration file is different from ./.greenframe.yml, you can provide a path to this file by using the --configFile or -C argument.

Example: greenframe analyze --configFile ./config/mygreenframefile.yml

--delete Option

If you want to delete the Greenframe daemonset from your cluster, you can use the --delete or -D option.

Example: greenframe kube-config --delete

--kubeConfig Option

If you need to specify a specific kube config, you can use the kubeConfig of -K option.

Example: greenframe kube-config --kubeConfig ~/.kube/config.staging