show a stack trace when an error occurs

[meleu]

UPDATE

What was discussed here was already implemented via #635

---

Disclaimer

This is more like a brainstorming post.

It's something I'd like to see in bashly but still not sure how it would be implemented.

---

Idea

One more step towards making bash programming more in line with "how progamming is expected to look like"...

When an error occurs in a bash program, little information is displayed to aid debugging. What most bash programmers usually do as the first debugging investigation is to run the program with set -x, which is too verbose.

One trick I learned recently is to use the caller builtin to get useful information about the call stack. And then create a trap to give me a stack trace.

You can check help caller for the official description. I found this explanation particularly useful.

In order to use caller to generate an useful stacktrace, some "hacking" is needed. Here I share an implementation:

#!/bin/bash
# my-cli

#################################################
# Start of the stacktrace implementation snippet
#################################################

# `set -E` is mandatory to enable the `ERR` trap
set -Ee

stacktrace() {
  local i=0
  local caller_output line func file

  while caller_output="$(caller $i)"; do
    read -r line func file <<< "$caller_output"
    echo "[$i] ${file}:${line} $func"
    i=$((i + 1))
  done
}

# Trap errors and call the print_stack function
trap 'stacktrace' ERR

# End of stacktrace snippet ######################

# Example functions
function_a() {
  echo "hello from function_a"
  function_b
  echo "bye from function_a"
}

function_b() {
  echo "hello from function_b"
  function_c
  echo "bye from function_b"
}

function_c() {
  echo "hello from function_c"
  # 💥 error happens here 💥
  non-existing-command
  echo "bye from function_c"
}

# Call the initial function
function_a

Here's the output:

$ ./my-cli
hello from function_a
hello from function_b
hello from function_c
./my-cli: line 43: non-existing-command: command not found
[0] ./my-cli:43 function_c
[1] ./my-cli:36 function_b
[2] ./my-cli:30 function_a
[3] ./my-cli:48 main

Notes

set -E

This is needed so trap ... ERR can be inherited by the functions.

caller output

The default output is $line $func $file, but in other programming languages we usually see something starting with $file:$line ....

If we don't tweak the output, the stacktrace function would be much simpler like this:

simple_stacktrace() {
  local i=0
  while caller $i; do
    i=$((i + 1))
  done
}

In our example it would generate this output:

$ ./my-cli
hello from function_a
hello from function_b
hello from function_c
./my-cli: line 51: non-existing-command: command not found
51 function_c ./my-cli
44 function_b ./my-cli
38 function_a ./my-cli
56 main ./my-cli

Which is kinda confusing IMO.

To be fair, the implementation I've posted is probably too verbose, as the bashly-generated code is always in the same file. I posted that just for illustration.

Considerations

Although displaying a stack trace is a basic thing in many interpreted languages, the way to have it in bash requires our own implementation, and for it to be actually useful we need to enable flags (set -Ee) and set a trap, which can break existing code.

The possibility to have it via library functions looks safer, as it requires the programmer to be aware of what they're doing (future maintainers of the codebase can be confused, though).

[pcrockett]

I've tried to do something like this in the past, and got mixed results. It may have just been me writing a buggy implementation, or it may be that Bash just makes these things really hard.

I personally would be open to prototyping a library function that implements stack trace functionality and trying it out in a few of my projects, and see how it goes.

In any case, as you mention, this can't be abstracted away from the programmer so that they avoid needing to think about the details. For this reason I'm not entirely sure this belongs in the Bashly project itself. A stand-alone third-party library makes sense to me. That would force developers to actually look at some documentation and understand things first before they use it.

[DannyBen]

I like it.

1. I agree that adding a stack trace would help debugging in complex cases, and is expected from a programming language (or a framework that aims to make it look like one in our case).
2. I like having this as a standard library; bashly add stacktrace - the question is, can this be done in this way. It seems like two parts are needed: a function and something in the initialize to change the set directive. Libraries currently cannot do this - but perhaps there might be a way to overcome this.

As for the difference in output format - I did not see a huge difference, and for me simpler is almost always better.

Since you two seem to have some experience with this bash feature, I am open to try any implementation that you think can work, and can be added as a library. If the only obstacle in our way is the ability for a library to "inject" the set -E, lets focus on solving that.

[pcrockett]

yeah, on second thought, standard library makes sense.

BUT i can't think of a way to do this cleanly as a library without causing footguns. IMO all set directives should be an intentional decision by the developer, since it affects the entire program. automatically injecting -E for the developer would violate that.

perhaps a compromise: make the library detect whether -E has been specified, and crash the script with a helpful error message if not.

[DannyBen]

I wonder what is the level of demand for this. After all, anybody who is interested in this can do it easily.
If 1 of 100 users need it, then maybe it is not worth refactoring the libraries mechanism just to accommodate the need to inject / warn if something is missing upstream.

[meleu]

One thing that came to my mind is to have a wiki here in this repo. Then people can share recipes of how to solve certain kind of problems (like showing a friendly stacktrace).

Maybe some recipes can mature over time and then be part of bashly library...

[DannyBen]

That is not a bad idea.
The reason I did not open it, is that it always looked like a deprecated GitHub feature, and was usually empty.

I have enabled Wiki with editing access to everyone, lets see how it goes.

[meleu]

Just sharing the stacktrace function I'm currently using in my internal projects (and finding it quite nice 👌):

# src/lib/stacktrace.sh

stacktrace() {
  local exit_status="$?"
  local i=0
  local caller_output line func file

  log_error "${BASH_SOURCE[0]}:${BASH_LINENO[0]} in \`${FUNCNAME[1]}\`: $BASH_COMMAND"
  echo "Stack trace:"
  while caller_output="$(caller $i)"; do
    read -r line func file <<< "$caller_output"
    echo -e "\tfrom ${file}:${line} in \`$func\`"
    i=$((i + 1))
  done

  exit "$exit_status"
} >&2 # <-- this is important so all output goes to stderr

trap 'stacktrace' ERR

Example of output:

./my_app:424 in `do_op_signin`: op signin --account my_account.1password.com
Stack trace:
        from ./my_app:424 in `do_op_signin`
        from ./my_app:287 in `aws_signin`
        from ./my_app:684 in `my_app_aws_signin_command`
        from ./my_app:1206 in `run`
        from ./my_app:1215 in `main`

It's noticeable that it was inspired by Ruby errors. That's because in my current job we are all Rubyist.

[DannyBen]

Nice.

And I am assuming you add something like this to your initialize:

trap 'stacktrace' ERR
set -o errtrace

yes?

Should we reopen the discussion for making this a library?

[meleu]

And I am assuming you add something like this to your initialize:

trap 'stacktrace' ERR
set -o errtrace

Yeah, we still need the set -Ee (aka -o errtrace and -o errexit respectively). I don't use the initialize though.

I usually define the set flags in the bashly strict setting, and I use set -Eeo pipefail.

The trap I put right below the stacktrace function, in the src/lib/stacktrace.sh file.

---

Should we reopen the discussion for making this a library?

As I always use some sort of stacktrace in my bash programs, yeah!, I would love to have this as a library.

[meleu]

We started a lot of threads in this discussion and it's starting to become confusing. Let's try to use this one to discuss the implementation of a standard library for stacktrace.

My "top-level" idea is:

• the library provides a stacktrace function
• file: src/lib/stacktrace.sh
• it's up to the dev to decide if they want to enable errexit and errtrace (we can give instructions in the header)
• not really sure about where to put the trap, but I use it in the same stacktrace.sh and it works just fine.

What do you think?

[DannyBen]

Excellent. Yes, this is exactly the same path I had in mind.

I believe the trap can and should be in the initialize. Do you see any reason against it?

Lastly - one thing that I was concerned about, maybe you can confirm it is a non issue:
Is there any case where this error trap is executed during a "normal" bashly behavior? For example, when insufficient arguments were provided by the user?

[DannyBen]

Started implementation in #635