Distributed tracing has become a crucial tool in our microservices toolbox, and Micronaut makes it a breeze to implement. I’ve been tinkering with Micronaut’s native support for distributed tracing lately, and I’m excited to share what I’ve learned.

Let’s start with the basics. Micronaut offers out-of-the-box support for distributed tracing using popular tools like Zipkin and OpenTelemetry. These tools help us visualize and analyze the flow of requests across our microservices architecture, making it easier to identify bottlenecks and troubleshoot issues.

To get started with Zipkin in your Micronaut application, you’ll need to add the following dependency to your build file:

implementation("io.micronaut:micronaut-tracing-zipkin")

Once you’ve added the dependency, you’ll need to configure your application to send traces to your Zipkin server. You can do this by adding the following properties to your application.yml file:

tracing:
  zipkin:
    enabled: true
    url: http://localhost:9411
    sampler:
      probability: 1

This configuration tells Micronaut to enable Zipkin tracing and send traces to a Zipkin server running on localhost:9411. The sampler probability of 1 means that all requests will be traced.

Now, let’s create a simple controller to demonstrate how tracing works:

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.tracing.annotation.NewSpan;

@Controller("/hello")
public class HelloController {

    @Get("/")
    @NewSpan("say-hello")
    public String hello() {
        return "Hello, World!";
    }
}

In this example, we’ve used the @NewSpan annotation to create a new span for our hello method. This span will be visible in Zipkin, allowing us to see how long the method takes to execute.

But what if we want to add custom tags to our spans? Micronaut makes this easy too. We can use the @SpanTag annotation to add custom tags to our spans:

import io.micronaut.tracing.annotation.SpanTag;

@Get("/{name}")
@NewSpan("say-hello-name")
public String helloName(@SpanTag("name") String name) {
    return "Hello, " + name + "!";
}

In this example, we’ve added a custom tag called “name” to our span. This tag will be visible in Zipkin, making it easier to filter and search for specific requests.

Now, let’s talk about OpenTelemetry. It’s a more recent addition to the distributed tracing ecosystem, but it’s quickly gaining popularity due to its vendor-neutral approach. Micronaut supports OpenTelemetry out of the box, making it easy to switch from Zipkin if you decide to do so.

To use OpenTelemetry with Micronaut, you’ll need to add the following dependencies:

implementation("io.micronaut:micronaut-tracing-opentelemetry")
implementation("io.opentelemetry:opentelemetry-exporter-otlp")

Then, configure your application to use OpenTelemetry by adding the following to your application.yml:

tracing:
  opentelemetry:
    enabled: true
    exporter:
      otlp:
        endpoint: http://localhost:4317

This configuration tells Micronaut to use OpenTelemetry and send traces to an OTLP-compatible server running on localhost:4317.

One of the cool things about OpenTelemetry is its support for automatic instrumentation. This means that many common libraries and frameworks are automatically traced without you having to add any additional code. For example, if you’re using Micronaut Data, your database queries will be automatically traced.

But what if you want to add custom spans or attributes to your OpenTelemetry traces? Micronaut has you covered there too. You can use the OpenTelemetry API directly in your code:

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import jakarta.inject.Inject;

@Controller("/otel")
public class OpenTelemetryController {

    @Inject
    private Tracer tracer;

    @Get("/")
    public String hello() {
        Span span = tracer.spanBuilder("custom-span").startSpan();
        try {
            span.setAttribute("custom.attribute", "value");
            return "Hello, OpenTelemetry!";
        } finally {
            span.end();
        }
    }
}

In this example, we’re creating a custom span and adding a custom attribute to it. This gives us fine-grained control over our tracing data.

One thing I’ve found particularly useful is the ability to trace across service boundaries. When you’re working with microservices, it’s common to have one service call another. Micronaut’s tracing support makes it easy to see these cross-service calls in your tracing tool.

For example, let’s say we have two services: a user service and an order service. The order service needs to call the user service to get user details when processing an order. Here’s how we might implement this with tracing:

// In OrderService.java
@Client("user-service")
public interface UserClient {
    @Get("/users/{id}")
    User getUser(Long id);
}

@Singleton
public class OrderService {
    @Inject
    private UserClient userClient;

    @NewSpan("process-order")
    public Order processOrder(Long userId, List<Item> items) {
        User user = userClient.getUser(userId);
        // Process the order...
        return new Order(user, items);
    }
}

In this example, the call to userClient.getUser() will automatically be traced as part of the “process-order” span. When you look at the trace in Zipkin or your OpenTelemetry-compatible tool, you’ll see both the “process-order” span and the HTTP call to the user service.

One thing to keep in mind when implementing distributed tracing is the potential performance impact. While Micronaut’s tracing implementation is designed to be lightweight, it does add some overhead to each request. In my experience, this overhead is usually negligible, but it’s something to be aware of, especially if you’re dealing with high-traffic services.

To mitigate this, you can adjust the sampling rate. Instead of tracing every request (probability: 1), you might choose to trace only a percentage of requests:

tracing:
  zipkin:
    sampler:
      probability: 0.1  # Trace 10% of requests

This can significantly reduce the overhead of tracing while still giving you valuable insights into your system’s performance.

Another cool feature of Micronaut’s tracing support is its integration with Micronaut’s declarative HTTP client. If you’re using Micronaut to make HTTP calls to other services, those calls will automatically be traced. This means you can see the entire request flow, from the initial incoming HTTP request, through any internal service calls, to the final response.

Here’s a quick example:

@Client("http://api.example.com")
public interface ExampleClient {
    @Get("/data")
    String getData();
}

@Controller("/proxy")
public class ProxyController {
    @Inject
    private ExampleClient client;

    @Get("/")
    public String proxy() {
        return client.getData();
    }
}

In this example, when a request comes in to the /proxy endpoint, it will make a call to api.example.com. Both the incoming request to /proxy and the outgoing request to /data will be traced, allowing you to see the full flow of the request.

One thing I’ve found particularly useful is the ability to add business-specific information to your traces. For example, you might want to add a customer ID or order number to your spans. This can make it much easier to track down issues related to specific customers or transactions.

Here’s how you might do this:

@Singleton
public class OrderProcessor {
    @Inject
    private Tracer tracer;

    @NewSpan("process-order")
    public void processOrder(Order order) {
        Span span = tracer.currentSpan();
        span.setAttribute("order.id", order.getId().toString());
        span.setAttribute("customer.id", order.getCustomerId().toString());

        // Process the order...
    }
}

By adding these attributes to your span, you can easily filter and search for traces related to specific orders or customers in your tracing tool.

As you start implementing distributed tracing across your microservices, you’ll likely encounter some challenges. One common issue is dealing with async operations. When you’re working with asynchronous code, it’s easy to lose the trace context. Micronaut provides some tools to help with this.

For example, if you’re using CompletableFuture, you can use Micronaut’s TracedExecutorService to ensure that the trace context is propagated:

@Singleton
public class AsyncService {
    @Inject
    private TracedExecutorService executorService;

    public CompletableFuture<String> doSomethingAsync() {
        return CompletableFuture.supplyAsync(() -> {
            // This code will be traced
            return "Result";
        }, executorService);
    }
}

Another challenge you might face is tracing across different protocols. While HTTP tracing is straightforward, what if you’re using message queues or gRPC? Micronaut has you covered there too. It provides integrations with various messaging systems and gRPC, allowing you to trace across these protocols as well.

For example, if you’re using Kafka, you can add the micronaut-kafka dependency and Micronaut will automatically propagate trace context across your Kafka producers and consumers.

As you dive deeper into distributed tracing, you’ll start to appreciate the wealth of information it provides. You can use it not just for troubleshooting, but also for performance optimization. By analyzing your traces, you can identify slow database queries, inefficient API calls, and other bottlenecks in your system.

One tip I’ve found useful is to set up alerts based on your tracing data. Most tracing systems allow you to set up alerts based on things like span duration or error rates. This can help you catch issues before they become critical problems.

Implementing distributed tracing with Micronaut has been a game-changer for me. It’s helped me understand the flow of requests through our microservices architecture, identify performance bottlenecks, and troubleshoot issues much more quickly than before. And the best part is, with Micronaut’s native support, it’s surprisingly easy to set up and use.

Whether you’re just getting started with microservices or you’re looking to improve observability in an existing system, I highly recommend giving Micronaut’s tracing support a try. It’s a powerful tool that can provide invaluable insights into your distributed system.

Remember, the key to effective tracing is to start small and gradually expand. Begin by tracing a few key services or endpoints, and then expand as you become more comfortable with the tools and concepts. Before you know it, you’ll have a comprehensive view of your entire system, and you’ll wonder how you ever managed without it.

Happy tracing!