Package io.honeycomb.beeline.tracing

Class Beeline

java.lang.Object

io.honeycomb.beeline.tracing.Beeline

public class Beeline
extends Object

The Beeline class is the main/most-convenient point of interaction with traces in a Beeline-instrumented application. It allows user code to add contextual information to the currently active Span and to create new nested/child Spans. This is done by interacting with internal thread-local context. In essence, creating a child pushes onto a stack and closing the span pops it back off. Take care to always close the Spans you create to ensure correct measurements of duration and timely submission to Honeycomb.

Instrumentation

When using this class, it is assumed that your framework instrumentation would have initialized an initial "root" Span, alleviating the burden of having to manage low-level details. For example, the Spring Beeline creates a "root" span for all incoming HTTP requests and closes it when the request returns from user code.

However, access to the low level API is given via the delegates returned by getTracer() and getSpanBuilderFactory(). The Beeline class is essentially a façade to those delegates, narrowing and bundling lower-level APIs to target the most common use-cases.

Sampling

Sampling of traces and Spans can be done in two ways.

Firstly, the SpanBuilderFactory is configured with a "global" sampler (usually DeterministicTraceSampler that applies its sampling logic to a Span's traceId, and therefore will sample uniformly with a specific sample rate. In addition, if a trace is not sampled, "noop" spans that carry no data are generated tp minimise runtime overhead.

Secondly, the factory can be configure with a SpanPostProcessor that applies sampling just before a Span is submitted to Honeycomb. This allows sampling to be performed based on the contents of the Span. It does so only on Spans that have been sampled by the "global" sampler, because "noop" Spans carry no data.

For example, you might decide to sample Spans containing fields indicating error conditions at a high rate, and sample the "happy path" at a lower rate.

When the two sampling mechanisms are used together then the effective sample rate is a product of both. However, note that you do not have to use either of the sampling mechanisms and can always configure either one or both to "always sample" with a sampleRate of 1 (e.g. Sampling.alwaysSampler() does this).

Thread-safety

See Tracer's notes on thread-safety, as the same rules apply to this class.

Propagation to other threads

Because of the use of thread-local context you might find traces breaking as you execute code asynchronously.

See the Tracer's notes on propagation, which details how to use its API to propagate your traces to other threads.

Propagation to other processes

For example, the Spring Beeline automatically accepts traces by decoding the Honeycomb trace header. It also continues traces downstream when using Spring's RestTemplate.

If your framework instrumentation does not automatically propagate traces then you can use Propagation.honeycombHeaderV1() to encode/decode Honeycombs standard HTTP header. Once decoded, you can use the SpanBuilderFactory to create new instance and Tracer.startTrace(Span) to initialize the "root" Span.

Encoding takes a PropagationContext, which you can retrieve with Span.getTraceContext().

Constructor Summary

Constructors

Constructor	Description
Beeline(Tracer tracer, SpanBuilderFactory factory)

Method Summary

Modifier and Type	Method	Description
void	addField(String key, Object value)	Add a field to the active Span.
Span	getActiveSpan()	Returns the span that is currently active on this thread - the one that is top of the stack.
SpanBuilderFactory	getSpanBuilderFactory()
Tracer	getTracer()
Span	startChildSpan(String childSpanName)	Starts and returns a new span as the child of the previous span.
Span	startTrace(String spanName, PropagationContext parentContext, String serviceName)	A convenience method that starts a trace.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Beeline

public Beeline(Tracer tracer,
               SpanBuilderFactory factory)

Method Detail

getActiveSpan

public Span getActiveSpan()

Returns the span that is currently active on this thread - the one that is top of the stack.

Note, this method is null-safe - a "noop" span is returned if no trace is currently active. This may be due to the current execution not being instrumented or because the trace was not sampled.

Example

 if (underAttack) {
      final Span currentSpan = beeline.getActiveSpan()
           .addField("alert-message", "We are under attack!")
           .addField("alert-level", "red");
 }
 

Returns:

the active span.

startChildSpan

public Span startChildSpan(String childSpanName)

Starts and returns a new span as the child of the previous span.

This means the child becomes the new active span (see getActiveSpan() on this thread. The old active span (i.e the "parent span") is linked to the child via the Parent ID and via reference. When Span.close() closing the child} the parent will be reset to being the active span.

Because of the parent and child being linked by reference, the child's lifetime is tied and limited to that of the parent.

Example

 // try-with-resources statement automatically closes the span
 try (Span childSpan = beeline.startChildSpan("http-call")) {
      childSpan.addField("http-url", url);
      return httpClient.get(url);
 }
 

Parameters:

childSpanName - to use as the name of the new span - must not be empty.

Returns:

new child span.

Throws:

IllegalArgumentException - if the argument is null or empty.

addField

public void addField(String key,
                     Object value)

Add a field to the active Span.

The field key will be prefixed with "app." to make it part of the "app" namespace for user-added fields. This is to avoid clashes and distinguish it from standard fields provided by automatic instrumentations like the "Spring Beeline".

Example

 if (underAttack) {
      beeline.addField("alert-message", "We are under attack!");
 }
 

Parameters:

key - of the field.

value - of the field.

See Also:

getActiveSpan()

startTrace

public Span startTrace(String spanName,
                       PropagationContext parentContext,
                       String serviceName)

A convenience method that starts a trace.

Typically this would be invoked when a service receives an external request, but before the request is processed by the service. For example in an HTTP Servlet filter before javax.servlet.FilterChain#doFilter(ServletRequest, ServletResponse)} is invoked.

The parentContext contains information that is needed to continue traces across process boundaries, e.g. whether the external service making the request was also traced. If the external service was also traced, the span returned by this method will:

- share the same trace ID
- be the child of the span that represents the call to this service

The returned span is also accessible via getActiveSpan() because it becomes the current span.

Parameters:

spanName - the name of the span to create

parentContext - the parent context containing inter-process tracing information

serviceName - the name of the service using this method

Returns:

the new current span

See Also:

Tracer.startTrace(Span), for an existing solution for starting (and closing) traces for incoming requests to an HTTP server.

getTracer

public Tracer getTracer()

getSpanBuilderFactory

public SpanBuilderFactory getSpanBuilderFactory()