fix: add trace:on and trace:off

Closes #3553

ISSUE_TEMPLATE.md

@@ -29,9 +29,7 @@
 
 ### Additional information
 
-- Container Inspect Output (if applicable):
-  - 0.13.0+: `dokku inspect APP_NAME`
-  - <0.13.0: `docker inspect CONTAINER_ID`: WARNING, `docker inspect` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX.
+- Container Inspect Output (if applicable) via `dokku inspect APP_NAME`
 - `cat /home/dokku/<app>/nginx.conf` (if applicable):
 - Link to the exact repository being deployed (if possible/applicable):
 - If a deploy is failing or behaving unexpectedly:
@@ -40,5 +38,5 @@
   - If using buildpacks, which custom buildpacks are in use
   - If using a `Dockerfile`, the contents of that file
   - If it exists, the contents of your `Procfile`.
-- Output of failing Dokku commands after running `dokku trace on`
-  (BEWARE: `trace on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX):
+- Output of failing Dokku commands after running `dokku trace:on`
+  (BEWARE: `trace:on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX):

docs/configuration/environment-variables.md

@@ -92,7 +92,7 @@ The following list config variables have special meaning and can be set in a var
 | `DOKKU_DETACH_CONTAINER`       | none                            | `--detach` flag                                                                                                                                  | Whether to detach a container started via `dokku run`. |
 | `DOKKU_QUIET_OUTPUT`           | none                            | `--quiet` flag                                                                                                                                   | Silences certain header output for `dokku` commands. |
 | `DOKKU_RM_CONTAINER`           | none                            | `dokku config:set` <br /> `--rm-container` flag <br /> `--rm` flag                                                                               | Whether to keep `dokku run` containers around or not. |
-| `DOKKU_TRACE`                  | none                            | `dokku trace on`   <br /> `dokku trace false` <br /> `--trace` flag                                                                              | Turn on very verbose debugging. |
+| `DOKKU_TRACE`                  | none                            | `dokku trace:on`   <br /> `dokku trace:off` <br /> `--trace` flag                                                                              | Turn on very verbose debugging. |
 | `DOKKU_APP_PROXY_TYPE`         | `nginx`                         | `dokku proxy:set`                                                                                                                                | |
 | `DOKKU_APP_RESTORE`            | `1`                             | `dokku config:set` <br /> `dokku ps:stop`                                                                                                        | |
 | `DOKKU_APP_SHELL`              | `/bin/bash`                     | `dokku config:set`                                                                                                                               | Allows users to change the default shell used by Dokku for `dokku enter` and execution of deployment tasks. |

docs/getting-started/troubleshooting.md

@@ -1,5 +1,38 @@
 # Troubleshooting
 
+> New as of 0.17.0
+
+```
+trace:on                                       # Enables trace mode
+trace:off                                      # Disables trace mode
+```
+
+## Trace Mode
+
+By default, Dokku will constrain the amount of output displayed for any given command run. The verbosity of output can be increased by enabling trace mode. Trace mode will turn on the `set -x` flag for bash plugins, while other plugins are free to respect the environment variable `DOKKU_TRACE` and log differently as approprate. Trace mode can be useful to see _where_ plugins are running commands that would otherwise be unexpected.
+
+To enable trace mode, run `trace:on`
+
+```shell
+dokku trace:on
+```
+
+```
+-----> Enabling trace mode
+```
+
+Trace mode can be disabled with `trace:off`
+
+```shell
+dokku trace:off
+```
+
+```
+-----> Disabling trace mode
+```
+
+## Common Problems
+
 __Symptom:__ I deployed my app but I am getting the default nginx page.
 
 __Solution:__
@@ -41,22 +74,7 @@ __Symptom:__ I want to deploy my app, but while pushing I get the following erro
 
 __Solution:__
 
-The `remote rejected` error does not give enough information. Anything could have failed.
-
-To enable Dokku tracing, simply run the following command:
-
-```shell
-# since 0.3.9
-dokku trace on
-```
-
-In versions older than 0.3.9, you can create a `/home/dokku/dokkurc` file containing the following:
-
-```shell
-export DOKKU_TRACE=1
-```
-
-This will trace all of Dokku's activity. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue.
+The `remote rejected` error does not give enough information. Anything could have failed. Enable trace mode and begin debugging. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue.
 
 ***
 

plugins/trace/commands

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+[[ " help trace:help " == *" $1 "* ]] || exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
+source "$PLUGIN_AVAILABLE_PATH/trace/internal-functions"
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+case "$1" in
+  help | trace:help)
+    trace_help_cmd "$@"
+    ;;
+
+  *)
+    exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
+    ;;
+
+esac

plugins/trace/internal-functions

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+trace_help_content_func() {
+  declare desc="return trace plugin help content"
+  cat <<help_content
+    trace, [DEPRECATED] Enables/Disables trace mode
+    trace:on, Clones an app
+    trace:off, Create a new app
+help_content
+}
+
+trace_help_cmd() {
+  if [[ $1 == "trace:help" ]]; then
+    echo -e 'Usage: dokku trace[:COMMAND]'
+    echo ''
+    echo 'Manage trace mode'
+    echo ''
+    echo 'Additional commands:'
+    trace_help_content_func | sort | column -c2 -t -s,
+  elif [[ $(ps -o command= $PPID) == *"--all"* ]]; then
+    trace_help_content_func
+  else
+    cat <<help_desc
+    trace, Manage trace mode
+help_desc
+  fi
+}

plugins/trace/plugin.toml

@@ -0,0 +1,4 @@
+[plugin]
+description = "dokku core trace plugin"
+version = "0.16.4"
+[plugin.config]

plugins/trace/subcommands/default

@@ -3,23 +3,25 @@ set -eo pipefail
 [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
 
-dokku_trace_cmd() {
-  declare desc="enables/disables DOKKU_TRACE"
+trace_default_cmd() {
+  declare desc="enables/disables trace mode"
   local cmd="trace"
   [[ -d $DOKKU_ROOT/.dokkurc ]] || mkdir -p "$DOKKU_ROOT/.dokkurc"
   [[ "$2" == "on" ]] || [[ "$2" == "off" ]] || {
     dokku_log_fail "Valid trace options are [on/off]"
   }
 
+  dokku_log_warn "Deprecated: Please use trace:on or trace:off"
+
   if [[ "$2" == "on" ]]; then
-    echo "Enabling dokku trace"
+    dokku_log_info1 "Enabling trace mode"
     echo "export DOKKU_TRACE=1" >"$DOKKU_ROOT/.dokkurc/DOKKU_TRACE"
   fi
 
   if [[ "$2" == "off" ]]; then
-    echo "Disabling dokku trace"
+    dokku_log_info1 "Disabling trace mode"
     rm -f "$DOKKU_ROOT/.dokkurc/DOKKU_TRACE"
   fi
 }
 
-dokku_trace_cmd "$@"
+trace_default_cmd "$@"

plugins/trace/subcommands/off

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+trace_off_cmd() {
+  declare desc="disables trace mode"
+  local cmd="trace"
+  [[ -d $DOKKU_ROOT/.dokkurc ]] || mkdir -p "$DOKKU_ROOT/.dokkurc"
+
+  dokku_log_info1 "Disabling trace mode"
+  rm -f "$DOKKU_ROOT/.dokkurc/DOKKU_TRACE"
+}
+
+trace_off_cmd "$@"

plugins/trace/subcommands/on

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+trace_on_cmd() {
+  declare desc="enables trace mode"
+  local cmd="trace"
+  [[ -d $DOKKU_ROOT/.dokkurc ]] || mkdir -p "$DOKKU_ROOT/.dokkurc"
+
+  dokku_log_info1 "Enabling trace mode"
+  echo "export DOKKU_TRACE=1" >"$DOKKU_ROOT/.dokkurc/DOKKU_TRACE"
+}
+
+trace_on_cmd "$@"