OpenTelemetry interoperability for Java on z/OS

This example shows how you can capture an additional operation in a Java application running on a WebSphere Application Server monitored by Dynatrace.

1. Define a Tracer.

   javacopydownload
   import io.opentelemetry.api.GlobalOpenTelemetry;
   import io.opentelemetry.api.trace.Tracer;
   
   public final class RestaurantOpenTelemetry {
     public static Tracer getTracer() {
       return GlobalOpenTelemetry.getTracer("restaurant", "0.0.1");
     }
   }

2. Use the Tracer to capture an operation including some attributes.

   javacopydownload
   import io.opentelemetry.api.trace.Span;
   import io.opentelemetry.api.trace.SpanKind;
   import io.opentelemetry.context.Scope;
   
   public class MenuDao {
   
       public Order newOrder(String customer) {
   
           // OpenTelemetry: create a span and define it's scope
           Span span = RestaurantOpenTelemetry.getTracer().spanBuilder("MenuDao.newOrder")
               .setSpanKind(SpanKind.INTERNAL)
               .setAttribute("customer", customer)
               .startSpan();
           try (Scope scope = span.makeCurrent()) {
   
               // Your application code: create a new order
               Order order = new Order();
               order.setCustomer(customer);
               order.setStatus("pending");
   
               // OpenTelemetry: add order ID to the span
               span.setAttribute("newOrderId", order.getId());
   
               return order;
           } finally {
   
               // OpenTelemetry: close the span
               span.end();
           }
       }
   }

The MenuDao.newOrder operation is displayed as a span on the Code level tab in the Dynatrace web UI with the captured span attributes (customer, newOrderId) and measured execution time.

This example shows how you can trace an audit service running on a WebSphere Application Server (monitored by Dynatrace) that uses a Java transport that is not supported by OneAgent out-of-the-box. We use Java serialization (object output streams) as an example for such an unsupported Java transport.

To learn more about context propagation, refer to the official OpenTelemetry Context Propagation documentation.

Service A writes an audit entry to the ObjectOutputStream:

javacopydownload
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.propagation.TextMapPropagator;

public class AuditService {

    public static void sendAuditEntry(Order order) {

        // Your application code: declare an audit entry
        Map<String, String> auditEntry = new HashMap<>();
        auditEntry.put("name", order.getId().toString());
        auditEntry.put("description", order.getCustomer());

        // OpenTelemetry: Inject current context of audit entry and propagate it
        TextMapPropagator propagator = GlobalOpenTelemetry.getPropagators().getTextMapPropagator();
        propagator.inject(
            Context.current(),
            auditEntry,
            Map::put
        );

        // Your application code: write audit entry to objectOutputStream (Socket)
        Socket socket = new Socket(host, port);
        ObjectOutputStream objectOutputStream = new ObjectOutputStream(socket.getOutputStream())) {
        objectOutputStream.writeObject(auditEntry);
    }
}

Service B reads an audit entry from the ObjectInputStream:

javacopydownload
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import io.opentelemetry.context.propagation.TextMapGetter;

public class AuditService {

    private static void receivedAuditEntry(Map<String, String> auditEntry) {

        // OpenTelemetry: declare the tracer, create a span and define it's scope
        Span span = GlobalOpenTelemetry.getTracer("auditing-center", "0.0.1")
            .spanBuilder("auditEntry")
            .setSpanKind(SpanKind.SERVER)
            .setAttribute("auditName", auditEntry.get("name"))
            .startSpan();
        try (Scope scope = span.makeCurrent()) {

            // Your application code: process audit entry
            // ...
        }
        span.end();
    }

    public static void readAuditEntryFromSocket(Socket socket) {
        ObjectInputStream objectInputStream = new ObjectInputStream(socket.getInputStream());
        Object input = objectInputStream.readObject();

        // OpenTelemetry: extract context of audit entry
        Context context = GlobalOpenTelemetry.getPropagators().getTextMapPropagator()
            .extract(
                Context.current(),
                input,
                new TextMapGetter<Map<String, String>>(){ /* ... */ });

        try (Scope scope = context.makeCurrent()) {
            receivedAuditEntry((Map<String, String>) input);
        }
        // ...
    }
}

Dynatrace displays the full end-to-end trace as a distributed trace that contains the auditEntry as a service method which includes the captured attributes and measured execution time. The auditEntry service method is the result of the traced receivedAuditEntry method with its new span. The fact that it is displayed as a child of the /orderReceived service method is the result of the inject and extract calls of the TextMapPropagator.