A screenshot is better than a thousand Words for debugging
Spring 2024
Attention: rant incoming - Please don't feel offended if I send this to you, it's just that after the hundredth message like the one below I have lost the patience writing the same thing over and over again.
As a contributor and developer of the SeAT eve corporation and alliance management tool, I frequently interact with users that have to troubleshoot problems with the application. A common pattern in these support requests is that they look something like this:
I can't access (data provided by an upstream API) on the web UI and I get an error saying the request is too long. I've increased the maximum request length in my nginx settings, but it doesn't help.
From this message, I see that:
- You have a problem
- It looks like it has something to do with an HTTP request from the browser.
- You changed something and it doesn't help
This is just not enough so that I can provide assistance. I therefore need to ask for more context if I even write back. Most likely, I'll ask for the specific error instead of the paraphrased version. I might get a message like this:
Request Too Long - The length of the request headers is too long.
That message tells me that your action of changing the nginx setting is not completely unreasonable, but since we advise people to install the application behind a reverse proxy, we still don't know if the error is from the reverse proxy or the application itself. A simple snippet of text like this error is often insufficient to tell from where an error originates. Visually, I can tell application errors apart from reverse proxy errors since they use different error page designs. I therefore ask whether the background color of the error is white or a blue-gray. They reply with:
It is yellow
This is very much confusing. I've never seen a yellow error page with this application. I might think about it for a day and then ask for a screenshot to really confirm it is yellow.
The screenshot shows that it is a terminal window. Additionally, besides the error I see a command that displays the logs of the upstream API. It is therefore an error with the upstream API.
How is it even possible that it takes this long to figure that out? It is mostly the first message:
I can't access the data
means the tables that are supposed to display data are empty. They therefore did the correct thing and looked at the logs and reported the error, although paraphrased. However, they never mentioned where they got the error from, making it look like it was in the browser and leading the investigation down the wrong way.
How it could have been
Even still using the same, suboptimal text message, the screenshot could be attached alongside the message from the start. This would have immediately changed the following things:
- The error is not in a browser
- It is from the upstream API since the screenshot inadvertently provides the missing hint that I am looking at the API logs
- One roundtrip to get a non-paraphrased error message could be saved.
- Your nginx fix cannot work since API requests don't go through nginx.
Conclusion
This is just one made-up and of course exaggerated example, but I've experienced multiple situations where simply including a screenshot would have helped massively.
Going forward, please just include a screenshot of the thing that makes you think something is wrong alongside your diagnosis of what is wrong, so I can check if it makes sense. Ultimately, it will help you!
Of course, this article is intentionally without any screenshot as illustrations :)