runtime: document missing GODEBUG settings

[bradfitz]

src/runtime/extern.go needs docs for some missing GODEBUG keys:

• h2debug (from https://go-review.googlesource.com/#/c/17754/1/http2/http2.go@29)
• h2client=0 (from net/http) and upcoming(?) h2server=0?
• netdns (documented elsewhere, but not in runtime/extern.go)

/cc @ianlancetaylor

[minux]

I'm wondering if we're overusing the GODEBUG environment variable. For example, http2 is not handled by runtime, so it seems counterintuitive to document it in the runtime. Perhaps the http2 stuff should just use its own environment variable for that and leave GODEBUG for things that is really about runtime debugging. (It's already to late to change the netdns settings.) If we really want to use GODEBUG like this, it's probably better to export a runtime interface to query for value of a specific key in the GODEBUG, and document that each package can have its own handling of the variable and refers the user to individual packages for the GODEBUG settings. (But then there will be conflict key usages in the $GODEBUG, and I don't really want to see it either. Note that this is not really different from the status quo, and the GODEBUG parsing code is scattered throughout the standard library. At least we could add an internal package for this, for example, internal/debug.)

[bradfitz]

/cc @rsc

[rsc]

I'm not wild about the overuse of GODEBUG but I'm less wild about new environment variables, so I think it's OK. I would like the http2 stuff to die out eventually, but maybe that's naive. It would be fine to put a sentence in the runtime docs pointing at the net and net/http docs. I don't want the actual details in package runtime; they clearly don't belong there.

[bradfitz]

@rsc, any opinions on something like an internal/debug package as @minux mentioned? The repetitive parsing is annoying and inconsistent. But maybe you don't want to encourage usage.

[rsc]

Let's not bother with an internal/debug for now. Thanks. I'm afraid this is going to turn into Java's -XX:.

[rsc]

@bradfitz, can you please make the http2 support use http2 instead of h2 in the GODEBUG keys and document them in the net/http package doc?
I'll put a pointer to both net and net/http from the runtime discussion of GODEBUG.

[bradfitz]

Will do.

[gopherbot]

CL https://golang.org/cl/18346 mentions this issue.

[gopherbot]

CL https://golang.org/cl/18373 mentions this issue.