Tracer (Tracer: Core 0.11.1 API)

```
public interface Tracer
```
A tracer is a lifecycle manager of one or more traces. Traces are identified by name, e.g. X-Trace-ID and, during an active lifecycle, they can have a value, e.g. 5dc90f18-231f-11e6-a17d-0f84f5d57f60. Values can either be provided on a per-lifecycle basis or generated on-demand by a generator. Lifecycle events, i.e. start and stop, can be observed by registering one or more listeners.

See Also:

Trace, Generator, TraceListener

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`static TracerFactory.Builder`	`builder()`
`static Tracer`	`create(String... names)` Creates a new tracer that will manage the given traces.
`default <V> Callable<V>`	`delegate(Callable<V> task, Function<String,String> provider)` Creates a delegating `callable`, based on the given original, that will manage the tracer lifecycle for every invocation.
`default Runnable`	`delegate(Runnable task, Function<String,String> provider)` Creates a delegating `runnable`, based on the given original, that will manage the tracer lifecycle for every invocation.
`void`	`forEach(BiConsumer<String,String> consumer)` Iterates all configured traces and allows to observe their current values.
`Trace`	`get(String name)` Retrieves the `trace` with the given name.
`boolean`	`isActive()`
`default <V> Callable<V>`	`manage(Callable<V> task)` Creates a `callable`, based on the given original, that will manage a completely new lifecycle for every invocation,
`default Runnable`	`manage(Runnable task)` Creates a `runnable`, based on the given original, that will manage a completely new lifecycle for every invocation,
`default <V> Callable<V>`	`preserve(Callable<V> task)` Creates a `callable`, based on the given original, that will preserve the current state of all traces for every invocation.
`default Runnable`	`preserve(Runnable task)` Creates a `runnable`, based on the given original, that will preserve the current state of all traces for every invocation.
`default Map<String,String>`	`snapshot()` Provides an immutable snapshot of all configured traces mapped by name to their current values.
`default void`	`start()` Starts a new trace lifecycle without transporting any trace identifiers.
`void`	`start(Function<String,String> provider)` Starts a new trace lifecycle with the possibility to transport given trace identifiers.
`void`	`stop()` Stops the current lifecycle.
`default <V> Callable<V>`	`tryPreserve(Callable<V> task)` Creates a `callable`, based on the given original, that will preserve the current state of all traces for every invocation, if a trace is currently active.
`default Runnable`	`tryPreserve(Runnable task)` Creates a `runnable`, based on the given original, that will preserve the current state of all traces for every invocation, if a trace is currently active.

- Method Detail
  - start
```
default void start()
```
    Starts a new trace lifecycle without transporting any trace identifiers.
    The most common use case would be to manage a trace lifecycle in a scheduled background job or during tests.
```
 tracer.start();

 try {
     // do some background work here
 } finally {
     tracer.stop();
 }
 
```
    Throws:
    
    IllegalStateException - if this tracer is already started
  - start
```
void start(Function<String,String> provider)
```
    Starts a new trace lifecycle with the possibility to transport given trace identifiers.
    The most common use case would be to read headers from an incoming HTTP request and hand them over to this tracer in order to persist them:
```
 tracer.start(request::getHeader)

 try {
     // continue with processing the request
 } finally {
     tracer.stop();
 }
 
```
    If the provider returns null a value will be created using the configured generator.
    Parameters:
    
    provider - a provider for trace identifiers, will be called with individual trace names
    
    Throws:
    
    IllegalStateException - if this tracer is already started
  - isActive
```
boolean isActive()
```
  - get
```
Trace get(String name)
```
    Retrieves the trace with the given name. The returned instance is a thread-safe live-view that allows to observe future changes to that trace's lifecycle.
    This can be used to manually access a trace value, e.g. for additional audit logging:
```
 entity.setModifiedBy(trace.getValue());
 db.persist(entity);
 
```
    Parameters:
    
    name - the name of the trace
    
    Returns:
    
    the trace
    
    Throws:
    
    IllegalArgumentException - if no trace was configured for the given name
  - forEach
```
void forEach(BiConsumer<String,String> consumer)
```
    Iterates all configured traces and allows to observe their current values.
    The most common use case woule be to pass all traces onto another system by adding them to an outgoing HTTP request:
```
 tracer.forEach(request::addHeader);
 
```
    Parameters:
    
    consumer - a consumer for traces, will be called with trace name-value pairs
    
    Throws:
    
    IllegalStateException - if this tracer not started
  - snapshot
```
default Map<String,String> snapshot()
```
    Provides an immutable snapshot of all configured traces mapped by name to their current values.
    
    Returns:
    
    an immutable snapshot of all traces
    
    Throws:
    
    IllegalStateException - if this tracer not started
  - stop
```
void stop()
```
    Stops the current lifecycle.
    
    Throws:
    
    IllegalStateException - if this tracer is not started
  - manage
```
default Runnable manage(Runnable task)
```
    Creates a runnable, based on the given original, that will manage a completely new lifecycle for every invocation,
    
    Parameters:
    
    task - the original runnable
    
    Returns:
    
    a runnable that will add lifecycle management to the given runnable
    
    See Also:
    
    delegate(Runnable, Function)
  - preserve
```
default Runnable preserve(Runnable task)
```
    Creates a runnable, based on the given original, that will preserve the current state of all traces for every invocation.
    
    Parameters:
    
    task - the original runnable
    
    Returns:
    
    a runnable that will add lifecycle management to the given runnable
    
    Throws:
    
    IllegalStateException - if this tracer is not started
    
    See Also:
    
    snapshot(), delegate(Runnable, Function)
  - tryPreserve
```
default Runnable tryPreserve(Runnable task)
```
    Creates a runnable, based on the given original, that will preserve the current state of all traces for every invocation, if a trace is currently active. Otherwise it will manage a completely new lifecycle for every invocation.
    
    Parameters:
    
    task - the original runnable
    
    Returns:
    
    a runnable that will add lifecycle management to the given runnable
    
    See Also:
    
    snapshot(), preserve(Runnable), manage(Runnable)
  - delegate
```
default Runnable delegate(Runnable task,
                          Function<String,String> provider)
```
    Creates a delegating runnable, based on the given original, that will manage the tracer lifecycle for every invocation. Initial trace values can be seeded with the given provider.
    
    Parameters:
    
    task - the original runnable
    
    provider - a provider for trace identifiers, will be called with individual trace names
    
    Returns:
    
    a runnable that will add lifecycle management to the given runnable
    
    See Also:
    
    start(Function), manage(Runnable), preserve(Runnable)
  - manage
```
default <V> Callable<V> manage(Callable<V> task)
```
    Creates a callable, based on the given original, that will manage a completely new lifecycle for every invocation,
    
    Parameters:
    
    task - the original callable
    
    Returns:
    
    a callable that will add lifecycle management to the given callable
    
    See Also:
    
    delegate(Callable, Function)
  - preserve
```
default <V> Callable<V> preserve(Callable<V> task)
```
    Creates a callable, based on the given original, that will preserve the current state of all traces for every invocation.
    
    Parameters:
    
    task - the original callable
    
    Returns:
    
    a callable that will add lifecycle management to the given callable
    
    Throws:
    
    IllegalStateException - if this tracer is not started
    
    See Also:
    
    snapshot(), delegate(Callable, Function)
  - tryPreserve
```
default <V> Callable<V> tryPreserve(Callable<V> task)
```
    Creates a callable, based on the given original, that will preserve the current state of all traces for every invocation, if a trace is currently active. Otherwise it will manage a completely new lifecycle for every invocation.
    
    Parameters:
    
    task - the original callable
    
    Returns:
    
    a callable that will add lifecycle management to the given callable
    
    See Also:
    
    snapshot(), preserve(Callable), manage(Callable)
  - delegate
```
default <V> Callable<V> delegate(Callable<V> task,
                                 Function<String,String> provider)
```
    Creates a delegating callable, based on the given original, that will manage the tracer lifecycle for every invocation. Initial trace values can be seeded with the given provider.
    
    Parameters:
    
    task - the original callable
    
    provider - a provider for trace identifiers, will be called with individual trace names
    
    Returns:
    
    a callable that will add lifecycle management to the given callable
    
    See Also:
    
    start(Function), manage(Callable), preserve(Callable)
  - create
```
static Tracer create(String... names)
```
    Creates a new tracer that will manage the given traces. All traces will be using the UUIDGenerator by default. The returned instance will not have any listeners attached to it.
    
    Parameters:
    
    names - trace names to be configured
    
    Returns:
    
    a new tracer
  - builder
```
static TracerFactory.Builder builder()
```

Interface Tracer

Method Summary

Method Detail

start

start

isActive

get

forEach

snapshot

stop

manage

preserve

tryPreserve

delegate

manage

preserve

tryPreserve

delegate

create

builder