Debugging the Chef Run


When debugging Chef, several strategies exist. In this article, we review the main approaches to addressing multiple issues with the Chef run.


Troubleshooting strategies

Enzyme commands

When debugging a specific Recipe, you may need to make any changes to the files under /etc/chef/recipes/cookbooks/<recipe_name>/recipes/. However, initiating a Chef run normally will redownload the Recipes and remove any manual changes you might make.

To prevent Enzyme from re-downloading everything, you can manually run a specific Recipe, which includes any Recipes you may create in the instance. An example is below:

  1. Create ey-init/recipes/worker.rb, containing the recipe to be imported:
    include_recipe "passenger5”
  2. Run the Enzyme command:
    /home/ey/bin/ey-enzyme --refresh-dna --cached --run-list ey-init::worker --chef-bin /home/ey/bin/chef-solo

In the above context, the following parameters are leveraged:

  • refresh-dna: Will force dna.json to be re-downloaded.
  • cached: Makes sure to use the recipes in the instance, instead of re-downloading them, where able.
  • run-list: Selects the entry point for Chef.
  • chef -bin: Provides the Chef executable to be used.

Usage of '--run-list'

Passing a specific recipe as an entry point will start execution there, but it may not be restricted to that recipe only. If the recipe includes others, then Chef will execute those others as well.

If need to run the full set of recipes, then remove the --run-list parameter altogether. This will prompt Chef to use the entry point indicated by dna.json.

Identifying customizations

When debugging a Chef run, it is paramount to identify whether any custom Recipes are in place. However, identifying whether any default Recipes are being overlaid with customizations may be slightly trickier. The best way to do this is by running the following command:

ls -ltr /etc/chef/recipes/cookbooks/

Since Enzyme works by unpacking customizations from S3 after installing the regular Recipes, any custom elements will have a last updated time that is slightly later than the default Recipes.

A more precise method, although more involved, is to run the following command:

echo "Enabled using custom recipes:" && grep 'depends' /etc/chef/recipes/cookbooks/ey-custom/metadata.rb | awk '{print $2}'; echo; echo "Enabled using env vars:"; grep "EY_" /etc/chef/dna.json | awk '{print $2}'

On the other hand, it is interesting to understand that custom Recipes offered by Engine Yard fall into two categories when it comes to troubleshooting:

  • Custom recipes that simply import an existing core recipe: They allow for easy configuring of the core Recipes. Note that the same Recipe may be otherwise imported by the core run. Example: custom-memcached.
  • Custom recipes that are complete, new recipes: These have a much larger code and are not present in the core recipes. Example: custom-datadog

Finding logs

The following logs are related to instance configuration and Chef runs. Logs from previous runs are kept as well, with a suffix indicating the year/date/time of execution.

Version Location
  • /var/log/chef.main.log
  • /var/log/chef.custom.log
  • /var/log/enzyme.log
  • /var/log/chef.log
  • /var/log/ey-enzyme.log
  • /var/log/ey-primer.log
v6 & v7
  • /var/log/chef.log
  • /var/log/ey-enzyme.log
  • /var/log/ey-mnml.*.log


To address issues with the Chef run, it is important to be able to locate the logs, as well as to execute a specific recipe with any changes required via Enzyme commands. Customizations are another common source of issues, and therefore need to be identified promptly when troublehsooting.


Article is closed for comments.