"host" is repeatedly used as questionable descriptor for full url aka "http://localhost:8086"

[wolfgangr]

Describe the issue here.

complicated description arising from backup error here:
influxdata/influxdb#25460

simple root cause:
influx ping --host localhost does not work
influx ping --host "http://localhost:8086" works

I'd consider it as an documentation issue.
There are loads of web articles from people trapped by this.
"host" in my mental dictionary is just the "host" part of an URL, while in influx world, obviously it refers to a complete url:
"protocol://host:port"

I know that any influx pro is just rofl on this case.
But climbing up the learning curve this are silly issues costing you hours of work.

Relevant URLs

• https://docs.influxdata.com/influxdb/v2/admin/backup-restore/backup/
• Provide other relevant URLs (project issues, community threads, etc.)

[jstirnaman]

@wolfgangr Thanks for raising this. I agree that the naming of the --host flag and the corresponding env variable can be misleading for the reason you describe. For that reason, in the CLI reference we use phrasing like the following:

HTTP address of InfluxDB (default: http://localhost:8086)

Do you have an example in the docs web site that isn't clear about this or are you referring to the Usage docs in the CLI itself? The URL that you listed (https://docs.influxdata.com/influxdb/v2/admin/backup-restore/backup/) doesn't include the use of --host.

[wolfgangr]

The URL that you listed (https://docs.influxdata.com/influxdb/v2/admin/backup-restore/backup/) doesn't include the use of --host.

Sure? 🙈 🙊 😁

The superficial answer might be:
"Well, that's the mistake then"

But we don't spend our time on deciding who is right and wrong, but on assisting other people not to fall in the same trap - OK?
So let me try to step down the rabitt hole of causality

• why did I not add the host in the beginning?
• why did I not search and find for the correct syntax
• how did I come to the idea to add a --host clause without looking for proper syntax?

I try to remember:

• I wanted to do a backup, so I typed this in the search field of influx docu (or may be I was pointed by a web search)?
• there are a couple of overlapping pages, so by mix of random and search for simplicity, I took one
• I typed the example in my command line and got a message indicating "missing environment variable"
• I don't like to pollute my console namespace with environment variables
• I memorized that there are --host clauses, so I tried this
• the error message received was completely misleading, so I assumed a version mismatch and filed issue #25460

What could the influx development team do to avoid people get trapped?

Envrionment variables

Of course, this is a matter of habit and taste. But those have reasons, too:

From https://peps.python.org/pep-0020/#the-zen-of-python

Namespaces are one honking great idea -- let's do more of those!

...and the cmd line env is a namespace with quite a laaaarge scope.

I know that many projects - Python itself among them - don't care about this wisdom and release uncooperative Software.
And then end up in requiring virtual environments, docker images and whatever kind of sanboxing to manage even simple task.

Sure, you may add your veryveryvery secret token to your .bashrc, if you're on a docker jail or development-dont-care-box.

But on a headless production machine, when I administer dozens of services from parallel ssh sessions maybe from different clients, that's not the way to go.
OK, may be, in fine crafted skripted shell pipelines, environment variables have their place, too.
But the maturing path from development to deployment leads through the quagmire of interactive trial, testing, and hands-on quick fixes, which quite often are performed on an interactive command line.

Anyway, essence:
May be you don't implicitly assume that people keep their config in environment variables when you write your documentation

Misleading error messages

Having understood my mistake, it was immediately obvious that the "version mismatch" did not come from influxdb <-> influx cmd line, but from apache <-> influx cmd line, sitting at the default http port.

The developer may say "so, look, not my fault".
But the user feels "but still my problem".

Essence: since the web is full of similiar case report, may be it is worth to consider to catch this case (reporting server seems not to be an influxDB) and report a proper error message aka "host may not be a influxd, please check your host URL . format http://hostname:port"

Organisation of documentation

To admit, I find the structure of Influx documentation rather confusing.
I have at least three windows of firefox open, each with a dozen or so Influx/telegraf documentation, and some web searches and strayed forum threads to geht ahead.
I'm sure, you are aware of that and work on that issue, right?

If you think my input may help you in your strive to improve documentation, we may try to dig further.

If you think that's OK rihgt now or even I'm stealing your valuable time, simply close the issue.

[wolfgangr]

just cleaning up and found the files I think yo might think "why didn't he look there":

https://docs.influxdata.com/influxdb/v2/reference/cli/influx/backup/

Indeed is refered to by the issue's starting page in a Link quite at the bottom.
In the example section, there is no full URL as required.

The option flag enty reads
--host HTTP address of InfluxDB (default: http://localhost:8086)

I can remeber having seen this before.
And at superficial reading, I'd understand:
"when no --host is provided, it defaults to this setting"
and (... implicitly, false...):
"if only hostname ist given, protocol will default to http and port to 8086"

For protocol, the guess was right, for port is was wrong.
Presumably, with some clue I might have startet looking closer there and might even had found the solution.

Howerver the message presented didn't provide any clue that I was talking to the wrong server.

influx backup: Error: API compatibility check failed:
Get "/health": unsupported protocol scheme

It was only when I got the second line of the message with a influx ping and did a web search on that, when I found the solution.

May be even the first line (presumably added by the backup code?) was even intended to provide assisting information.
Maybe, for a developer or influx professional, it does.
For the casual admin, it is even more distracting.

---

the other one is
https://docs.influxdata.com/influxdb/v2/reference/urls/
Even there it reads Default port: 8086

[jstirnaman]

I understand and apologize for the confusion. I see your point about the language used to describe the InfluxDB default URL in the influx CLI (and that may exist in other clients).

I'll keep this ticket open with this list of suggested improvements:

• docs-v2: for influx (and other clients?), clarify that the user needs to configure their InfluxDB URL. The use of "default URL" may be misinterpreted to mean that the client uses the default.
• docs-v2: improve and fix links to CLI configuration.
• docs-v2: include more examples that use flags and configurations, and fewer assumptions that env variables are set.
• influx CLI (and client library?) help and errors: clarify that the user needs to configure their InfluxDB URL (there is no client default), and be more helpful in error responses.

I'm sure I missed some finer points, so please list them if you can.

To admit, I find the structure of Influx documentation rather confusing.

If you have specific suggestions where we can improve, please add them. We have many docs improvements we want to make, but, like you, limited time and resources. This will help us prioritize.

FWIW, reliance on environment variables is also my pet peeve and I wish our documentation and tooling didn't rely on or assume them so often. I'm also a JS/UI developer and I get the dangers and annoyances of polluting the namespace.
In newer examples, I lean more toward using explicit config and parameters, but that hasn't historically been the case for the docs and the clients. I'll keep fighting the fight.

We truly appreciate the patience and the feedback.