docs: add highlight to js tracer examples

[chiawendt]

The removed code example is confusing because the acquired tracer is unused. Merging acquisition and usage makes examples more readable.

[theletterf]

This is a pretty big edit.

@open-telemetry/javascript-maintainers Could you have a look?

[maryliag]

the idea was to do a step by step, setting up things, etc, I'm not sure if the removal will cause confusion
can you clarify what part was confusing for you?
maybe one idea is to give more steps in between, having the example without instrumentation, then adding part of it, then using it, and so on

[chiawendt]

1. The original code example has too much irrelevant information. Its purpose is to demo acquiring the tracer, it has 20 lines, but only 1 line is actually acquiring the tracer. As an reader who know nothing about tracer, I need to read and think about each line carefully and find out that only 1 line is what I care about.

2. The code example acquire the tracer but does not use it. I see the tracer variable defined and searches for its usages in the following lines and found nothing, I got confused.

3. People have short and fragmented attention span. It helps to have a code example that includes both the tracer acquiring and tracer usage. Reader can read a single code example and learn the whole idea, instead of jumping between several code examples to get a complete picture.

[svrnm]

I see where you are coming from, but let me point out that at the top of that section we have a short version:

https://opentelemetry.io/docs/languages/js/instrumentation/#acquiring-a-tracer

import opentelemetry from '@opentelemetry/api';
//...

const tracer = opentelemetry.trace.getTracer(
  'instrumentation-scope-name',
  'instrumentation-scope-version',
);

// You can now use a 'tracer' to do tracing!

The part below you are referring to is for the "walk along tutorial", and people might just want to copy and paste that over.

A way to resolve that is that we use code highlights provided by hugo, so the lines that have been changed get easier to be seen:

https://gohugo.io/content-management/syntax-highlighting/#fenced-code-blocks

see the "hl_lines" option

[chiawendt]

I think even with the help of highlighting, the problem of high noise-to-signal is still not resolved. The "rolldice" logic below the tracer acquirement complex and does more distraction than clarifying. Maybe the culprit here is that the "rolldice" example is too complex? Also do we really need two files and two tracers to explain how to use a tracer? Can we keep it simple and focused, by using an one file example?

[svrnm]

I think even with the help of highlighting, the problem of high noise-to-signal is still not resolved. The "rolldice" logic below the tracer acquirement complex and does more distraction than clarifying. Maybe the culprit here is that the "rolldice" example is too complex? Also do we really need two files and two tracers to explain how to use a tracer? Can we keep it simple and focused, by using an one file example?

Having the 2 files is part of the the point we want to drive with the example, you have an "app" file that leverages the API and the SDK, and you have a "library" file that only depends on the "API", which means that if you for example develop a 3rd party library it should only take dependency on the API.

I understand that this is far from optimal, we can definitely reduce some of the overhead with highlighting lines or maybe even not showing the full files, or we can make that part of the docs visually distinct, but removing this portion is not an option.

[chiawendt]

Sounds good. I changed the PR to adding highlights.

[svrnm]

@open-telemetry/javascript-approvers PTAL!

[pichlermarc]

thanks!

[otelbot]

Thank you for your contribution @chiawendt! 🎉 We would like to hear from you about your experience contributing to OpenTelemetry by taking a few minutes to fill out this survey.