Adds diagram showing trace instrumentation's role in architecture

[codefromthecrypt]

Adds a sequence diagram that shows instrumentation do things in band and out-of-band

See #68

[codefromthecrypt]

@guettli does this help?

[guettli]

Looks much less boring than a sequence diagram .... on the other hand I like it boring. I like it boring since it is often a good, since most obvious, way.

[codefromthecrypt]

@guettli PTAL I hope this is more what you were looking for (also changed PR description)

[codefromthecrypt]

@openzipkin/core might want to take a look at this, too. The attempt here is to show the relationship of sorts of activity in scope of trace instrumentation. We've had plenty of requests to clarify this and probably does help to do so in the architecture pane vs requiring people to look at the instrumenting section.

IOTW, people simply using a zipkin system probably could do well to have a brief overview of the process.

thoughts?

[guettli]

@adriancole This sequence diagram is easy to understand. Looks good, thank you. BTW, how did you "paint" it? What tool did you use?

[shakuzen]

"after the application response" may also be accurate here, but I believe the diagram is trying to show the tracing of the HTTP call GET /foo being made by "Application". Maybe it would be less confusing/more accurate to say "after the HTTP call is completed."

[shakuzen]

To that end, maybe it is best to explicitly state in the previous line:

Here's an example sequence of http tracing where "Application" is making an http call to GET /foo that will be traced in a single span.

[codefromthecrypt]

good point.. above in the doc we do define the term Span.. good to reinforce

[codefromthecrypt]

did some rewording based on ideas from @shakuzen

Here's an example sequence of http tracing where user code calls the resource
/foo. This results in a single span, sent asynchronously to Zipkin after user
code receives the http response.

then clarifying below the diagram why

Trace instrumentation report spans asynchronously to prevent delays or failures
relating to the tracing system from delaying or breaking user code.

Not sure if this is too much info for this section, but maybe it is ok? I chose "user code" instead of application as I didn't want folks to misunderstand application as something not in the same process. If the choice makes things worse, let me know

[codefromthecrypt]

as we can edit at anytime (in fact anyone can raise a PR), merged as I think this was good progress

[codefromthecrypt]

@adriancole <https://github.com/adriancole> This sequence diagram is easy to understand. Looks good, thank you. BTW, how did you "paint" it? What tool did you use?

I used monodraw which I'm just now getting familiar with. it is pretty good and a bit better than what I used before. There's no built-in sequence diagram, I just drew lines and boxes and moved them around etc. Thanks for the feedback!

[guettli]

@adriancole off topic: I want to learn zipkin, I have question here at StackO: http://stackoverflow.com/questions/41508180/zipkin-for-profiling-traditional-progamm-one-process-one-thread if you have three minutes ...