Enable distributed tracing of microservices with MicroProfile 1.3 (and more) in Open Liberty 18.0.0.1

The mpOpenTracing-1.0 feature, together with a user provided io.opentracing.Tracer implementation, enables JAX-RS applications to automatically create, propagate, and deliver distributed tracing information. With the mpOpenTracing-1.0 feature, you can also explicitly mark for tracing methods that would not automatically be traced. Additionally, you can use the @Inject annotation to obtain an application-specific instance of an io.opentracing.Tracer. The injected Tracer instance provides access to the full opentracing.io API.

Give it a go with our new guide: Enabling distributed tracing in microservices.

In an environment with numerous services communicating with each other, distributed trace information provides a way to view the end-to-end flow of requests through multiple services. In many environments, there is a central trace collection service that accepts distributed tracing information from individual applications (one popular distributed tracing service is Zipkin). The central service correlates the distributed tracing information and presents the end-to-end request flow information with a UI.

The opentracing.io project defines an API that applications can use to create, propagate, and deliver distributed trace information. An implementation of the opentracing.io API must be available to an application so that the application can deliver distributed trace information. The implementation of the opentracing.io API must match the implementation of the central trace collection service.

For example, if the central trace collection service is Zipkin, then the opentracing.io implementation used by applications must perform distributed tracing functions in a way that is specific to Zipkin. Typically, you must explicitly add code to each application in the environment for it to create, propagate, and deliver distributed tracing information. With the mpOpenTracing-1.0` feature of Liberty, you do not need to add any code to your JAX-RS applications to participate in distributed tracing. The JAX-RS application will automatically create, propagate, and deliver distributed tracing information.

Each Liberty server in the environment must be configured with a user feature that provides an implementation of the opentracing.io API. The user feature must provide an implementation of the opentracing.io API that matches the central trace collection service that is used in the environment. You can find sample source code for a user feature that provides a Zipkin-specific opentracing.io API implementation on GitHub. Or you can download a built version of the user feature from Maven Central.

To enable the MicroProfile OpenTracing in the server.xml:

OpenAPI (previously Swagger) fully describes the details of your RESTful application, creating a shared contract between the server and clients and enables a variety of tools such as code generators and API gateways.

The MicroProfile OpenAPI specification formalizes a programming model for OpenAPI v3 (the next generation of the Swagger spec). Finally Java programmers have a standard set of annotations, models, and APIs that allow their application to remain portable (vendor neutral) while taking full advantage of the full OpenAPI v3 specification and extensive configuration provided by MicroProfile.

To try it out, add this feature to your server.xml list of features:

Then use one of the documentation methods. You can view the generated OpenAPI document in the endpoint /openapi, or view the rendered user interface at the endpoint /openapi/ui.

Give it a go with our new guide: Documenting RESTful APIs.

The MicroProfile Rest Client builds on the JAX-RS 2.0 Client APIs to provide a type-safe approach for invoking RESTful services over HTTP. This means writing client applications with more model-centric code and less "plumbing". You can create a Java interface that represents a remote RESTful service. Decorate the methods with appropriate @Path, @GET, @POST, etc. annotations, and then invoke those methods like a POJO and get the response from the remote service.

To enable MicroProfile Rest Client in the server.xml:

Want to see some worked examples? Andy McCright has written an intro to writing a REST client and there’s an even simpler example here on GitHub.

MicroProfile Metrics 1.1 adds explicit support for reusing metrics in different parts of your app, and adds the ability to configure it using mpConfig-1.2.

In the past, accidentally using the same name for a metric in multiple places would result in that metric being updated from all of those places. The new 'reusable' flag lets you explicitly indicate which metrics are expected/allowed to appear in multiple places and which are only allowed to be used in one place.

To enable the MicroProfile Metrics in the server.xml:

Give it a go with our new guide: Providing metrics from a microservice.

MicroProfile Config provides you with the capability to externally configure your microservices. If you’d like to know more, take a look at our new guide to configuring microservices or our interactive guide to separating configuration from code (no installation necessary to try this one!).

Building on version 1.1, MicroProfile Config 1.2.1 adds a number of new built-in converters, including Class, List, Set and automatic conversion for classes which have a suitable String constructor or static valueOf method. You can use this feature with either the cdi-1.2 feature or the cdi-2.0 feature.

To enable the MicroProfile Config 1.2 feature just add the following feature definition to your server.xml:

For more information about MicroProfile Config 1.2, see the MicroProfile.io website.

You can find a full list of changes since version 1.1 on the MicroProfile Config 1.2 Milestone and the 1.2.1 Maintenance Release Milestone.

There’s a new endpoint control MBean so that you can now query and control the state of both HTTP endpoints and message-driven beans (MDBs). You can now also control the state of MDBs using the existing server command. And you can configure whether the MDB starts automatically with the associated application.

Prior to this feature, the only option for administrators wanting to stop inbound traffic to the server was to use the server pause and resume commands from the command line; for more info, see the WebSphere Liberty Knowledge Center docs.

The MBean has the Object name: WebSphere:feature=kernel,name=ServerEndpointControl and, like most mbeans, is self-describing. To find out more, take a look at Fred’s blog post on controlling traffic on server endpoints with Liberty MBeans.

The Liberty threadpool controller automatically sets the size of the default threadpool to optimize the server throughput, so the system administrator does not have to manually tune the threadpool. This feature improves the controller’s ability to auto-tune to an optimal pool size when the offered workload has high-latency transactions. Workloads with high latency that require many threads were not always handled optimally by the prior controller implementation. With this improvement, there should be far fewer use cases where the system operator has to manually tune or configure the default threadpool in order to fully exploit the available CPU resources.

For more about Liberty’s threading, see Gary’s blog post: Liberty threading and why you probably don’t need to tune it

Currently, messages are written to the console and messages.log in a simple, human-friendly text format while FFDC, trace, and access log events are written to separate output files. This new JSON logging enhancement enables all of these events to be written to the messages.log and the console using JSON. This JSON format is easy for log analysis tools to read and parse. Writing events in JSON format to the console is particularly useful in containerized environments that provide log management capabilities (such as Docker or Cloud Foundry).

You can, for example, use JSON logging to provide effective log consolidation and analysis in Kibana dashboards. Administrators can use the sample dashboards to monitor a large number of Liberty containers to aid in problem determination. For example, see the WebSphere Liberty Knowledge Center docs.

You can enable JSON logging by setting environment variables, bootstrap properties, or specifying new attributes in the <logging> element in server.xml. For example:

This enables JSON logging and message, trace, access log, and FFDC events to be written to console in JSON format.

For more info, see the WebSphere Liberty Knowledge Center docs.