TraceKit Java SDK Setup

When To Use

Use this skill when the user asks to:

Add TraceKit to a Java service
Add observability or APM to a Java application
Instrument a Java service with distributed tracing
Configure TraceKit API keys in a Java project
Debug production Java services with live breakpoints
Set up code monitoring in a Java app
Add tracing to a Spring Boot or Micronaut application

Non-Negotiable Rules

Never hardcode API keys in code or config files. Always use System.getenv("TRACEKIT_API_KEY") or externalized config.
Always initialize TraceKit before starting the HTTP server -- the SDK must be configured before routes are registered.
Always include a verification step confirming traces appear in https://app.tracekit.dev/traces.
Always enable code monitoring (enableCodeMonitoring: true) -- it is TraceKit's differentiator.
Use env vars or externalized config for all secrets -- never commit API keys to source control.

Detection

Before applying this skill, detect the project type:

Check for pom.xml -- confirms Maven build system.
Check for build.gradle or build.gradle.kts -- confirms Gradle build system.
Detect framework by scanning dependencies:
- spring-boot-starter-web or org.springframework.boot => Spring Boot (use Spring Boot branch)
- io.micronaut => Micronaut (use Micronaut branch)
- Neither => vanilla Java (use vanilla Java branch)
Only ask the user if multiple frameworks are detected or build files are missing.

Step 1: Environment Setup

Set the TRACEKIT_API_KEY environment variable. This is the only required secret.

Add to your environment or .env file:

export TRACEKIT_API_KEY=ctxio_your_api_key_here

Where to get your API key:

Log in to TraceKit
Go to API Keys page
Generate a new key (starts with ctxio_)

Do not commit real API keys. Use environment variables, secret managers, or CI/CD secrets.

Step 2: Install SDK

Choose your build system and framework.

Maven -- Spring Boot

Add to pom.xml:

<dependency>
    <groupId>dev.tracekit</groupId>
    <artifactId>tracekit-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Maven -- Vanilla Java / Micronaut

Add to pom.xml:

<dependency>
    <groupId>dev.tracekit</groupId>
    <artifactId>tracekit-core</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle -- Spring Boot

Add to build.gradle:

implementation 'dev.tracekit:tracekit-spring-boot-starter:1.0.0'

Or build.gradle.kts:

implementation("dev.tracekit:tracekit-spring-boot-starter:1.0.0")

Gradle -- Vanilla Java / Micronaut

Add to build.gradle:

implementation 'dev.tracekit:tracekit-core:1.0.0'

Or build.gradle.kts:

implementation("dev.tracekit:tracekit-core:1.0.0")

Prerequisites:

Java 8 or higher (Java 11+ recommended)
Maven or Gradle build system
A TraceKit account (create one free)

Step 3: Framework Integration

Choose the branch matching your framework. Apply one of the following.

Branch A: Spring Boot (Recommended)

Configuration via application.yml:

tracekit:
  api-key: ${TRACEKIT_API_KEY}
  service-name: my-spring-service
  endpoint: https://app.tracekit.dev/v1/traces
  enable-code-monitoring: true

Or via application.properties:

tracekit.api-key=${TRACEKIT_API_KEY}
tracekit.service-name=my-spring-service
tracekit.endpoint=https://app.tracekit.dev/v1/traces
tracekit.enable-code-monitoring=true

The Spring Boot starter provides auto-configuration -- no @Bean definitions needed. It automatically:

Registers a servlet filter for HTTP request tracing
Traces JDBC database queries
Traces outgoing RestTemplate and WebClient calls
Captures unhandled exceptions
Propagates trace context to downstream services

Manual bean registration (only if auto-configuration is disabled):

import dev.tracekit.TracekitAutoConfiguration;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

@Configuration
@Import(TracekitAutoConfiguration.class)
public class TracekitConfig {
    // Auto-configuration handles everything
}

Custom filter registration (only if you need specific ordering):

import dev.tracekit.spring.TracekitFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class TracekitFilterConfig {

    @Bean
    public FilterRegistrationBean<TracekitFilter> tracekitFilter() {
        FilterRegistrationBean<TracekitFilter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new TracekitFilter());
        registration.addUrlPatterns("/*");
        registration.setOrder(1); // Run early to capture full request
        return registration;
    }
}

Branch B: Micronaut

Configuration via application.yml:

tracekit:
  api-key: ${TRACEKIT_API_KEY}
  service-name: my-micronaut-service
  endpoint: https://app.tracekit.dev/v1/traces
  enable-code-monitoring: true

Register the TraceKit bean and filter:

import dev.tracekit.Tracekit;
import dev.tracekit.TracekitConfig;
import io.micronaut.context.annotation.Factory;
import jakarta.inject.Singleton;

@Factory
public class TracekitFactory {

    @Singleton
    public Tracekit tracekit() {
        return new Tracekit(TracekitConfig.builder()
            .apiKey(System.getenv("TRACEKIT_API_KEY"))
            .serviceName("my-micronaut-service")
            .endpoint("https://app.tracekit.dev/v1/traces")
            .enableCodeMonitoring(true)
            .build());
    }
}

HTTP filter for request tracing:

import dev.tracekit.Tracekit;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.MutableHttpResponse;
import io.micronaut.http.annotation.Filter;
import io.micronaut.http.filter.HttpServerFilter;
import io.micronaut.http.filter.ServerFilterChain;
import jakarta.inject.Inject;
import org.reactivestreams.Publisher;

@Filter("/**")
public class TracekitHttpFilter implements HttpServerFilter {

    @Inject
    private Tracekit tracekit;

    @Override
    public Publisher<MutableHttpResponse<?>> doFilter(HttpRequest<?> request, ServerFilterChain chain) {
        return tracekit.traceRequest(request, chain);
    }
}

Branch C: Vanilla Java

Initialize TraceKit in your main() method:

import dev.tracekit.Tracekit;
import dev.tracekit.TracekitConfig;

public class Main {
    public static void main(String[] args) {
        // Initialize TraceKit -- MUST be before server start
        Tracekit tracekit = new Tracekit(TracekitConfig.builder()
            .apiKey(System.getenv("TRACEKIT_API_KEY"))
            .serviceName("my-java-service")
            .endpoint("https://app.tracekit.dev/v1/traces")
            .enableCodeMonitoring(true)
            .build());

        // Register shutdown hook to flush pending traces
        Runtime.getRuntime().addShutdownHook(new Thread(tracekit::shutdown));

        // ... start your HTTP server with tracekit filter
    }
}

Step 4: Error Capture

Capture exceptions explicitly where you handle them:

import dev.tracekit.Tracekit;

try {
    Object result = someOperation();
} catch (Exception e) {
    Tracekit.captureException(e);
    // Handle the error...
}

For adding context to traces, use manual spans:

import dev.tracekit.Span;
import dev.tracekit.Tracekit;

Span span = Tracekit.startSpan("process-order");
span.setAttribute("order.id", orderId);
span.setAttribute("user.id", userId);

try {
    Order order = processOrder(orderId);
} catch (Exception e) {
    Tracekit.captureException(e);
    throw e;
} finally {
    span.end();
}

Step 4b: Snapshot Capture (Code Monitoring)

For programmatic snapshots, use the SnapshotClient directly — do not call through the SDK wrapper. The SDK uses stack inspection internally to identify the call site. Adding extra layers shifts the frame and causes snapshots to report the wrong source location.

Create a Breakpoints utility class:

import dev.tracekit.SnapshotClient;
import dev.tracekit.Tracekit;
import java.util.Map;

public final class Breakpoints {
    private static SnapshotClient snapshotClient;

    public static void init(Tracekit sdk) {
        if (sdk != null) {
            snapshotClient = sdk.snapshotClient();
        }
    }

    public static void capture(String name, Map<String, Object> data) {
        if (snapshotClient == null) return;
        snapshotClient.checkAndCapture(name, data);
    }
}

Initialize after SDK setup:

Breakpoints.init(tracekit);

Use at call sites:

Breakpoints.capture("payment-failed", Map.of("orderId", orderId, "error", e.getMessage()));

See the tracekit-code-monitoring skill for the full pattern across all languages.

Step 5: JDBC Database Tracing

For Spring Boot, JDBC tracing is automatic via the auto-configuration.

For Micronaut or vanilla Java, wrap your DataSource:

import dev.tracekit.jdbc.TracekitDataSource;
import javax.sql.DataSource;

DataSource tracedDataSource = new TracekitDataSource(originalDataSource);

This traces all SQL queries with:

SQL statement (parameterized -- no sensitive data)
Database system and name
Query duration

Step 6: Outgoing HTTP Call Tracing

Spring Boot (RestTemplate):

import dev.tracekit.spring.TracekitRestTemplateInterceptor;
import org.springframework.web.client.RestTemplate;

@Bean
public RestTemplate restTemplate() {
    RestTemplate restTemplate = new RestTemplate();
    restTemplate.getInterceptors().add(new TracekitRestTemplateInterceptor());
    return restTemplate;
}

Spring Boot (WebClient):

import dev.tracekit.spring.TracekitWebClientFilter;
import org.springframework.web.reactive.function.client.WebClient;

@Bean
public WebClient webClient() {
    return WebClient.builder()
        .filter(new TracekitWebClientFilter())
        .build();
}

Vanilla Java (manual):

Span span = Tracekit.startSpan("http-client");
span.setAttribute("http.method", "GET");
span.setAttribute("http.url", "https://api.example.com/data");

try {
    HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
    span.setAttribute("http.status_code", response.statusCode());
} finally {
    span.end();
}

Step 7: Verification

After integrating, verify traces are flowing:

Start your application with TRACEKIT_API_KEY set in the environment.
Hit your endpoints 3-5 times -- e.g., curl http://localhost:8080/api/users.
Open https://app.tracekit.dev/traces.
Confirm new spans and your service name appear within 30-60 seconds.

If traces do not appear, see Troubleshooting below.

Troubleshooting

Traces not appearing in dashboard

Check TRACEKIT_API_KEY: Ensure the env var is set in the runtime environment. Verify: System.out.println(System.getenv("TRACEKIT_API_KEY")).
Check outbound access: Your service must reach https://app.tracekit.dev/v1/traces. Verify with: curl -X POST https://app.tracekit.dev/v1/traces (expect 401 -- means the endpoint is reachable).
Check init order: TraceKit must be initialized before starting the HTTP server.

Spring Boot auto-configuration not loading

Symptoms: No tracing despite correct application.yml config.

Fix: Ensure tracekit-spring-boot-starter is on the classpath. Check @SpringBootApplication scan includes the TraceKit package. Run with --debug to see auto-configuration report.

Micronaut bean not found

Symptoms: No bean of type [dev.tracekit.Tracekit] exists error.

Fix: Ensure the TracekitFactory is in a package scanned by Micronaut. Check that tracekit-core is on the classpath.

Missing environment variable

Symptoms: NullPointerException on startup or traces rejected by backend.

Fix: Ensure TRACEKIT_API_KEY is exported in your shell, .env file, Docker Compose, or deployment config. For Spring Boot, use ${TRACEKIT_API_KEY} placeholder syntax in application.yml.

Service name collisions

Symptoms: Traces appear under the wrong service in the dashboard.

Fix: Use a unique service-name per deployed service. Avoid generic names like "app" or "service".

Next Steps

Once your Java service is traced, consider:

Code Monitoring -- Set live breakpoints and capture snapshots in production without redeploying (already enabled via enableCodeMonitoring: true)
Distributed Tracing -- Connect traces across multiple services for full request visibility
Frontend Observability -- Add @tracekit/browser to your frontend for end-to-end trace correlation

References

Java SDK docs: https://app.tracekit.dev/docs/languages/java
TraceKit docs root: https://app.tracekit.dev/docs
Dashboard: https://app.tracekit.dev
Quick start: https://app.tracekit.dev/docs/quickstart