Opentelemetry-go: Add a "Quickstart" guide

[MrAlias]

The Java SIG has an instructive and helpful set of documentation that provides relevant details for things like creating instrumentation and setting up the telemetry pipelines: https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md

We should create something similar.

[austinlparker]

Hi! Friendly neighborhood Comms SIG is here with a PR that adds some quickstart documentation for Go to the OpenTelemetry website. If someone would be so kind as to put some eyes on it, we'd love for this to be a starting point for future docs!

Note that this doesn't necessarily replace documentation that you wish to have in your repository or on pkg.go.dev, it's meant to be a high-level overview that website visitors can refer to initially.

Please see the PR here -> https://github.com/open-telemetry/opentelemetry.io/pull/311

[johananl]

Thanks @austinlparker! We'll definitely take a look.

@MrAlias - happy to take this issue.

[johananl]

@MrAlias given that we already have https://opentelemetry.io/docs/go/getting-started/, what should be the relationship between the guide on the website and this guide we're adding to the repo?

Assuming we do want two separate guides, I have the following questions:

• Shall we cover both tracing and metrics?
• Which exporter(s) shall we use? IMO looking at things via e.g. Jaeger or Grafana is a lot nicer than stdout or querying a metrics endpoint manually.

[MrAlias]

@austinlparker those are some excellent docs!

@johananl I'm hesitant to create additional documentation after seeing the quality of those linked docs. Having a single place for a "getting started" set of documentation is probably a good place to start and will avoid drift and increased maintenance burden.

I think we should update this issue to instead update those linked docs and link them in our README and go docs.

I would like to:

1. Pin the examples in the docs to a specific version of this project (i.e. in the go get command specify it with versions)
2. Ensure all the code examples in the getting started are functional. They currently reflect the old release and are not accurate. We should have actual go examples that contain the code snippets in the documentation. Those examples should contain a comment at the top stating that any change to the example needs to be propagated to the documentation. Though it isn't automated, it will ensure our users have buildable examples.
3. Update our README and main otel package documentation to link to the getting started.
4. Possibly extend the documentation to use Jaeger or Grafana like you pointed out.

@Aneurysm9 thoughts?

[austinlparker]

Just as a small note, there's a section designed to cover export to Jaeger/whatever (https://opentelemetry.io/docs/go/exporting_data/) in the docs templates, so you could fill that out for whatever preferred exporter you have. In the absolute 'getting started' stuff I felt like keeping it limited to console export was easier, just to reduce the amount of boilerplate.

You can, of course, add more documentation beyond what's suggested there.