Spring Boot Project Guide

Use this guide for Spring Boot services where request pipelines, services, and repositories must remain diagnosable.

Architecture Scope

• Controllers and servlet filter chain.
• Service and repository layers.
• Outbound clients (HTTP, messaging, DB).

Setup

Register the Obtrace client as a Spring bean and add the filter for request instrumentation:

import io.obtrace.sdk.core.ObtraceClient;
import io.obtrace.sdk.model.ObtraceConfig;
import io.obtrace.sdk.framework.SpringObtraceFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
@Configuration
public class ObtraceBootstrap {
    @Bean
    public ObtraceClient obtraceClient() {
        ObtraceConfig cfg = new ObtraceConfig();
        cfg.apiKey = System.getenv("OBTRACE_API_KEY");
        cfg.serviceName = "checkout-api";
        cfg.env = System.getenv("OBTRACE_ENV");
        cfg.serviceVersion = System.getenv("OBTRACE_SERVICE_VERSION");
        return new ObtraceClient(cfg);
    }
 
    @Bean
    public SpringObtraceFilter obtraceFilter(ObtraceClient client) {
        return new SpringObtraceFilter(client);
    }
}

The SpringObtraceFilter auto-captures every HTTP request as a span with method, route, status, and duration. All java.util.logging output is also captured automatically.

Environment Variables

OBTRACE_API_KEY=obt_...
OBTRACE_ENV=production
OBTRACE_SERVICE_VERSION=1.0.0

Validation Checklist

• Boot sequence emits startup signal
• 5xx responses are trace-linked
• Slow queries appear in span timeline
• JVM shutdown hook flushes pending telemetry

Production Hardening

1. Ensure shutdown hooks flush telemetry (ObtraceClient registers one by default).
2. Keep retry bounded to avoid cascading failures.
3. Add alerts on ingestion/auth errors.
4. Validate after dependency and Java version updates.

Troubleshooting

• No data after startup refactor: confirm @Configuration class is scanned.
• Missing DB spans: wrap JDBC calls with client.span().
• High cardinality: normalize dynamic tag values.