SDA Commons Server Trace

The module sda-commons-server-trace adds support to track or create a trace token. The trace token is used to correlate a set of service invocations that belongs to the same logically cohesive call of a higher level service offered by the SDA Platform, e.g. interaction service.

Every service must forward the received trace token within calls to other services that are part of the SDA Platform. In HTTP REST calls, it's done within the HTTP Header as Trace-Token.

If no token is provided within the request, it will be generated automatically and put into the request context. This should be only the case, if a service call firstly enters the SDA Platform.

The calls can be correlated in logs and metrics using this trace token that is also added to the MDC.

When using new threads for clients to invoke another service, the trace token is not transferred out-of-the-box. The same holds for mentioning the trace token in log entries of new threads. See the documentation about concurrency on how to transfer this context into another thread.

Usage

The trace token is loaded within a filter that is created and registered by the TraceTokenBundle which must be added to the Dropwizard application:

public class MyApplication extends Application<MyConfiguration> {

    public static void main(final String[] args) {
        new MyApplication().run(args);
    }

   @Override
   public void initialize(Bootstrap<MyConfiguration> bootstrap) {
      // ...
      bootstrap.addBundle(TraceTokenBundle.builder().build());
      // ...
   }

   @Override
   public void run(MyConfiguration configuration, Environment environment) {
      // ...
   }
}

Custom initialization

In some cases, Dropwizard can't be configured to start correlation for a specific initialization point. For example, a dedicated correlation for each entity may be useful when batch processes act on multiple entities in the database. Also, Dropwizard Tasks can't be configured on library level like regular HTTP endpoints although correlation may be desired here as well.

To cover such individual cases, the library allows to wrap an operation in a TraceTokenContext. This will result in a Trace-Token in the log MDC, forwarding the trace token with clients build with client-jersey and forwarding the parent trace token with producers of server-kafka.

Trace Context for Dropwizard Tasks

package org.sdase.commons.server.trace.test;

import io.dropwizard.servlets.tasks.Task;
import java.io.PrintWriter;
import java.util.List;
import java.util.Map;
import org.sdase.commons.shared.tracing.TraceTokenContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class TraceTokenAwareExampleTask extends Task {

  private static final Logger LOG = LoggerFactory.getLogger(TraceTokenAwareExampleTask.class);

  public TraceTokenAwareExampleTask() {
    super("example-task");
  }

  @Override
  public void execute(Map<String, List<String>> parameters, PrintWriter output) {
    try (var traceTokenContext = TraceTokenContext.getOrCreateTraceTokenContext()) {
      LOG.info("Log with a TraceToken in the MDC.");
      // Note: Response headers will NOT contain the Trace-Token.
      output.println("Trace-Token: %s".formatted(traceTokenContext.get()));

      // Implement the task here. Logs will contain the 'Trace-Token' from the MDC.
    }
  }
}