`SpanHandler` is the base type for the now deprecated `FinishedSpanHandler`.
Notable, it can not just handle things at the end of a recording, but also the
beginning.
For example, this permits set-once baggage without the HTTP abstraction:
```java
static final BaggageField EPOCH_SECONDS = BaggageField.create("epoch_seconds");
static final class RootOnlyBaggage extends SpanHandler {
@Override
public boolean begin(TraceContext context, MutableSpan span, @Nullable TraceContext parent) {
if (EPOCH_SECONDS.getValue(context) == null) { // only set at the first span
long epochSeconds = System.currentTimeMillis() / 1000;
EPOCH_SECONDS.updateValue(context, String.valueOf(epochSeconds));
}
return true;
}
@Override public boolean end(TraceContext context, MutableSpan span, Cause cause) {
Tags.BAGGAGE_FIELD.tag(EPOCH_SECONDS, context, span);
return true;
}
}
```
As the parent is available, it can also facilitate advanced tasks like counting
children, or summarizing entire local roots.
See https://github.com/openzipkin/brave/tree/master/brave/src/test/java/brave/features/handler
and https://github.com/openzipkin/brave/blob/master/brave/src/main/java/brave/handler/SpanHandler.java for more
* Updates to latest Sampling infrastructure
Brave recently switched to an interface model for higher level sampling
like HTTP. So, `HttpSampler` -> `SamplingFunction<HttpRequest>`. Don't
worry because `HttpSampler` was retrofitted as a `SamplingFunction`.
This change moves to the higher interface, avoiding deprecated methods
and such. More interestingly, this weaves in support for `RpcTracing`,
which *finally* introduces RPC sampling the same way. Specifically, this
adds `SamplingFunction<RpcRequest>` under the same conventions as HTTP.
Most immediately, this can be used here in gRPC and Dubbo, as
autoconfiguration exists. It also works with any autoconfiguration that
isn't here, such as Armeria.
Ex. Here's a sampler that traces 100 "GetUserToken" requests per second. This
doesn't start new traces for requests to the health check service. Other
requests will use a global rate provided by the tracing component.
```java
import static brave.rpc.RpcRequestMatchers.methodEquals;
import static brave.rpc.RpcRequestMatchers.serviceEquals;
import static brave.sampler.Matchers.and;
--snip--
@Bean(name = ServerSampler.NAME)
SamplerFunction<RpcRequest> myRpcSampler() {
Matcher<RpcRequest> userAuth = and(
serviceEquals("users.UserService"),
methodEquals("GetUserToken")
);
return RpcRuleSampler.newBuilder()
.putRule(serviceEquals("grpc.health.v1.Health"), Sampler.NEVER_SAMPLE)
.putRule(userAuth, RateLimitingSampler.create(100)).build();
}
```
