[doc] Align agents logs documentation

[SylvainJuge]

update logs docs for nodejs agent, part of elastic/apm#800

[trentm]

@SylvainJuge Could you please merge in changes from 'main'. I ask because #3406 was recently merged and it includes changes that were meant to help with this "test Expected -- waiting for status to be reported" issue with a docs-only change hanging on the "test" check.

Then I'll have some review suggestions in a little bit.

[trentm]

@SylvainJuge Thanks for doing this! Would you be willing to apply this patch: https://gist.github.com/trentm/ad13d845d868ddb6ed60ba5f4b2366cf

• It updates a link from the old <<log-correlation>> to the new one.
• It drops usage of embedding some of the apm.currentTraceIds docs in the log correlation section. I don't think that re-embedding was useful because the common case we hope for is users not having to worry about it by using the ecs-logging-nodejs packages, or eventually automatic formatting.
• It does some re-wording. The current impl of injecting trace.id etc. is a little different in Node.js. Currently the ecs-logging-nodejs packages call the APM agent to get the IDs and then insert them. This is different than the other APM agents where I think the APM agent instruments the logging library to inject fields.

[SylvainJuge]

@trentm thanks for the patch ! I've just applied it + added a few links, let me know if there is anything left you'd like to change here, if there is none then you can merge it.

[trentm]

Suggested change

	* {ecs-ref}/ecs-tracing.html[`transaction.id`]* or {ecs-ref}/ecs-error.html[`span.id`]
	* {ecs-ref}/ecs-tracing.html[`transaction.id`] or {ecs-ref}/ecs-tracing.html[`span.id`]

@SylvainJuge I'd noticed that the equivalent docs for the Java APM agent mention the error.id field. Is that why you linked to ecs-error.html originally here?

Currently the ecs-logging-nodejs libs are setting span.id if there is a current span. Having re-read the ecs-logging spec, I suspect that I had it wrong all along that span.id should be set. It looks like it should always be trace.id and transaction.id. I don't know if log-correlation works in APM UI when span.id is set, but not transaction.id. I've opened elastic/ecs-logging-nodejs#146 to eventually look into this.

Aside: The Java agent is setting error.id if there is an "active" error. The Node.js agent doesn't have a concept of an "active" error, so I'm not sure we can do the same. FWIW, the ecs-logging spec (https://github.com/elastic/ecs-logging/blob/main/spec/spec.json) doesn't mention error.id. Anyway, this isn't relevant for this issue. I'm just curious.

[SylvainJuge]

For simplicity I've left span.id and error.id outside of the current scope for now:

• error.id is currently only used in java when capturing exceptions, and we lack proper specification for this (also there is some server-side implications)
• span.id is captured by some agents, but not all of them (the java agent does not for example).

I am not sure to get the trace.id and transaction.id part, let's discuss this live it might be easier.

[SylvainJuge]

In java the span.id for log correlation was removed a while ago with https://github.com/elastic/apm-agent-java/pull/742/files, to me the main concern was more technical (extra allocation) and consistency with other agents, and we could definitely challenge that (I'm pretty sure the current impl does not incur extra allocation right now).

I don't think the UI will have a different behavior when span.id is set in log messages, so it's fine to leave this as-is

• there isn't any navigation from a log message to a transaction or a span (which could still be something good to add)
• with our agents, a span is captured only within a transaction, thus we implicitly always have either trace.id+transaction.id+span.id or just trace.id+transaction.id
• we currently don't have an aggregated view for spans like we have for transactions, so the "log documents for a given span" can't be easily accessed.
• with otel log documents that are sent by otel agents (not our bridge), they have the trace.id and span.id set, but unlike with traces we can't easily interpret as a transaction from the logs only.

Long story short, I think fixing the link as you suggested is the right thing to do and we should be able to merge this.

[trentm]

Thanks, @SylvainJuge