"Instrumenting a library" is misleading (at least me)

[guettli]

I think the title "Instrumenting a library" is misleading.

I refer to this page: http://zipkin.io/pages/instrumenting.html

I guess the meaning of the title is "Creating a new instrumenting library".

Background: I had the idea of tracing the internals of a library (single process, single thread, not RPC) ... I would call this "Instrumenting a library" :-)

[codefromthecrypt]

Along this note, it does seem we need two different or maybe three sections.

• users of existing trace instrumentation generally have fewer things to answer.. ex what are usual default span names and tags, and what guidelines are there for custom ones
• developers of trace instrumentation need to know the general practice of using a tracer, ex. propagation, making sure default tags are in place, not making spans too big or without service name (this is mostly our existing doc)
• developers of tracers need to know encoding, propagation formats, the model, async reporting etc

we've had some questions come up which hints that the first point above could help others..

@triks80

Can someone help with a guideline on best practices for using Zipkin? Tags, naming spans etc., I feel like I am using this product without a manual and groping for things in the dark.

[codefromthecrypt]

here are some notes about the questions asked

on span naming the main concern is that the names are low cardinality (they don't repeat endlessly due to containing variables)
ex. that's why the http method is the default name in most zipkin http instrumentation (there's only several of these, and in the UI drop-down no problem)
good names are short and are useful grouping on their own. Ex. if I make one called "get /trace/" that would be ok, but "get /trace/1231234" would be bad as the latter would repeat for each id

on tagging, instrumentation usually have default tags already setup, like http.url these are documented here https://github.com/openzipkin/zipkin-api/blob/master/thrift/zipkinCore.thrift
user defined tags/binary annotations serve two purposes: exact match lookup for the search screen and details for the trace view (specifically the span detail screen)
so user-defined tags are sometimes things like an application-specific request id. you would add that so that you can search by this
possibly the user or the framework.. things like this
then, sometimes people add more verbose tags that aren't searchable. ex the parameters of an operation.
the current docs mention guidance which is to not load up tags with too much, as it will reduce the usability of the system (<1KiB is good)