Add a page illustrating common instrumentation use cases #34

yurishkuro · 2016-01-22T21:41:56Z

No description provided.

dkuebric · 2016-01-22T21:51:24Z

use-cases.md

+
+  1. Attempt to deserialize Trace Context from the incoming request, in case the trace has already been started by the client.
+  1. Depending on the outcome, either start a new trace, or join the existing trace using deserialized Trace Context. This operation starts a new Span.
+  1. Store the newly created span in some _request context_ that is propagated throughout the application, either by application code, or by the RPC framework.


Might be worth adding "4. Finally, close the trace using span.finish() when the server has finished processing the request"

@dankosaur good catch, updated.

dkuebric · 2016-01-22T22:00:33Z

use-cases.md

+    )
+```
+
+Here we set both arguments of the decoding method to the `headers` map. The Tracer object will have the knowledge which headers it needs to read in order to reconstruct Trace Context, which is comprised of a trace context ID and trace attributes.


I was reminded that with custom attributes we have the potential for naming collision with common HTTP headers -- do you think this is worth adding a note about in spec.md?

the way it's been implemented in a few places so far is that the custom attributes are prefixed by some string specific to the tracer. For example, our internal tracer serializes id into Uber-Trace-Id and attributes into UberCtx-***.

But it's definitely worth making explicit somewhere. I would prefer it to be in the docstring of the actual interface classes that people will implement, rather than in semantic documentation.

nit: "The Tracer object will have the knowledge which headers it needs to read ..." -> "The Tracer object knows which headers it needs to read ..."

micronit / common English bug: when people write "is comprised of", they almost always mean "comprises". So, "... Trace Context, which comprises a trace context ID and trace attributes."

http://public.wsu.edu/~brians/errors/comprised.html

❤️ the reference :-)

dkuebric · 2016-01-22T22:04:43Z

This is very clear and helpful @yurishkuro

dkuebric · 2016-01-22T22:07:01Z

use-cases.md

+
+### Logging Events
+
+We have already used `log_event_with_payload` in the client span use case. Events can be logged without a payload, and not just where the span is being created / finished. For example, the application may record a cache miss event in the middle of execution, as long as it can get access to the current span from request context:


add ~ "These events also have a timestamp associated with them, which distinguishes them from a tag applying to the entire span." ?

done, and I also added a whole use case (unsupported atm) about recording externally captured timestamps.

where's the example of recording externally captured timestamps?

bhs · 2016-01-23T00:02:21Z

public/js/toc.js

@@ -0,0 +1,89 @@
+// https://github.com/ghiculescu/jekyll-table-of-contents
+(function($){


why doesn't this use opentracing-javascript?! :)

bhs · 2016-01-23T00:13:58Z

I decided midstream that nitpicking at a minute level was probably annoying and certainly not a good use of your time! So I will stop.

The only substantial request I'd have is that we include – probably at the top – a totally utterly vanilla span that just starts with an operation name and stops within the same function scope. And maybe a second example where we create a child span in-process, also totally vanilla.

yurishkuro · 2016-01-23T00:34:26Z

I don't mind nit-picking, but it will probably be less work for you, after I merge this, to do another commit by simply changing the wording.

I will add a vanilla span example, but I didn't what were the two things you mentioned, how are they different?

Vanilla example:

    def my_function():
        span = get_current_span().start_child('my-function') if get_current_span() else None
        try:
            . . . # business logic
        finally:
            if span:
                span.finish()

bhs · 2016-01-23T00:40:46Z

I guess I was imagining – just for the sake of starting simple – something like

def my_top_level_function():
    trivial_span = tracer.start_trace("top-level-function")
    try:
        . . .
    finally:
        trivial_span.finish()

Then of course things can get more complex from there.

yurishkuro · 2016-01-23T01:00:07Z

@bensigelman comments addressed

bhs · 2016-01-23T01:01:14Z

great, LGTM, thanks! And agreed, if anyone cares I can take a pass at make my Composition professor happy with some silly line-edits as a separate PR. (Or not :)

Add a page illustrating common instrumentation use cases

michaelsembwever · 2016-01-23T06:47:31Z

use-cases.md

+        if parent_span is None:
+            span = tracer.start_trace(operation_name=operation)
+        else:
+            span = parent_span.start_child(operation_name=operation)


I believe the API can do this as a one-liner.
The parent_span also has a SpanContext, using that we can use a simplified method along the lines of

Span Tracer.startTrace(String operation, @Nullable SpanContext cxt);

This also co-incidentally removes the need for span.start_child(..) which i've already advocated for.

Also +1 to combining start_trace and start_child

codefromthecrypt · 2016-01-24T08:56:18Z

use-cases.md

+    span.set_tag('http.url', request.full_url)
+```
+
+The `operation` above refers to the name the server wants to give to the Span. For example, if the HTTP request was a POST against `/save_user/123`, the operation name can be set to `post:/save_user/`. OpenTracing API does not dictate how application calls the spans.


codefromthecrypt · 2016-01-24T09:12:58Z

use-cases.md

+            span = tracer.start_trace(operation_name=operation)
+        else:
+            span = parent_span.start_child(operation_name=operation)
+        span.set_tag('server.http.url', request.full_url)


ugh.. s/server.http.url/http.url/ please I understand why you are saying this, but ex in zipkin if there's actually an clash, it is tagged with an endpoint which compensates. On single-endpoint spans, this won't clash. This is likely to be read by people and I'd hate to make them stop and think about this part too much, or worse use it.

Per discussion in opentracing/opentracing.io#34 and opentracing/opentracing-java#7

Add a page illustrating common instrumentation use cases

40662b4

dkuebric reviewed Jan 22, 2016
View reviewed changes

Add step 4 for server flow

3553e67

dkuebric reviewed Jan 22, 2016
View reviewed changes

Add use case for externally captured timestamps

6945fd9

yurishkuro mentioned this pull request Jan 22, 2016

In discrete steps, Simplify the API opentracing/opentracing-java#7

Closed

bhs reviewed Jan 23, 2016
View reviewed changes

Add example of tracing a single function

d23c743

yurishkuro added a commit that referenced this pull request Jan 23, 2016

Merge pull request #34 from opentracing/use-cases

0827d9c

Add a page illustrating common instrumentation use cases

yurishkuro merged commit 0827d9c into master Jan 23, 2016

michaelsembwever reviewed Jan 23, 2016
View reviewed changes

michaelsembwever mentioned this pull request Jan 24, 2016

RFC: far fewer types (but comparable portability) opentracing/opentracing-go#40

Merged

codefromthecrypt reviewed Jan 24, 2016
View reviewed changes

codefromthecrypt deleted the use-cases branch January 24, 2016 16:58

dkuebric added a commit to dkuebric/opentracing-python that referenced this pull request Jan 26, 2016

Merge Tracer.join trace into Tracer.start_trace

1cb7097

Per discussion in opentracing/opentracing.io#34 and opentracing/opentracing-java#7

dkuebric mentioned this pull request Jan 26, 2016

Merge Tracer.join_trace into Tracer.start_trace opentracing/opentracing-python#13

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a page illustrating common instrumentation use cases #34

Add a page illustrating common instrumentation use cases #34

yurishkuro commented Jan 22, 2016

dkuebric Jan 22, 2016

yurishkuro Jan 22, 2016

dkuebric Jan 22, 2016

yurishkuro Jan 22, 2016

bhs Jan 23, 2016

bhs Jan 23, 2016

yurishkuro Jan 23, 2016

dkuebric commented Jan 22, 2016

dkuebric Jan 22, 2016

yurishkuro Jan 22, 2016

michaelsembwever Jan 23, 2016

bhs Jan 23, 2016

bhs commented Jan 23, 2016

yurishkuro commented Jan 23, 2016

bhs commented Jan 23, 2016

yurishkuro commented Jan 23, 2016

bhs commented Jan 23, 2016

michaelsembwever Jan 23, 2016

codefromthecrypt Jan 24, 2016

bcronin Jan 24, 2016

codefromthecrypt Jan 24, 2016

codefromthecrypt Jan 24, 2016


		### Logging Events

		We have already used `log_event_with_payload` in the client span use case. Events can be logged without a payload, and not just where the span is being created / finished. For example, the application may record a cache miss event in the middle of execution, as long as it can get access to the current span from request context:

		@@ -0,0 +1,89 @@
		// https://github.com/ghiculescu/jekyll-table-of-contents
		(function($){

Add a page illustrating common instrumentation use cases #34

Add a page illustrating common instrumentation use cases #34

Conversation

yurishkuro commented Jan 22, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dkuebric commented Jan 22, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bhs commented Jan 23, 2016

yurishkuro commented Jan 23, 2016

bhs commented Jan 23, 2016

yurishkuro commented Jan 23, 2016

bhs commented Jan 23, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment