How to use

brave.internal.Nullable

constructor

/**
 * Sets the current span in scope until the returned object is closed. It is a programming error
 * to drop or never close the result. Using try-with-resources is preferred for this reason.
 *
 * @param currentSpan span to place into scope or null to clear the scope
 */
public abstract Scope newScope(@Nullable TraceContext currentSpan);

/**
 * The parent's {@link #spanId} or null if this the root span in a trace.
 *
 * @see #parentIdAsLong()
 */
@Nullable public final Long parentId() {
 return parentId != 0 ? parentId : null;
}

/**
 * The entire URL, including the scheme, host and query parameters if available or null if
 * unreadable.
 *
 * <p>Conventionally associated with the key "http.url"
 */
@Nullable public abstract String url(Req request);

/**
 * The HTTP status code or null if unreadable.
 *
 * <p>Conventionally associated with the key "http.status_code"
 *
 * @see #statusCodeAsInt(Object)
 */
@Nullable public abstract Integer statusCode(Resp response);

/**
 * Returns an overriding sampling decision for a new trace. Return null ignore the request and use
 * the {@link brave.sampler.Sampler trace ID sampler}.
 */
@Nullable public abstract <Req> Boolean trySample(HttpAdapter<Req, ?> adapter, Req request);

 /**
  * Customizes the span based on the response received from the server.
  *
  * <p>{@inheritDoc}
  */
 @Override public <Resp> void response(HttpAdapter<?, Resp> adapter, @Nullable Resp res,
   @Nullable Throwable error, SpanCustomizer customizer) {
  super.response(adapter, res, error, customizer);
 }
}

 /**
  * Customizes the span based on the response sent to the client.
  *
  * <p>{@inheritDoc}
  */
 @Override public <Resp> void response(HttpAdapter<?, Resp> adapter, @Nullable Resp res,
   @Nullable Throwable error, SpanCustomizer customizer) {
  super.response(adapter, res, error, customizer);
 }
}

 /**
  * Finishes the client span after assigning it tags according to the response or error.
  *
  * <p>This is typically called once the response headers are received, and after the span is
  * {@link brave.Tracer.SpanInScope#close() no longer in scope}.
  *
  * @see HttpClientParser#response(HttpAdapter, Object, Throwable, SpanCustomizer)
  */
 public void handleReceive(@Nullable Resp response, @Nullable Throwable error, Span span) {
  handleFinish(response, error, span);
 }
}

/** Returns the last value associated with the key or null */
@Nullable public String tag(String key) {
 if (key == null) throw new NullPointerException("key == null");
 if (key.isEmpty()) throw new IllegalArgumentException("key is empty");
 String result = null;
 for (int i = 0, length = tags.size(); i < length; i += 2) {
  if (key.equals(tags.get(i))) result = tags.get(i + 1);
 }
 return result;
}

/** @see TraceContext#sampled() */
public Builder sampled(@Nullable Boolean sampled) {
 if (sampled == null) {
  flags &= ~(FLAG_SAMPLED_SET | FLAG_SAMPLED);
  return this;
 }
 return sampled(sampled.booleanValue());
}

/**
 * The absolute http path, without any query parameters or null if unreadable. Ex.
 * "/objects/abcd-ff"
 *
 * <p>Conventionally associated with the key "http.path"
 * @see #route(Object)
 */
@Nullable public String path(Req request) {
 String url = url(request);
 if (url == null) return null;
 return URI.create(url).getPath(); // TODO benchmark
}

@Nullable public String linkLocalIp() {
 // uses synchronized variant of double-checked locking as getting the endpoint can be expensive
 if (linkLocalIp != null) return linkLocalIp;
 synchronized (this) {
  if (linkLocalIp == null) {
   linkLocalIp = produceLinkLocalIp();
  }
 }
 return linkLocalIp;
}

/** @see #localIp() */
public boolean localIp(@Nullable String localIp) {
 this.localIp = IpLiteral.ipOrNull(localIp);
 return true;
}

/** @see brave.Span#remoteIpAndPort(String, int) */
public boolean remoteIpAndPort(@Nullable String remoteIp, int remotePort) {
 if (remoteIp == null) return false;
 this.remoteIp = IpLiteral.ipOrNull(remoteIp);
 if (this.remoteIp == null) return false;
 if (remotePort > 0xffff) throw new IllegalArgumentException("invalid port " + remotePort);
 if (remotePort < 0) remotePort = 0;
 this.remotePort = remotePort;
 return true;
}

 @Override public Scope newScope(@Nullable TraceContext currentSpan) {
  Scope scope = delegate.newScope(currentSpan);
  return decorateScope(currentSpan, scope);
 }
}

 public SamplingFlags sample(@Nullable P parameters) {
  if (parameters == null) return SamplingFlags.EMPTY;
  for (Rule<P> rule : rules) {
   if (rule.matches(parameters)) return rule.isSampled();
  }
  return SamplingFlags.EMPTY;
 }
}

/**
 * Returns the value of the field with the specified key or null if not available.
 *
 * <p>Prefer {@link #get(TraceContext, String)} if you have a reference to a span.
 */
@Nullable public static String get(String name) {
 TraceContext context = currentTraceContext();
 return context != null ? get(context, name) : null;
}

 final void replace(String key, @Nullable String value) {
  if (value != null) {
   put(key, value);
  } else {
   remove(key);
  }
 }
}

 @Override public void onCompletion(RecordMetadata metadata, @Nullable Exception exception) {
  try (Scope ws = current.maybeScope(span.context())) {
   delegate.onCompletion(metadata, exception);
  } finally {
   super.onCompletion(metadata, exception);
  }
 }
}

/**
 * Returns the {@link Tracer#nextSpan(TraceContextOrSamplingFlags)} or null if {@link
 * #CURRENT_TRACER} and tracing isn't available.
 */
@Nullable public Span next(TraceContextOrSamplingFlags extracted) {
 Tracer tracer = tracer();
 if (tracer == null) return null;
 Span next = tracer.nextSpan(extracted);
 Object[] spanAndScope = {next, tracer.withSpanInScope(next)};
 getCurrentSpanInScopeStack().addFirst(spanAndScope);
 return next;
}