Add semantic conventions for log media attributes

[djaglowski]

Resolves #1772

Changes

Adds semantic conventions for file log source.

[dmitryax]

Should we define here which type of log data model attributes these should be applied to? If so, I see file related attributes as Resource attributes, and the stream attribute as log record attributes, but open for discussion.

[djaglowski]

I see file related attributes as Resource attributes

I disagree on this point because the log file is not really the source of the log, which would be necessary to categorize file attributes as resource attributes. The file is really just a communication mechanism between the source of the log and the consumer of the log.

Should we define here which type of log data model attributes these should be applied to?

Probably we should try to describe any new resource types as separate documents in this directory, so that there are no a log-specific resource types.

[dmitryax]

I disagree on this point because the log file is not really the source of the log, which would be necessary to categorize file attributes as resource attributes. The file is really just a communication mechanism between the source of the log and the consumer of the log.

This makes sense, but the attribute namespace name source_log sounds contradicting with this definition. Should we consider other names if log file is not source of the log? Maybe log.file.path and log.file.name?

[djaglowski]

@dmitryax This is a very good point.

I think the namespace you've proposed is a good description. My only hesitation is that it seems a bit more likely that this namespace risks a collision with actual log attributes. (i.e. a developer or a logging framework chooses to emit logs with a "log" key in the attributes) That said, it seems still unlikely enough that it probably should not guide this decision.

[tigrannajaryan]

i.e. a developer or a logging framework chooses to emit logs with a "log" key in the attributes

So, for reference the spec has a recommendation about this which says

Names SHOULD NOT coincide with namespaces. For example if service.instance.id is an attribute name then it is no longer valid to have an attribute named service.instance because service.instance is already a namespace. Because of this rule be careful when choosing names: every existing name prohibits existence of an equally named namespace in the future, and vice versa: any existing namespace prohibits existence of an equally named attribute key in the future.

Now, I think it is OK to use "log" as a namespace. I don't think we will want to have an attribute names "log". Presumably that would be for the body of the log record but there is a native field for that in our data model, so we will not want to make a semantic convention for an attribute "log" ourselves. This leaves the possibility of someone accidentally using "log" as an attribute name.

If they do it there is no catastrophic results, but it will be against Otel recommendations.

How likely it is for someone to accidentally do this? We can consider 2 typical use-cases:

• They emit logs using some logging library that is plugged into Otel Logging SDK. In this case this shouldn't happen since there is a native place to record the log body/message. Well, unless they explicitly try to set an attribute named "log", but why would they want to do it? I can't see it (and if they do this mistake, it is equally possible they do it for any other attribute that clashes with our namespaces).
• It comes from some 3rd party format. In that case it needs to be translated to Otel log data model somewhere (typically Otel Collector) and the attribute can be deleted during the conversion, so I think it should be fine. We do that for example in Otelcol fluentforward receiver which uses "log" or "message" for the body. The "log" attribute is put into the body and is not added as an attribute.

Of course there is a possibility someone can manually add an attribute using Otel Logging SDK or using Collector, but the again it can happen with any other attribute name, I don't think "log" is any different.

Perhaps there is some other scenario that I am missing.

---

With all this said I am not sure what's the proposal. :-) Do we want to go with log.file.path and log.stream or something else?

[djaglowski]

Thanks for your analysis Tigran.

It comes from some 3rd party format. In that case it needs to be translated to Otel log data model somewhere (typically Otel Collector) and the attribute can be deleted during the conversion, so I think it should be fine. We do that for example in Otelcol fluentforward receiver which uses "log" or "message" for the body. The "log" attribute is put into the body and is not added as an attribute.

This is basically the scenario I was pondering, but you've pointed out that this is easily handled.

Do we want to go with log.file.path and log.stream

This is where we've arrived. I'll update the PR.

[tigrannajaryan]

Please rebase.

[djaglowski]

This should be ready to merge, unless there is any more feedback.

[tigrannajaryan]

@djaglowski I think this needs one more rebase. I enabled auto-merged, should be merged once you rebase.