It is my understanding that these groups are actually related, and as such I believe the naming is appropriate. WithGroup will cause log attrs to go into the group. GroupValue will cause the provided attrs in the arguments to go into the group, but unlike WithGroup it won't affect other attrs logged by the Logger.

There are are currently two different usages of "group" in the API which are completely unrelated:

I think you're right that in practice the uses of "group" are fairly distinct / distinctly motivated.

IMHO ... they are significantly related in terms of the data model. It's almost just that the following log lines should encode data equivalently into "g":{"a":1}, even while the first commits data more persistently to Handlers and the second observes data more transiently in a single record:

	log.WithGroup("g").With("a", 1).Info("")

	log.Info("", slog.Group("g", slog.Int("a", 1)))

Where it's about the structure of the data model more exclusively, and not about encoding or formatting, is for functionality like ReplaceAttr.

	log := slog.New(slog.HandlerOptions{
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if len(groups) == 1 && groups[0] == "g" {
				a.Value = slog.IntValue(2)
			}
			return a
		},
	}.NewJSONHandler(os.Stdout))

It's maybe a little more straightforward that we expect "g":{"a":2} from both of the logging calls from this perspective - no opinion on the method name but I do think there is a real relationship here.

According to the documentation, WithGroup causes "attributes [to be] qualified by the group name". My expectation based on that was to get "g.a" as key in JSON, not an object. But I hadn't actually run an example (nor seen one, I believe). My expectation turned out to be wrong: both calls do the exact same thing.

That makes this proposal incorrect.

@pohly, thanks for closing. I used the phrase "qualified by the group name" in the docs deliberately, to avoid committing to what that might actually look like. I tried to clarify that in https://go-review.googlesource.com/c/go/+/478056.