Refine log fields

[jack-berg]

A handful of questions have come up regarding log fields. This issue tracks them so we don't forget.

1. All the fields in the log proto are optional except timestamp, but only traceId, spanId, severityText, and Name are @Nullable. The other fields have default values. We should have a uniform strategy on this, or good reasons for breaking uniformity.
2. There have been discussions about removing the setBody(Body body) method and simply keeping setBody(String message).
3. There have been discussions about dropping or renaming the name field.
4. We should make setFlags(int flags) more usable. Perhaps setFlags(LogFlags) akin to TraceFlags?

[jkwatson]

for 4), has the log SIG defined any flags yet? If not, we should probably just leave that out of our SDK until they do.

[jack-berg]

On closer inspection, flags is actually trace flags.

There's an open spec issue to clarify its purpose.

[jkwatson]

On closer inspection, flags is actually trace flags.

oh! Then we should definitely change our model to just accept TraceFlags and be done with it. :)

[anuraaga]

Also to capture, an idea I'm quite fond of is having a LogEmitter.logBuilder().emit() type of pattern as opposed to LogEmitter.emit(Log.builder().build())

https://github.com/open-telemetry/opentelemetry-java/pull/3759/files#r731228356

[jkwatson]

Also to capture, an idea I'm quite fond of is having a LogEmitter.logBuilder().emit() type of pattern as opposed to LogEmitter.emit(Log.builder().build())

https://github.com/open-telemetry/opentelemetry-java/pull/3759/files#r731228356

I'm definitely ok with starting with this API, and if someone really needs a direct interface to implement (maybe to support delegation to another logging data model, and hence zero-copy?), then it could easily be added in the future.

[jack-berg]

I've included the change of the pattern to LogEmitter.logBuilder().emit() in PR #3759.

[jack-berg]

I believe 2 is resolved now that spec PR #2096 was merged explaining why log body should be structured.

2. There have been discussions about removing the setBody(Body body) method and simply keeping setBody(String message).

[anuraaga]

Would it make sense to leave the structured version out of the SDK until someone asks for it? It mentions compatibility with certain existing log formats, but perhaps we can wait until we know this actually exists in the Java ecosystem, unless someone already has an example.

[jack-berg]

I'd be on board to make it an internal implementation detail until required. Can keep the setBody(String) method and add a setBody(Body) overload when requested?

[jack-berg]

All but one of these items were addressed in #3837.

The last unaddressed item is about the log name field. This is being actively discussed in the specification. If the field is removed in the spec, I'll remove it here. But for now, I'll close this ticket.