docs: Rework of logs data model doc

[thompson-tomo]

Fixes #4735

Changes

This removes the resource and instrument scope fields from the log data model as they are not fields on the log record but rather higher level otlp fields.

The other changes are an attempt to align the document structure with that used in the metric data model doc.

For non-trivial changes, follow the change proposal process.

• Related issues #
• Related OTEP(s) #
• Links to the prototypes (when adding or changing features)
• CHANGELOG.md file updated for non-trivial changes
• Spec compliance matrix updated if necessary

[jsuereth]

I'm not sure I understand this PR.

DataModel != OTLP. We encode things into OTLP where the data model may not exactly match how things are encoded in OTLP, as OTLP is a protocol. We may have different protocols in the future where things are structured differently, but logs will still need a Resource + instrumentation scope.

I do not think this should be removed.

cc @jack-berg / @tigrannajaryan for thoughts.

[thompson-tomo]

The key thing the page says

Here is the list of fields in a log record:

The 2 fields removed are not in fact fields in the log record as discussed with @pellared who is the sponsor of changes based on the linked issue.

If you look at metrics https://opentelemetry.io/docs/specs/otel/metrics/data-model/#opentelemetry-protocol-data-model there it mentions the metric is identified based on resource/scope with the metric defined using a collection of properties which doesn't include resource/scope. Logs are no different.

[pellared]

The 2 fields removed are not in fact fields in the log record as discussed with @pellared who is the sponsor of changes based on the linked issue.

There should be something which describes the record's relationship to instrumentation scope and resource.

Also notice the lint errors from https://github.com/open-telemetry/opentelemetry-specification/actions/runs/19997659863/job/57347719833?pr=4783:

[home/repo/specification/logs/api.md]:
Error:  file:///home/repo/specification/logs/data-model.md#field-instrumentationscope | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

[home/repo/specification/logs/README.md]:
Error:  file:///home/repo/specification/logs/data-model.md#field-resource | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

[home/repo/specification/logs/sdk.md]:
Error:  file:///home/repo/specification/logs/data-model.md#field-instrumentationscope | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure
Error:  file:///home/repo/specification/logs/data-model.md#field-resource | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

If you look at metrics https://opentelemetry.io/docs/specs/otel/metrics/data-model/#opentelemetry-protocol-data-model there it mentions the metric is identified based on resource/scope with the metric defined using a collection of properties which doesn't include resource/scope. Logs are no different.

The Data Model specification structure is different for Metrics and Logs. Do you want to unify the document structure?

[pellared]

@thompson-tomo, are you planning to work on this?

[thompson-tomo]

Sorry missed the previous comment. I have made an attempt to update the structure of the logs data model doc to be more like the metrics equivalent.

I have tried to keep text changes to a minimum with alot of the changes coming from re-organising sections.

[github-actions]

This PR was marked stale. It will be closed in 14 days without additional activity.

[jack-berg]

The "log data stream" is conceptually new. It borrows from metrics, but I'm not sure its necessary. In metrics, streams have an identity and its critical for backends to define the identity of the stream to properly associate points with it. For logs, while some backends may adopt a log stream mentality and benefit from an identity from that stream, its not strictly necessary.

I like that you're trying to make the log data model more consistent with metrics, but don't want to over do it. For example, if we go in this direction, then for consistency sake, we would want to add a trace data model document, and add similar language about span streams. If we really want to talk about all signals in terms of streams with an identity and which group individual objects, then this is a bigger conversation.

As @jsuereth points out, data model does not equal OTLP. You respond "The 2 fields removed are not in fact fields in the log record". But to drive home the point that data model != OTLP, here is the java in memory representation of a log record, which does have resource and scope as fields on the log record. When OTLP exporter receives a batch of these LogRecordData objects, it groups them by resource and scope to transform to the alternative OTLP proto representation of the data model.

[tigrannajaryan]

I am not sure this PR solves a problem that needs solving.

#4735 says that fields in data model are not aligned exactly with the fields in OTLP protocol. That is not a requirement that we have. The distinction and allowance for logical data model to structurally differ from representation in OTLP protocol is deliberate.

Logical data model's purpose is to explain the model. OTLP protocol is a concrete implementation of that data model optimized for specific needs (wire efficiency, ProtoBuf in-memory representation, etc).