Skip to content

Adds advice about bounding spans #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 9, 2016
Merged

Adds advice about bounding spans #35

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions pages/instrumenting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,12 +58,31 @@ information about the RPC. For instance when calling an HTTP service, providing
the URI of the call will help with later analysis of requests coming into the
service.

The primary use case of binary annotations is exact match search. That said, it is
Copy link

@yurishkuro yurishkuro Sep 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't think this is accurate statement. I would even say the opposite, the majority of binary annotations are never used for search, they are used to add contextual data to the span.

Copy link
Member Author

@codefromthecrypt codefromthecrypt Sep 12, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will reword this, though I wouldn't go so far as to say it is opposite even
if in your practice search isnt used.

On 12 Sep 2016 00:40, "Yuri Shkuro" notifications@github.com wrote:

In pages/instrumenting.md
#35 (comment)
:

@@ -58,12 +58,31 @@ information about the RPC. For instance when calling an HTTP service, providing
the URI of the call will help with later analysis of requests coming into the
service.

+The primary use case of binary annotations is exact match search. That said, it is

don't think this is accurate statement. I would even say the opposite, the
majority of binary annotations are never used for search, they are used to
add contextual data to the span.

—
You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
https://github.com/openzipkin/openzipkin.github.io/pull/35/files/eeb91ad188ac5257ec2123b9cf557674c74f3d7c#r78298213,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAD610FzBG_JGFGAQ42rhneJYKrnqyb9ks5qpC8NgaJpZM4IrHCO
.

common to have binary annotations for uncontrolled values, such as exception messages.

**Endpoint**
Annotations and binary annotations have an endpoint associated with them. With two
exceptions, this endpoint is associated with the traced process. For example, the
service name drop-down in the Zipkin UI corresponds with Annotation.endpoint.serviceName
or BinaryAnnotation.endpoint.serviceName. For the sake of usability, the cardinality
of Endpoint.serviceName should be bounded. For example, it shouldn't include variables
or random numbers.


**Span**

A set of Annotations and BinaryAnnotations that correspond to a particular RPC.
Spans contain identifying information such as traceId, spandId, parentId, and
RPC name.

Spans are usually small. For example, the serialized form is often measured in
Copy link

@virtuald virtuald Jun 1, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about "spans are expected to be typically small" instead?

Copy link
Member Author

@codefromthecrypt codefromthecrypt Jun 1, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or maybe "Zipkin's design assumes spans are small (orders of kilobytes or less)"

ps @mosesn this is a fair statement?

Main idea I'm trying to relay is that being space efficient was a constant in a lot of Zipkin's design, ex how ip addresses are serialized into numbers, how finagle's tracer only picks a couple fields so that it ends up with quite small (hundreds of byte) spans, etc. If higher orders (like MiB) were intended, people wouldn't mess with things like this.

Copy link

@mosesn mosesn Jun 1, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think that's right. Even with all of these optimizations, the write throughput is often enormous.

KiB or less. When spans grow beyond orders of KiB, other problems occur, such as
hitting limits like Kafka message size (1MiB). Even if you can raise message
limits, large spans will increase the cost and decrease the usability of the
tracing system. For this reason, be conscious to store data that helps explain
latency, and don't store data that doesn't.
Copy link

@yurishkuro yurishkuro Sep 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would s/latency/system behavior/ - latency is not the only use case of tracing.

Copy link
Member Author

@codefromthecrypt codefromthecrypt Sep 12, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will do

On 12 Sep 2016 00:43, "Yuri Shkuro" notifications@github.com wrote:

In pages/instrumenting.md
#35 (comment)
:

Span

A set of Annotations and BinaryAnnotations that correspond to a particular RPC.
Spans contain identifying information such as traceId, spandId, parentId, and
RPC name.

+Spans are usually small. For example, the serialized form is often measured in
+KiB or less. When spans grow beyond orders of KiB, other problems occur, such as
+hitting limits like Kafka message size (1MiB). Even if you can raise message
+limits, large spans will increase the cost and decrease the usability of the
+tracing system. For this reason, be conscious to store data that helps explain
+latency, and don't store data that doesn't.

I would s/latency/system behavior/ - latency is not the only use case of
tracing.

—
You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
https://github.com/openzipkin/openzipkin.github.io/pull/35/files/eeb91ad188ac5257ec2123b9cf557674c74f3d7c#r78298285,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAD610JBD3mrYPGLBwFkX1Rurz8nR8QGks5qpC-ugaJpZM4IrHCO
.


**Trace**

A set of spans that share a single root span. Traces are built by collecting all
Expand Down