docs: Update the quick start guide #930
Conversation
arielvalentin
requested review from
dazuma,
ericmustin,
mwear and
robertlaurin
as code owners
|
👋🏼 @open-telemetry/ruby-approvers I marked all conversations resolved since I reworked the majority of the structure since creating the initial draft. Hope that is OK. |
| Auto-instrumentation is the easiest way to get started with instrumenting your code, but in order to get the most insight into your system, you should add manual instrumentation where appropriate. | ||
| To do this, use the OpenTelemetry SDK to access the currently executing span and add attributes to it, and/or to create new spans. | ||
|
|
||
| To add manual instrumentation, you need to add the OpenTelemetry SDK gem to your Gemfile: |
There was a problem hiding this comment.
With the reference to auto-instrumentation here, would it be reasonable to assume the reader has arrived here after setting up their project with the gem dependencies required for auto-instrumentation? If so, they should have the SDK included already and this could be a statement "confirm that you've got opentelemetry-ruby installed" linking to those other steps. If we ought not to assume here that auto-instrumentation is already configured, this section might need more detail about configuring for only manual spans.
There was a problem hiding this comment.
Gotcha. Removed those from the doc.
| ```bash | ||
| $> git clone git@github.com:open-telemetry/opentelemetry-ruby.git; \ | ||
| cd open-telemetry-ruby/examples/otel-collector; \ | ||
| docker-compose up -d |
There was a problem hiding this comment.
I'll test this out this weekend.
There was a problem hiding this comment.
You will have to switch to this branch in order for that to work.
website_docs/context_propagation.md
Outdated
| You will also have to add a gem dependency: | ||
|
|
||
| ```sh | ||
| gem install opentelemetry-propagator-b3 |
There was a problem hiding this comment.
At this point in the Ruby ecosystem, could we assume that most people are using Bundler and Gemfiles? Can we streamline the setup instructions a bit with only the "add gem to Gemfile and bundle install" path and assume that people who are not using Bundler know to do a gem install instead? My impression is that most people new to Ruby are learning the Bundler Way and gem install is a choice made by more experienced folks, but my impression could certainly be mistaken!
There was a problem hiding this comment.
I agree with you. Let's see what others have to say about it.
There was a problem hiding this comment.
I'm +1 on preferring bundler instructions rather than gem instructions.
|
|
||
| ## Adding Manual Instrumentation | ||
|
|
||
| Auto-instrumentation is the easiest way to get started with instrumenting your code, but in order to get the most insight into your system, you should add manual instrumentation where appropriate. |
There was a problem hiding this comment.
I've been experimenting with phrasing manual instrumentation added to auto-instrumentation as "enriching auto-instrumentation" to distinguish the use case from "I want only my bespoke artisanal manual spans." My hypothesis is that identifying which of those two use cases a reader thinks may apply to them routes them down a setup path that pays off for them sooner than the other. My further guess is that auto-inst-with-manual-enrichment is the happier path for most users. If this seems like a promising perspective, maybe there are some tweaks we can make to this page to help readers down one of the two paths?
There was a problem hiding this comment.
Perhaps we could create a separate section that describe use cases and patterns or we could set aside time to co-author our book series "Head First OpenTelemetry", "OpenTelemetry in Action", and "OpenTelemetry the Hard Way".
There was a problem hiding this comment.
I did make a few changes. Let me know if it flows a little better.
See #775 Co-authored-by: Robb Kidd <robbkidd@honeycomb.io>
|
ping @open-telemetry/ruby-approvers @open-telemetry/ruby-maintainers |
|
ping @open-telemetry/ruby-approvers @open-telemetry/ruby-maintainers |
Co-authored-by: Francis Bogsanyi <francis.bogsanyi@shopify.com>
Co-authored-by: Francis Bogsanyi <francis.bogsanyi@shopify.com>
Co-authored-by: Francis Bogsanyi <francis.bogsanyi@shopify.com>
Co-authored-by: Francis Bogsanyi <francis.bogsanyi@shopify.com>
Co-authored-by: Francis Bogsanyi <francis.bogsanyi@shopify.com>
This PR adds some initial documentation for a quick start guide composed of content from from the following sources:
This is not intended to be a comprehensive guide and is an initial attempt to provide developers the ability to getting started with OpenTelemetry Ruby.