runtime/debug: add SetCrashOutput options

[adonovan]

The debug.SetCrashOutput function was added for go1.23, but has not yet been released. After discussion with @aclements, we agree that support for JSON-formatted crash output containing all the information of runtime.CallersFrames is a desirable feature, since it frees the consumer of the crash from having to be a process of the same executable as the producer of the crash (in order to make sense of the PCs), and from having to think about relative address mappings--and no doubt for other reasons as well.

We propose to change the signature of SetCrashOutput so that it has a second parameter of type CrashOptions, which is defined as an initially empty struct. (We expect to add JSON bool in future, but neither of has time to implement it before the go1.23 freeze.)

package debug // "runtime/debug"

type CrashOptions struct{} // for future expansion

func SetCrashOutput(f *os.File, opts CrashOptions)

This change may break clients that depend on unreleased go1.23 features, such as x/telemetry. As a tactical matter, I suggest we add a variadic parameter ...CrashOptions, update x/telemetry, and then remove the ..., all within a few hours. [Edit: doesn't work; clients will need to use typeswitch during the transition.]

[Stavrospanakakis]

@adonovan I tried to implement the solution by adding the variadic parameter ...CrashOptions.

However, after running the ./make.bash command, I got the following error:

 ./make.bash
Building Go cmd/dist using /usr/local/go. (go1.22.2 darwin/arm64)
Building Go toolchain1 using /usr/local/go.
Building Go bootstrap cmd/go (go_bootstrap) using Go toolchain1.
Building Go toolchain2 using go_bootstrap and Go toolchain1.
Building Go toolchain3 using go_bootstrap and Go toolchain2.
Building packages and commands for darwin/arm64.
# cmd/vendor/golang.org/x/telemetry/internal/crashmonitor
/Users/user/go/src/cmd/vendor/golang.org/x/telemetry/internal/crashmonitor/crash_go123.go:13:19: cannot use debug.SetCrashOutput (value of type func(f *os.File, opts ...debug.CrashOptions) error) as func(*os.File) error value in assignment
go tool dist: FAILED: /Users/user/go/pkg/tool/darwin_arm64/go_bootstrap install cmd: exit status 1

I suppose that the reason is the following line:

var setCrashOutput func(*os.File) error // = runtime.SetCrashOutput on go1.23+

For this reason, I opened these 2 pull requests #67192 golang/telemetry#8

What do you think?

[gopherbot]

Change https://go.dev/cl/583300 mentions this issue: runtime/debug: add the options parameter to SetCrashOutput

[gopherbot]

Change https://go.dev/cl/583278 mentions this issue: internal/crashmonitor: add the options parameter to the setCrashOutput

[adonovan]

Good point. Then perhaps we should just preemptively change x/telemetry to typeswitch on SetCrashOutput and do the right thing for both types.

[prattmic]

Marked as release blocker to ensure we make a decision before the release.

[aclements]

Other uses we discussed for the options struct:

• Forcing a particular level of GOTRACEBACK for that output
• Requesting that a user space core dump be in included (much more pie-in-the-sky, obviously)

[findleyr]

@prattmic I milestoned this for 1.23, rather than Proposal, since I think that affects tooling that searches for 1.23 release blockers. Please correct me if that's wrong.

@matloob please note that this will require re-vendoring x/telemetry. In fact, this will be tricky or impossible to land without breaking one of the builds.

[adonovan]

In fact, this will be tricky or impossible to land without breaking one of the builds.

Tricky but not impossible. The plan agreed above is:

1. change x/telemetry to use the symbol only in call position (thus avoiding a dependency on the precise type of the symbol).
2. change GOROOT to add a variadic ... parameter (and reject len > 1).
3. change x/telemetry to provide the options struct.
4. change GOROOT to remove the "...".

[Stavrospanakakis]

@findleyr More specifically, what about the following?

1. Merging the following PR internal/crashmonitor: update the setCrashOutput definition telemetry#8 that updates the setCrashOutput definition

• This pull request updates the type of the SetCrashOutput function to prepare the code for step 2

2. Add a variadic parameter called CrashOptions as done in this PR runtime/debug: add the options parameter to SetCrashOutput #67192
3. Open another PR to x/telemetry that adds the CrashOptions parameter
4. Remove the ... from the CrashOptions parameter introduced in step 2

Thoughts?

[findleyr]

Aha, thanks.

@adonovan sorry for missing this consideration in the top comment. That plan sounds feasible.

@Stavrospanakakis sure, that seems about right. I'll defer to @adonovan for coordinating these changes if/when the proposal is approved.

[rsc]

Based on the discussion above, this proposal seems like a likely accept.
— rsc for the proposal review group

The proposal is to change the recently added

func SetCrashOutput(*os.File)

to be

type CrashOptions struct{}
func SetCrashOutput(*os.File, CrashOptions)

for future extensibility.

We expect that there will be a JSON bool added in a future Go release (perhaps Go 1.24).

[rsc]

No change in consensus, so accepted. 🎉
This issue now tracks the work of implementing the proposal.
— rsc for the proposal review group

The proposal is to change the recently added

func SetCrashOutput(*os.File)

to be

type CrashOptions struct{}
func SetCrashOutput(*os.File, CrashOptions)

for future extensibility.

We expect that there will be a JSON bool added in a future Go release (perhaps Go 1.24).

[gopherbot]

Change https://go.dev/cl/585378 mentions this issue: internal/crashmonitor: prepare for SetCrashOutput signature change

[gopherbot]

Change https://go.dev/cl/585557 mentions this issue: runtime/debug: add SetCrashOutput(...CrashOptions) parameter

[gopherbot]

Change https://go.dev/cl/585835 mentions this issue: x/tools: update to x/telemetry@ac8fed8

[gopherbot]

Change https://go.dev/cl/585818 mentions this issue: cmd/vendor/golang.org/x/telemetry: update to ac8fed8

[gopherbot]

Change https://go.dev/cl/585478 mentions this issue: internal/crashmonitor: pass CrashOptions to SetCrashOutput

[gopherbot]

Change https://go.dev/cl/585819 mentions this issue: cmd/vendor/golang.org/x/telemetry: update to 9ff3ad9

[gopherbot]

Change https://go.dev/cl/585420 mentions this issue: runtime/debug: eliminate temporary variadicity from SetCrashOutput

[gopherbot]

Change https://go.dev/cl/585821 mentions this issue: x/tools: update to x/telemetry@9ff3ad9

[adonovan]

This is now complete. Please be sure to use tip GOROOT when building tip x/tools or x/telemetry.