Mention URLs in our error messages

[ozgune]

We hear questions from our users about some of our error messages. @will noted that we could mention URLs (where appropriate) in our error messages to provide more info.

For example, we could use one of the attached FAQ errors as an example:

test=# SELECT COUNT(t.id) FROM "event" "t" LEFT JOIN "sensor" ON sensor.id = t.sensor_id;
ERROR: cannot perform distributed planning on this query
DETAIL: Shards of relations in outer join queries must have 1-to-1 shard partitioning. More info https://cit.us/102
-> we can always re-direct the content to be the right one, without necessarily a pull request later on.

I'm thinking another side benefit of this approach could be that we could infer which error messages frequently come up and confuse our users.

We could add this URL initially for #750, #949, #693, and #310.

[ozgune]

We talked about this in more detail and had two proposals.

(1) We append an optional 30-character note to the end of the error message. For example, "cannot perform distributed planning on this query. See See citusdata.com/e/2090".

One drawback to this approach is that it conflicts with PostgreSQL's conventions on error messages. Postgres asks to keep the primary message short (one line) and factual. We mostly followed this convention in Citus' error messages so far.

(2) We append this note as part of the detail or hint portion of an error message. One drawback to this approach is that some drivers might hide an error message's fields from the application (re: Visibility of PostgreSQL error fields in various drivers)

[lithp]

(1) seems like the better option even if it went against the postgres conventions, but it's not clear to me that it does. From the page you linked:

The primary message should be short, factual, and avoid reference to implementation details such as specific function names. "Short" means "should fit on one line under normal conditions". Use a detail message if needed to keep the primary message short, or if you feel a need to mention implementation details such as the particular system call that failed.

As long as we keep the total message short adding a link seems okay. And if the whole point is additional usability, shoving them somewhere they might not be seen seems like a bad idea.

[lithp]

Also, a strong yes in this ticket, this would be such a big win!