Expanded documentation for tracing fields #1128

sgryphon · 2020-11-17T12:12:09Z

Additional usage documentation for tracing fields, with a longer explanation of trace.id, span.id, and how they are related, and the correlation purpose of each.

Documentation would not reproduce the diagrams inline, so added to the optional docs/usages/.asciidoc file.

Addresses issue #998

Note: I have added the generated files to the PR, as the build 'make check' wants them checked in.

Doc page preview

…, and how they relate to each other.

sgryphon · 2020-11-18T13:08:13Z

@webmat I see you added the label 1.9.0, which I am guessing means version 1.9. This is only additional documentation, not an actual schema change, so from SemVer point of view it is can be a patch version 1.7, as it is still fully compatible with 1.7

webmat · 2020-11-18T14:08:59Z

@sgryphon Yeah we did that tagging as part of regular planning and figuring what we have time for when. We hadn't noticed that you were actually contributing the documentation page itself.

This is great, thank you for submitting that :-)

We will review shortly, and we may indeed backport this all the way back to 1.7, so that the documentation page comes to life before the next release.

webmat · 2020-11-18T14:10:18Z

@elasticmachine, run elasticsearch-ci/docs

webmat · 2020-11-18T15:44:05Z

The doc page can now be previewed at https://ecs_1128.docs-preview.app.elstc.co/guide/en/ecs/master/ecs-tracing-usage.html :-)

…ansaction

webmat · 2020-11-24T19:12:21Z

@axw Do you feel like this doc page captures the discussion in #998?

axw

Thanks @sgryphon! This looks pretty good overall.

I'm happy to have this usage page. There are some discrepancies with Elastic APM which, along with ECS loggers, is (AFAIK) the only thing using these fields at the moment. I think it's important that we make some adjustments to avoid confusion.

@felixbarny @bmorelli25 any thoughts, concerns?

docs/usage/tracing.asciidoc

schemas/tracing.yml

Conflicts: CHANGELOG.next.md docs/field-details.asciidoc experimental/generated/beats/fields.ecs.yml generated/beats/fields.ecs.yml schemas/tracing.yml

…cribes (rather than messages)

…ate transaction spans, link to APM transactions.

sgryphon · 2021-01-25T08:47:10Z

Pull request has been updated based on feedback. Please review and let me know if there is anything else needed before it can be merged. Thanks.

axw

Thanks for the updates @sgryphon. LGTM!

bmorelli25 · 2021-01-25T17:24:43Z

@elasticmachine, run elasticsearch-ci/docs

Kicking off a new doc build and will take a look at the changes this afternoon. Thanks for putting this together @sgryphon

bmorelli25

Thanks again for putting this together! I have a few grammar/spelling recommendations. Everything is open for discussion, so feel free to let me know if you disagree with anything!

I'll mock up some graphics for this right now.

docs/usage/tracing.asciidoc

bmorelli25 · 2021-01-25T22:45:20Z

docs/usage/tracing.asciidoc

+Causal relationships between Spans in a single Trace
+
+       [Transaction Span A]  ←←←(the root transaction span)
+           |
+    +------+------+
+    |             | ←←←(call to Service 2)
+    |             v
+[Span B]      [Transaction Span C] ←←←(C is a child of A)
+    |             |
+[Span D]      +---+-------+
+              |           |
+          [Span E]    [Span F]
+------------------------------------------------------------------
+
+Sometimes it's easier to visualize **Traces** with a time axis as in the diagram
+below:
+
+------------------------------------------------------------------
+Temporal relationships between Spans in a single Trace
+
+––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–> time
+
+Service 1:
+[Transaction Span A·······································]
+[Span B··············································]
+    [Span D··········································]
+
+Service 2:
+    [Transaction Span C····························]
+        [Span E·······]        [Span F··]
+------------------------------------------------------------------


I'm not a fan of how these render. Let me mock up some graphics to replace these. Give me an hour.

bmorelli25 · 2021-01-26T00:18:54Z

Here's what I'm thinking for the causal and temporal graphics. Open to feedback.

@sgryphon If you're getting tired of updating this PR, let me know and I can make these changes for you.

ebeahan · 2021-02-01T20:48:55Z

Thanks, @sgryphon, for taking on authoring this content! The functionality to add the usage docs was added only recently, so it's great to see folks contributing already. 😄

Also, thanks to @axw and @bmorelli25 for the reviews and feedback. These graphics look amazing! ❤️ 💯

From an ECS-perspective, I do have reservations that this content is too focused on terminology and concepts and not focused enough on how to use/populate the ECS fields themselves. I prefer directing users to the APM docs' relevant sections as the more definitive reference for definitions and concepts. The ECS usage docs can then focus on applying the concepts with real-world examples using the tracing.* fields.

Those types of extended examples will help tie together concepts better for ECS users when mapping their own data sources. Some of the original questions from #998 were "How do these [fields] work together?", and I want to ensure that remains in focus here.

Co-authored-by: Brandon Morelli <[email protected]>

Nice pick up. Yes, it should definitely be an em dash! Co-authored-by: Brandon Morelli <[email protected]>

Co-authored-by: Brandon Morelli <[email protected]>

sgryphon · 2021-02-03T00:55:55Z

Here's what I'm thinking for the causal and temporal graphics. Open to feedback.

My question about the graphics are how are they generated? Using ASCII is viewable even in text output.

Mostly for diagrams I use something like PlantUML, to specify the diagram in text (under version control) and then generate the image.

But if you prefer straight images that is okay. I will create some SVG of the able, which are then more easily trackable in version control for changes.

sgryphon · 2021-02-03T01:22:57Z

Those types of extended examples will help tie together concepts better for ECS users when mapping their own data sources. Some of the original questions from #998 were "How do these [fields] work together?", and I want to ensure that remains in focus here.

Okay, I can expand on "how to populate the ECS fields".

I'll see what I can come up with for a general solution (e.g. users mapping their own sources), but implementations might end up being technology specific, e.g. how you would populate them in using the built in TraceContext support in .NET would be very different than if using the Elastic APM agent in Python, etc.

github-actions · 2022-02-24T00:18:31Z

This PR is stale because it has been open for 60 days with no activity.

bmorelli25 · 2022-02-28T22:46:33Z

Closing this and moving documentation to the APM Guide. Tracking in elastic/observability-docs#817.

sgryphon added 5 commits November 17, 2020 08:26

Add longer description of tracing

9d09f6e

Additional usage doc for a longer explanation of trace.id and span.id…

63f44fd

…, and how they relate to each other.

Add change to CHANGELOG

ea83d70

Additional links to the APM docs.

301dec7

Update changelog with ID of pull request (after creating it)

f1a21ba

ebeahan added the ready Issues we'd like to address in the future. label Nov 17, 2020

webmat added the 1.9.0 label Nov 17, 2020

sgryphon added 2 commits November 18, 2020 17:57

Add transaction as an alternative for span

2b27a9d

Looks like make check wants the generated files to be checked in

a9f043a

webmat added 1.7.0 1.8.0 needs_backport and removed 1.9.0 labels Nov 18, 2020

sgryphon added 3 commits November 19, 2020 07:47

Add note for the source of the diagrams.

5e118ff

For Elastic APM (rather than W3C Trace Context), parent could be a tr…

d08d58d

…ansaction

Merge commit '634c41931b857e9cc09d88eb9ad469c8e0f4a731'

fd0f9ef

webmat requested review from axw and webmat November 24, 2020 19:12

axw reviewed Nov 25, 2020

View reviewed changes

docs/usage/tracing.asciidoc Outdated Show resolved Hide resolved

docs/usage/tracing.asciidoc Outdated Show resolved Hide resolved

schemas/tracing.yml Outdated Show resolved Hide resolved

sgryphon added 6 commits January 21, 2021 18:36

Merge commit 'ab0c8baf3934baa4f15b907912c392638c85c024'

afbfc79

Conflicts: CHANGELOG.next.md docs/field-details.asciidoc experimental/generated/beats/fields.ecs.yml generated/beats/fields.ecs.yml schemas/tracing.yml

Auto generate after merge

6359912

Code review feedback - define trace in terms of the operations it des…

d86d1cd

…cribes (rather than messages)

Code review feedback, clarify spans are within a transaction.

f003a6f

Code review feedback; align better with APM, modify diagrams to indic…

07af653

…ate transaction spans, link to APM transactions.

Autogenerated output

15b2ca2

axw previously approved these changes Jan 25, 2021

View reviewed changes

bmorelli25 requested changes Jan 25, 2021

View reviewed changes

ebeahan mentioned this pull request Feb 1, 2021

Lack of clarity on how the trace fields are supposed to be used #998

Open

Update docs/usage/tracing.asciidoc

4dabf48

Co-authored-by: Brandon Morelli <[email protected]>

sgryphon dismissed axw’s stale review via 4dabf48 February 3, 2021 00:46

sgryphon and others added 8 commits February 2, 2021 16:46

Update docs/usage/tracing.asciidoc

65deac8

Nice pick up. Yes, it should definitely be an em dash! Co-authored-by: Brandon Morelli <[email protected]>

Update docs/usage/tracing.asciidoc

26c36f6

Co-authored-by: Brandon Morelli <[email protected]>

Update docs/usage/tracing.asciidoc

e132d3c

Co-authored-by: Brandon Morelli <[email protected]>

Update docs/usage/tracing.asciidoc

10461cf

Co-authored-by: Brandon Morelli <[email protected]>

Update docs/usage/tracing.asciidoc

e2db321

Co-authored-by: Brandon Morelli <[email protected]>

Update docs/usage/tracing.asciidoc

9ed5a8b

Co-authored-by: Brandon Morelli <[email protected]>

Update docs/usage/tracing.asciidoc

a5b16a0

Co-authored-by: Brandon Morelli <[email protected]>

Update docs/usage/tracing.asciidoc

74baf78

Co-authored-by: Brandon Morelli <[email protected]>

ebeahan removed 1.7.0 1.8.0 labels Feb 16, 2021

bmorelli25 mentioned this pull request Mar 11, 2021

[docs] What's a trace? elastic/observability-docs#436

Closed

ebeahan removed the needs_backport label Mar 29, 2021

github-actions bot added the stale Stale issues and pull requests label Feb 24, 2022

bmorelli25 closed this Feb 28, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expanded documentation for tracing fields #1128

Expanded documentation for tracing fields #1128

sgryphon commented Nov 17, 2020 •

edited by webmat

Loading

sgryphon commented Nov 18, 2020

webmat commented Nov 18, 2020

webmat commented Nov 18, 2020

webmat commented Nov 18, 2020

webmat commented Nov 24, 2020

axw left a comment

sgryphon commented Jan 25, 2021

axw left a comment

bmorelli25 commented Jan 25, 2021 •

edited

Loading

bmorelli25 left a comment

bmorelli25 Jan 25, 2021

bmorelli25 commented Jan 26, 2021 •

edited

Loading

ebeahan commented Feb 1, 2021

sgryphon commented Feb 3, 2021

sgryphon commented Feb 3, 2021

github-actions bot commented Feb 24, 2022

bmorelli25 commented Feb 28, 2022

Expanded documentation for tracing fields #1128

Expanded documentation for tracing fields #1128

Conversation

sgryphon commented Nov 17, 2020 • edited by webmat Loading

sgryphon commented Nov 18, 2020

webmat commented Nov 18, 2020

webmat commented Nov 18, 2020

webmat commented Nov 18, 2020

webmat commented Nov 24, 2020

axw left a comment

Choose a reason for hiding this comment

sgryphon commented Jan 25, 2021

axw left a comment

Choose a reason for hiding this comment

bmorelli25 commented Jan 25, 2021 • edited Loading

bmorelli25 left a comment

Choose a reason for hiding this comment

bmorelli25 Jan 25, 2021

Choose a reason for hiding this comment

bmorelli25 commented Jan 26, 2021 • edited Loading

ebeahan commented Feb 1, 2021

sgryphon commented Feb 3, 2021

sgryphon commented Feb 3, 2021

github-actions bot commented Feb 24, 2022

bmorelli25 commented Feb 28, 2022

sgryphon commented Nov 17, 2020 •

edited by webmat

Loading

bmorelli25 commented Jan 25, 2021 •

edited

Loading

bmorelli25 commented Jan 26, 2021 •

edited

Loading