Getting Started guides for OT supported languages

[yurishkuro]

I think we need a few simple "code labs" in each popular language that we could also use in the workshops at conferences, i.e.

• hello world one-span example
• traced function example
• traced async function
• traced inbound or outbound http request (e.g. to google.com)
• traced server-server example

There are two ways of doing them, either as a series of dirs each containing a complete project with a single lesson, or as a "slide show" code lab that walks through code snippets (and possibly screenshots of results) but does not give a complete source code.

[tedsuo]

I have one of these that is pretty straight forwards. Written for golang, then ported by @carlosalberto to java:

Go version: https://github.com/tedsuo/ot-walkthrough-go Java version: https://github.com/carlosalberto/ot-walkthrough-java

However, they are not quite as simplified as what you are describing, and don't cover all of the various "tracing patterns" which I think is what you want.

[yurishkuro]

@tedsuo your walkthroughs are useful too, just for different purpose. They are more like introductions into tracing, where you run a pre-made app and inspect the traces, with minimal introduction into OpenTracing API itself (very similar to the HotROD demo).

[tedsuo]

Yes, I think you want something more like a patterns library or "The OpenTracing Cookbook" that helps teach people how to instrument applications, libraries, and execution frameworks.

[pavolloffay]

@yurishkuro your proposal makes a lot of sense to me. I have a question about the last two use cases.

traced inbound or outbound http request (e.g. to google.com) traced server-server example

Do you want to actually wrap http request into one span or actually instrument http client using interceptor? When thinking about this we could just wrap it and explain that basically, the same thing would happen in interceptor.

[pavolloffay]

Do we want to put it here or to contrib? I would vote maybe for this org. What about the structure? One repo for language or all in one?

[yurishkuro]

Do you want to actually wrap http request into one span or actually instrument http client using interceptor?

The point of the guides is to illustrate how something can be done manually, to actually show the mechanics of the wire propagation using OT. It can point out, once a manual instrumentation is done, that repeating it for all endpoints is not DRY and some sort of middleware or interceptor is more appropriate, and hey, look at that, these interceptors are actually already implemented in opentracing-contrib.

Do we want to put it here or to contrib? I would vote maybe for this org. What about the structure? One repo for language or all in one?

It is debatable what the best format is. I was thinking of these guides as code labs, or documentation that is not actually executable, the user needs to copy / type the code to get a working example. The downside of that is the guides might get stale w.r.t. the API changes, while the actual examples can be compiled / tested. So making real runnable projects / examples is also an option.

As for location, I think it's fine to put them in this org, one repo per language, e.g. java-tutorial.

[pritianka-zz]

I am so glad this idea is moving forward! I'd love to support codelabs in the following ways:

1. Alpha tester - A friend and I are learning Golang together. She is actually a systems engineer from Goldman Sachs. We can test the labs and share how helpful it is for different types of beginners.

2. Promotion - I think if we have more than 2 languages worth of codelabs, we should do an awareness push around them with some blog posts and meetup talks. I would love to set up a plan that executes in August or October (have a crazy month in September).

Best, Priyanka ᐧ

Priyanka Sharma Advisor, HeavyBit http://heavybit.com/ Head of Marketing & Partnerships, LightStep http://lightstep.com/ Co-founder, WakaTime http://www.wakatime.com/ - Quantify your coding www.twitter.com/pritianka 650-796-7125

I'm speaking at OSCON | May 8-11, 2017 http://oreil.ly/2jboNPo http://oreil.ly/2jboNPo #OSCON

On Wed, Jun 14, 2017 at 10:25 AM, Yuri Shkuro notifications@github.com wrote:

Do you want to actually wrap http request into one span or actually instrument http client using interceptor?

The point of the guides is to illustrate how something can be done manually, to actually show the mechanics of the wire propagation using OT. It can point out, once a manual instrumentation is done, that repeating it for all endpoints is not DRY and some sort of middleware or interceptor is more appropriate, and hey, look at that, these interceptors are actually already implemented in opentracing-contrib.

Do we want to put it here or to contrib? I would vote maybe for this org. What about the structure? One repo for language or all in one?

It is debatable what the best format is. I was thinking of these guides as code labs, or documentation that is not actually executable, the user needs to copy / type the code to get a working example. The downside of that is the guides might get stale w.r.t. the API changes, while the actual examples can be compiled / tested. So making real runnable projects / examples is also an option.

As for location, I think it's fine to put them in this org, one repo per language, e.g. java-tutorial.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/opentracing/specification/issues/73#issuecomment-308501363, or mute the thread https://github.com/notifications/unsubscribe-auth/ACTTmAXbGxcVEoIkmSP4iwmCYDLgnu7xks5sEBeCgaJpZM4Nq-VX .

[pavolloffay]

I like more executable examples due to reasons you mentioned. We could also make it easy to configure them with a real tracer e.g. one point it code and all examples in given repo would pick that tracer.

About the name:

1. ${lang}-code-samples
2. ${lang}-tutorial
3. ${lang}-examples

I the most I like 1.

[yurishkuro]

The main thing to me is for the projects to be very flat and small. Ie not a separate maven project fort each use case, just separate Example{#}.java files in one project.

Naming - 1 or 2.

[yurishkuro]

I am taking a stab at this, to get something ready for Velocity NYC.

cc @bryanl

[yurishkuro]

Finished Go, Java, and Python tutorials - https://github.com/yurishkuro/opentracing-tutorial

[objectiser]

@yurishkuro Only had a quick scan of the java tutorial but the structure works well - minor point, lesson 3 refers to client/hello.go - and the subsection header Take it For 's' Span instead of 'a'.

Good job!