[HTRACE-324] Document tracer setup, the passing of traces across RPC,

• Type: Task
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Component/s: docs
• Assignee: Unassigned
• Reporter: Michael Stack
• Created: 09/Dec/15 18:48
• Updated: 10/Dec/15 00:14

Description

Doc why you should create a tracer always and create it early in your process. Then that you should start up a scope near immediately also so that your tracer context is available down the stack if anyone needs to pluck it from current thread context. Explain NPE when you do Tracer.curThreadTracer... and of how to fix and of how early setup allows you avoid this ugly idiom that requires null checks:

+    Tracer tracer = Tracer.curThreadTracer();
+    TraceScope scope = tracer == null? null:
+      tracer.newScope("MemStoreFluser.reclaimMemStoreMemory");
...

+    if (scope != null) scope.close();

Doc you should close tracer when done

Fix the current page because it has deprecated way of setting up a new Tracer using deprecated name method (this may be fixed already, we just haven't pushed it).