com.github.kristofa.brave

Class ServerTracer

java.lang.Object

com.github.kristofa.brave.AnnotationSubmitter

com.github.kristofa.brave.ServerTracer

public abstract class ServerTracer
extends AnnotationSubmitter

Used for setting up trace information for a request. When a request is received we typically do this:

1. Detect if we are part of existing trace/span. For example with services doing http requests this can be done by detecting and getting values of http header that reresent trace/span ids.
2. Once detected we submit state using one of 3 following methods depending on the state we are in: ServerTracer#setStateCurrentTrace(long, long, Long, String), {@link ServerTracer#setStateNoTracing()} or {@link ServerTracer#setStateUnknown(String)}.
3. Next we execute {@link ServerTracer#setServerReceived()} to mark the point in time at which we received the request.
4. Service request executes its logic...
5. Just before sending response we execute {@link ServerTracer#setServerSend()}.

Author:

kristof

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ServerTracer.Builder

Nested classes/interfaces inherited from class com.github.kristofa.brave.AnnotationSubmitter

AnnotationSubmitter.Clock

Method Summary

Modifier and Type	Method and Description
static ServerTracer.Builder	builder()
void	clearCurrentSpan() Clears current span.
void	setServerReceived() Sets server received event for current request.
void	setServerReceived(Endpoint client) Like setServerReceived(), except you can log the network context of the caller, for example an IP address from the X-Forwarded-For header.
void	setServerReceived(int ipv4, int port, String clientService) Deprecated. use setServerReceived(Endpoint)
void	setServerSend() Sets the server sent event for current thread.
void	setStateCurrentTrace(long traceId, long spanId, Long parentSpanId, String name) Sets the current Trace/Span state.
void	setStateNoTracing() Sets the current Trace/Span state.
void	setStateUnknown(String spanName) Sets the current Trace/Span state.

Methods inherited from class com.github.kristofa.brave.AnnotationSubmitter

create, submitAnnotation, submitAnnotation, submitBinaryAnnotation, submitBinaryAnnotation

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static ServerTracer.Builder builder()

clearCurrentSpan

public void clearCurrentSpan()

Clears current span.

setStateCurrentTrace

public void setStateCurrentTrace(long traceId,
                                 long spanId,
                                 @Nullable
                                 Long parentSpanId,
                                 @Nullable
                                 String name)

Sets the current Trace/Span state. Using this method indicates we are part of an existing trace/span.

Parameters:

traceId - Trace id.

spanId - Span id.

parentSpanId - Parent span id. Can be null.

name - Name should not be empty or null.

See Also:

setStateNoTracing(), setStateUnknown(String)

setStateNoTracing

public void setStateNoTracing()

Sets the current Trace/Span state. Using this method indicates that a parent request has decided that we should not trace the current request.

See Also:

setStateCurrentTrace(long, long, Long, String), setStateUnknown(String)

setStateUnknown

public void setStateUnknown(String spanName)

Sets the current Trace/Span state. Using this method indicates that we got no information about being part of an existing trace or about the fact that we should not trace the current request. In this case the ServerTracer will decide what to do.

Parameters:

spanName - The name of our current request/span.

setServerReceived

public void setServerReceived()

Sets server received event for current request. This should be done after setting state using one of 3 methods setStateCurrentTrace(long, long, Long, String) , setStateNoTracing() or setStateUnknown(String).

setServerReceived

public void setServerReceived(Endpoint client)

Like setServerReceived(), except you can log the network context of the caller, for example an IP address from the X-Forwarded-For header.

Parameters:

client - represents the client (peer). Set Endpoint.service_name to "unknown" if unknown.

setServerReceived

@Deprecated
public void setServerReceived(int ipv4,
                                          int port,
                                          @Nullable
                                          String clientService)

Deprecated. use setServerReceived(Endpoint)

Like setServerReceived(), except you can log the network context of the caller, for example an IP address from the X-Forwarded-For header.

Parameters:

ipv4 - ipv4 of the client as an int. Ex for 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4

port - port for client-side of the socket, or 0 if unknown

clientService - lowercase name of the callee service or null if unknown

setServerSend

public void setServerSend()

Sets the server sent event for current thread.