How to debug/troubleshoot

[adswa]

Fixes #536.
Feedback welcome. At the moment, this is an overview of logging and a hint on how to get into the debugger, and a collection of funny comics to make reading the section less dreadful 😉
Also, I found datalad/datalad#4661 while at it.

[glatard]

Hi @adswa, this would be very useful!

Here is a bit of text that you might consider adapting and adding somewhere to this section (not sure what the right place is):

File doesn't get downloaded by datalad get <file_name>, no error message is returned

It is common for datalad get errors to originate in git-annex, the software used by DataLad to transfer data. Here are a few suggestions to debug them:

• Take a deep breath, or preferably a walk in a nice park :)
• Check that you are using a recent version of git-annex
  • git-annex version returns the version of git-annex on the first line of its input
  • The version number contains the release date of the version in use. For instance, git-annex version: 8.20200330-g971791563 was released on 30 March 2020.
  • If the version that you are using is older than a few months, consider updating using the instructions here
• Try to download the file using git-annex get -v -d <file_name>
  • If this doesn't succeed, the DataLad command may not succeed.
  • Options -d and -v are here to provide as much verbosity in error messages as possible
• Read the output of git-annex, identify the error, breathe again, and solve the issue!
• Examples of possible issues:

git-annex error	A solution that worked once
Last exception was: Could not find a suitable TLS CA certificate bundle, invalid path: /etc/pki/tls/certs/ca-bundle.crt [adapters.py:cert_verify:227]	unset environment variable CURL_CA_BUNDLE
Permission denied when writing file	Download to a writeable file system

[adswa]

That's fantastic @glatard, thank you!

[adswa]

I've added your suggestion to this PR - thanks! I might integrate the "common error messages and what they mean" section into the table format. I like it a lot!

[adswa]

ah, and before I forget: @all-contributors please add @glatard for content

[allcontributors]

@adswa

I've put up a pull request to add @glatard! 🎉

[adswa]

@mih, can you take a look at this if you get a chance? not urgent

[mih]

Cool, thx! I made a few remarks, but feel free to ignore them.

[mih]

Is this true? I though I still see INFO messages by default.

[adswa]

This assumption is based on https://github.com/datalad/datalad/blob/dd09e4dfd7014438305daf398b833f9e03e03273/datalad/cmdline/common_args.py#L41, but I may be mistaken:

_log_level_names = ['critical', 'error', 'warning', 'info', 'debug']
log_level = (
    'log-level', ('-l', '--log-level'),
    dict(action=LogLevelAction,
         choices=_log_level_names + [str(x) for x in range(1, 10)],
         metavar="LEVEL",
         default='warning',
         help="""set logging verbosity level.  Choose among %s.  Also you can
         specify an integer <10 to provide even more debugging information"""
              % ', '.join(_log_level_names))
)

[adswa]

I'll merge this, I have removed any mention of default log levels.