Getting started: provide a uniform experience for Collector and all language SIGs

[chalin]

I think that each language SIG's Getting started page should use the equivalent of a "console exporter". Exporting to a backend should be covered elsewhere.

Thoughts @austinlparker @cartermp @theletterf

[chalin]

☝️

[cartermp]

Yep, agreed! I would also argue that every language section should have a dedicated page (or exporter section) that shows how to export to a backend, since it is important, just not for getting started.

The question in my mind is, what should the thing being instrumented cover? I can see two options:

1. An http server or something (think "hello world with express") that uses automatic instrumentation to track the inbound request, then creates at least 1 child span of that request's span, with the child/children tracking some distinct operation before a result is sent back as a response. Also demonstrates setting an attribute on a span.
2. A pure console app with no other dependencies that tracks some unit of work with a parent and child span. Also demonstrates setting an attribute on a span.

I lean a little more towards (1) since I believe incorporate automatic instrumentation is critically important and we should encourage using it as a first step so that you can get some easy wins by using OTel. However, it makes setup more complex, any sample app is a little harder to run, and in some cases (e.g., Java) requires running an agent in addition to the app.

[svrnm]

@chalin when you say "console collector" do you mean a console exporter or do you mean that there should be a collector receiving data via OTLP and the collector is then dumping the data to the console?

From an end-user experience I would argue that both would be great:

• Using the exporter is a quick win and it's easy to debug if anything goes wrong
• At the end, exporting with OTLP to a collector is recommended, so having a quick route to that as well is the next thing people will look for.

I think about the following flow

1. Do you have an application in already?
   a. Yes? great, you can use that one!
   b. No? ok, please use that "hello http server" as @cartermp suggested
2. Auto-instrument that service and use a console exporter to dump everything to the console. There are other exporters, go here to learn more
3. Exporters are good, collectors are great! Do you have a collector already?
   a. Yes? great, proceed
   b. No?, ok, go here and learn how to install one that dumps everything to the console
4. Reconfigure your service to use OTLP and point your data to the collector. Collector is now dumping everything to the console. There are other exporters for the collector, go here to learn more.

I am happy to help to make this happen / find people to help with that, please let me know if this make sense :)

[chalin]

@chalin when you say "console collector" do you mean a console exporter

Yes, thanks! I fixed that in the opening comment.

I think about the following flow

I like it! It seems smooth to me. Thoughts @tedsuo @cartermp @austinlparker?

[cartermp]

I do like that flow, yes.

[svrnm]

following up on this. I found some time to create a quick experiment for this at https://github.com/svrnm/opentelemetry.io/tree/multi_language_tutorial

The idea is to have the outlined sample webserver application in multiple languages. The key difference is, that all languages use the same text, and the end-user can pick the language that's relevant to them.

The big advantage is, that all text only needs to be written one (e.g. when describing what a span is, or that we are going to use a console exporter, etc.). This is inspired by https://www.rabbitmq.com/getstarted.html

Here's a quick video summary:

otel-multi-language-tutorial.mp4

If you'd like to play around with it, clone my fork&branch, run it and go to http://localhost:8888/docs/tutorial/hello_world/

What do you think?

[cartermp]

@svrnm I really like this a lot. I think this would be a great place to point newcomers. I do worry about the list of tabs getting too large, though. But maybe that's a thing to worry about at a later date 🙂

[svrnm]

I really like this a lot. I think this would be a great place to point newcomers.

Thanks. Newcomers would be the targeted audience: thinking about that for a little bit, I should have started with automatic instrumentation and not manual.

I do worry about the list of tabs getting too large, though. But maybe that's a thing to worry about at a later date 🙂

There might be alternatives like having the language controlled via the URL like the rabbitmq tutorial. The tabs have the advantage that someone who has multiple services in different languages can easily jump back and forth.

[chalin]

Finally getting back to this: @cartermp and @svrnm, I like your ideas, and have some points I'd like to discuss. If both of your are available, maybe we can discuss this at the next Comms meeting this week. WDYT?

[cartermp]

Sounds good to me

[svrnm]

Sounds good to me!

[svrnm]

Based on the conversation from the call last week, I follow up here on the flow I suggested a few weeks back. I'd like to add a premise to the whole "getting started guide", and get your opinion on it:

The personae that should follow this "Getting Started Guide" is someone who has an application in <language> using <list of frameworks> and know wants to see what insights they can get from adding OpenTelemetry into it. They know nothing about OpenTelemetry and are also not willing (yet) to learn a lot of technical concepts. All they are looking for is to see how quickly the can get value out of it (= seeing traces, logs, metrics in their backend of choice)

Next, to follow up on the "abstract-vs-details"-discussion: I think it is a good starting point to have a detailed set of instruction that is abstract(!) in the language used: this allows to approach the problem independent of implementation details, it might call out some improvements language-specific implementations can make and it starts with a common flow that can become specalized where needed.

Which brings us back to the flow:

Getting Started With OpenTelemetry (<language>)

Your Application

Do you have an application in <language> already, if so skip to the next chapter. If not copy the following simple "http server" in <language> using <framework>, install the dependencies and send some sample requests to it.

Adding OpenTelemetry to your service

For applications in <language> you can use <auto instrumentation package> to automatically instrument your application and your frameworks. Please install it & configuring it in the following way:

• use common package manager to install package & dependencies
• add some auto instrumentation code to your application source (not required for some languages)
• add what ever is needed to dump traces, logs, metrics to the console (ConsoleSpanExporter, etc.)

Run your application

Now run your application as normal, see how signals are dumped to the console.

Add a collector into the mix

Do you have a collector already? Great, skip to the next step. If not, here's a 20 word intro into what a collector is, here is how you install one that has a OTLP receiver and an exporter that dumps everything to the console

Use the OTLP exporter

Update your code / reconfigure opentelemetry to send data to the OTLP exporter.

Run your application (again)

Now run your application as normal, see how signals are dumped to the console by the exporter

Talk to a backend

You are almost there, all you need to do know is reconfigure your collector to talk to the backends(!) of your choice:

• Link to instructions for OSS Backend 1
• Link to instructions for OSS Backend 2
• ...
• Link to instructions for commercial Backend A
• Link to instructions for commercial Backend B

Summary & What's Next

You have successfully instrumented your application with OpenTelemetry. If you have multiple applications talking to each other, repeat the process with all other applications, and see how distributed tracing works.

If you have kubernetes, you can use the opentelemetry-operator to autoinstrument your services!

If you now want to learn more about OpenTelemetry, go to "Concepts"

[austinlparker]

The personae that should follow this "Getting Started Guide" is someone who has an application in <language> using <list of frameworks> and know wants to see what insights they can get from adding OpenTelemetry into it. They know nothing about OpenTelemetry and are also not willing (yet) to learn a lot of technical concepts. All they are looking for is to see how quickly the can get value out of it (= seeing traces, logs, metrics in their backend of choice)

☝🏼

This really captures the spirit of the 'getting started' pages. Historically we've set the bar for 'success' as "how quickly can I see a span/metric/log" but I don't think that really gets the value prop across.

A few misc notes --

• We should avoid adding instructions for proprietary/commercial tools. In my perfect world, vendors can link to this page and say "Ok, go through these instructions and come back at this point and we'll tell you how to export to Lightstep/Elastic/DD/Honeycomb/Whatever". I just don't want us to be in the business of trying to manage which vendor gets on here or doesn't, or what order they're presented in, or dealing with updates to their docs (or making more work for them to ensure that external docs are updated when they make changes on their end)
• For 'Running your application' steps, we should ensure that our sample service/deployment has some sort of command that can send requests to it (maybe a little curl script or whatever) so that we can ensure that users have a 'known good' set of output to target.
• Personally, I think it'd be great if we could have at least two or more services as part of our 'sample' app here, to illustrate propagation. Another option would be to have a single service with some sort of OSS middleware in front of it (envoy? idk) that can originate or propagate traces.

Thoughts?

[svrnm]

We should avoid adding instructions for proprietary/commercial tools.

Makes sense! What about replacing that link list with a search with the registry? or the /vendor page?

(maybe a little curl script or whatever)

Good point, if all of those sample apps are a "simple webserver" then they should be able to use the same curl sampleapp independent of language

illustrate propagation

I was thinking about, "go through the docs again with a different language and stitch them together", but as you suggested, being explicit would be better (here is a second sample app, talking to your first app, follow the instructions again, now you have a distributed trace (CC: @kyle-lt, reminds me of your otel-chain).
I also like the idea of adding some oss middleware like envoy (maybe in a third step?), to call out that they can also emit opentelemetry signals for you (could also be an apache (I had to mention this 😆 ))

[austinlparker]

I could sort of see something like this in terms of sequencing:

1. HTTP Server
2. HTTP Client
3. Middleware

Then having a GRPC version as well over time. That would cover the major RPC libraries that we support out of the gate.

[cartermp]

Makes sense! What about replacing that link list with a search with the registry? or the /vendor page?

@svrnm I sort of think it might be best to just let vendors handle this in their own docs for now. Some vendors support direct OTLP ingest and they make it no different from sending to a collector other than maybe needing to specify a header or two. Others might require you to pull in a contrib module to the collector, or use their distribution of a collector or an SDK, etc.

[svrnm]

Seems like this is redundant now, since a lot has changed and we have #2623 now