[Logs] Add semantic conventions for writing exceptions

[CodeBlanch]

Changes

Defines how exceptions should be written when using the logs & events API.

/cc @jack-berg @scheler @MSNev

[reyang]

LGTM with a changelog entry.

[scheler]

Interesting addition to Logs semantic conventions. Requires clarification on a few things.

[yurishkuro]

Could you please explain why this change is needed, specifically why it needs to redefine how exceptions are logged instead of referring to the existing definition under /trace/, as this PR already does for .stacktrace?

[CodeBlanch]

@yurishkuro

Could you please explain why this change is needed, specifically why it needs to redefine how exceptions are logged instead of referring to the existing definition under /trace/, as this PR already does for .stacktrace?

What I brought up on the Log SIG was that logging exceptions is common and the spec should define what to do. We could say "see trace exceptions" (which we kind of do) but the trace document is referencing spans & span events which are not applicable to logs. So the goal here is to prescribe what to do without ambiguity.

What perhaps might be better is to move exceptions.yaml up a level and then have traces + logs reference that?

[yurishkuro]

Yes, I would support making exceptions top-level category (cf. https://bit.do/telemetry-temple) and referring to it from both traces and logs.

[CodeBlanch]

@yurishkuro I moved exceptions.yaml up a level and it is now referenced by traces & logs. LMK what you think about that.

[tigrannajaryan]

I am confused about what this PR does. It seems like we have 3 different yaml files which define almost the same conventions (but not exactly the same).

Do we need the separate yaml files under traces and logs directories?

[CodeBlanch]

@tigrannajaryan

Do we need the separate yaml files under traces and logs directories?

It depends I suppose on where you stand on the DRY principle 😄 The yaml files are set up so that the Semantic Convention generator can spit out the markdown tables from a single source of truth. There a couple subtle (maybe not so) differences between traces & logs wrt to exceptions. Traces use an event off of span and have the escaped attribute.

If we want to jettison the generator and just mirror content manually, that is fine by me. The risk is they might become out of sync for the shared stuff.

[tigrannajaryan]

@tigrannajaryan

Do we need the separate yaml files under traces and logs directories?

It depends I suppose on where you stand on the DRY principle 😄 The yaml files are set up so that the Semantic Convention generator can spit out the markdown tables from a single source of truth. There a couple subtle (maybe not so) differences between traces & logs wrt to exceptions. Traces use an event off of span and have the escaped attribute.

If we want to jettison the generator and just mirror content manually, that is fine by me. The risk is they might become out of sync for the shared stuff.

I guess I am confused because I don't know how the generator works. Are you saying that the yaml files in traces and logs subdirectories reference the common yaml file?

[CodeBlanch]

@tigrannajaryan

I guess I am confused because I don't know how the generator works. Are you saying that the yaml files in traces and logs subdirectories reference the common yaml file?

💯! In the subdirectories you'll see ref used in the yamls like these in the log version. Then in the markdown you use the semconv tag thing like this in the log version which tells the generator to build the table in that location. The table gets built following the refs to the shared yaml.