Name	Name	Last commit message	Last commit date
parent directory ..
src/main	src/main
.gitignore	.gitignore
README.md	README.md
pom.xml	pom.xml

TraceKit Spring Boot Example

This example demonstrates how to integrate TraceKit APM into a Spring Boot application using the TraceKit Spring Boot Starter.

Features

This demo application showcases:

Zero-Code Instrumentation: Automatic HTTP request tracing with Spring Boot auto-configuration
Distributed Tracing: OpenTelemetry-based tracing with automatic span creation
Error Tracking: Automatic exception capture and reporting
Security Scanning: Automatic detection of hardcoded secrets, API keys, and sensitive data
Code Monitoring: Snapshot-based debugging with variable capture
Custom Configuration: YAML-based configuration for all TraceKit settings
Local Development: Built-in support for the TraceKit Local UI
Production Ready: Easy configuration for cloud deployment

Prerequisites

Java 11 or higher
Maven 3.6+
TraceKit API key (for cloud reporting) - Sign up here
Optional: TraceKit Local UI running on http://localhost:3000 (for local development)

Quick Start

1. Configure Your API Key

Set your TraceKit API key as an environment variable:

export TRACEKIT_API_KEY=your-api-key-here

Or edit src/main/resources/application.yml and replace your-api-key-here with your actual API key.

2. Build the Application

mvn clean package

3. Run the Application

mvn spring-boot:run

Or run the JAR directly:

java -jar target/spring-boot-example-1.0.0-SNAPSHOT.jar

The application will start on http://localhost:8080.

Testing the Endpoints

Welcome Endpoint

curl http://localhost:8080/

Returns a welcome message with available endpoints.

User Lookup Endpoint

# Successful lookup
curl http://localhost:8080/users/1
curl http://localhost:8080/users/2
curl http://localhost:8080/users/3

# Not found (404)
curl http://localhost:8080/users/999

Error Simulation Endpoint

curl http://localhost:8080/error

This endpoint randomly throws different exceptions to demonstrate error tracking.

Payment Processing Endpoint (Security Scanning Demo)

curl -X POST http://localhost:8080/process-payment \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "paymentMethod": "card"
  }'

This endpoint demonstrates:

Security Scanning: Automatic detection of hardcoded secrets (Stripe API key, credit card numbers)
Code Monitoring: Snapshot capture with variable inspection
Distributed Tracing: Full request trace with custom spans

When you call this endpoint, TraceKit will:

Auto-register a breakpoint at the snapshot capture location
Scan variables for sensitive data (API keys, credit cards, tokens)
Redact sensitive values before sending to the backend
Create security flags for detected issues
Link the snapshot to the current trace

Security Issues Detected (intentionally included for demo):

Stripe API key: sk_test_FakeKey123456789ABCDEFGHIJKL (CRITICAL severity)
Credit card number: 4532123456789012 (HIGH severity)

Viewing Traces

Local UI (Development)

If you have the TraceKit Local UI running on http://localhost:3000:

Make requests to the demo endpoints
Open http://localhost:3000 in your browser
View real-time traces and performance metrics
Inspect span details, timing, and errors

Cloud Dashboard (Production)

Make requests to the demo endpoints
Log in to your TraceKit account at https://app.tracekit.dev
Navigate to the "Traces" section
Filter by service name: spring-boot-demo
Analyze performance, errors, and distributed traces

Viewing Code Snapshots

Enable Code Monitoring

First, ensure code monitoring is enabled in application.yml:

tracekit:
  enable-code-monitoring: true

Viewing Snapshots in Dashboard

Call the payment processing endpoint to trigger snapshot registration:

curl -X POST http://localhost:8080/process-payment \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "USD", "paymentMethod": "card"}'

Log in to https://app.tracekit.dev
Navigate to Code Monitoring → Breakpoints
Find the payment-processing breakpoint at DemoApplication.java:255
Enable the breakpoint by clicking the toggle switch

Make another request to the endpoint:

curl -X POST http://localhost:8080/process-payment \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, "currency": "EUR", "paymentMethod": "card"}'

Navigate to Code Monitoring → Snapshots to view captured data:
- Variable values at execution time
- Security flags for sensitive data detected
- Stack trace at the capture point
- Linked distributed trace (trace_id, span_id)

Security Events

Security scanning automatically creates events when sensitive data is detected:

Navigate to Security → Events in the dashboard
Look for events with types:
- sensitive_data_stripe_key (CRITICAL)
- sensitive_data_credit_card (HIGH)
Each event includes:
- Severity level
- Variable name containing sensitive data
- File location where it was detected
- Timestamp and service information
- Link to the related snapshot

Configuration Options

All TraceKit configuration is in src/main/resources/application.yml under the tracekit section:

Basic Configuration

tracekit:
  api-key: your-api-key-here        # Your TraceKit API key
  service-name: spring-boot-demo    # Service identifier in traces
  environment: development          # Deployment environment
  enabled: true                     # Enable/disable tracing

Sampling Configuration

tracekit:
  sampling:
    rate: 1.0  # Sample rate: 0.0 to 1.0 (1.0 = 100% of requests)

Export Configuration

tracekit:
  export:
    endpoint: https://api.tracekit.dev/v1/traces  # TraceKit cloud endpoint
    timeout: 30000                                 # Export timeout (ms)

Local UI Configuration

tracekit:
  local-ui:
    enabled: true                                  # Enable local UI export
    endpoint: http://localhost:3000/api/traces    # Local UI endpoint

Code Monitoring Configuration

Enable snapshot-based debugging with variable capture:

tracekit:
  enable-code-monitoring: true      # Enable snapshot capture (default: true)

How it works:

When you call tracekitSDK.captureSnapshot(label, variables), a breakpoint is automatically registered
Breakpoints must be enabled in the dashboard before they start capturing
Security scanning is automatic - all captured variables are scanned for sensitive data (API keys, passwords, tokens, credit cards)
Sensitive values are redacted before sending to the backend
Security flags are created for detected issues

Resource Attributes

Add custom metadata to all traces:

tracekit:
  resource:
    attributes:
      deployment.environment: production
      service.version: 1.0.0
      service.namespace: my-company
      team: backend
      region: us-east-1

Environment Variables

You can override configuration using environment variables:

TRACEKIT_API_KEY - Your TraceKit API key
TRACEKIT_SERVICE_NAME - Service name
TRACEKIT_ENVIRONMENT - Environment (development, staging, production)
TRACEKIT_ENDPOINT - Export endpoint
TRACEKIT_LOCAL_UI_ENABLED - Enable/disable local UI (true/false)
TRACEKIT_LOCAL_UI_ENDPOINT - Local UI endpoint

Example:

export TRACEKIT_API_KEY=tk_live_abc123
export TRACEKIT_SERVICE_NAME=my-spring-app
export TRACEKIT_ENVIRONMENT=production

mvn spring-boot:run

What Gets Traced?

The TraceKit Spring Boot Starter automatically traces:

HTTP Requests
- Method, path, status code
- Request and response headers
- Query parameters
- Processing duration
Errors and Exceptions
- Exception type and message
- Stack traces
- HTTP error status codes
Custom Attributes
- Service metadata
- Environment information
- Resource attributes

What Gets Monitored?

When code monitoring is enabled, TraceKit provides:

Code Snapshots
- Variable values at execution points
- Stack traces at capture time
- Function names and line numbers
- Linked to distributed traces (trace_id, span_id)
Security Scanning
- API Keys: AWS, Stripe, OpenAI, SendGrid, Twilio, etc.
- Tokens: JWT, OAuth, GitHub, GitLab tokens
- Credentials: Passwords, secrets, private keys
- PII: Credit card numbers, SSNs, email addresses
- Severity Levels: CRITICAL, HIGH, MEDIUM, LOW
Automatic Data Redaction
- Sensitive values replaced with [REDACTED]
- Security flags attached to snapshots
- Original data never leaves your application
- Safe for production debugging

Project Structure

spring-boot-example/
├── pom.xml                          # Maven configuration
├── README.md                        # This file
└── src/
    └── main/
        ├── java/
        │   └── dev/tracekit/example/
        │       └── DemoApplication.java    # Main application class
        └── resources/
            └── application.yml              # Configuration file

Troubleshooting

Traces Not Appearing

Check API Key: Ensure your TRACEKIT_API_KEY is set correctly
Verify Endpoints: Check that the export endpoint is accessible
Check Logs: Look for TraceKit debug logs in the console
Network Issues: Ensure your application can reach the TraceKit API

Local UI Not Working

Verify Local UI is Running: Check http://localhost:3000
Check Configuration: Ensure tracekit.local-ui.enabled: true
Port Conflicts: Make sure port 3000 is not in use by another application

Build Errors

Java Version: Ensure you're using Java 11 or higher
Maven Version: Update to Maven 3.6+
Clean Build: Run mvn clean install in the parent directory first

Advanced Usage

Programmatic Configuration

You can also configure TraceKit programmatically in your Spring Boot application:

@Configuration
public class TracekitConfig {
    @Bean
    public TracekitConfigurationCustomizer tracekitCustomizer() {
        return config -> {
            config.setServiceName("custom-service-name");
            config.setEnvironment("custom-environment");
            // Add more customizations
        };
    }
}

Custom Spans

Add custom instrumentation to your code:

import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Span;

@Service
public class MyService {

    @Autowired
    private Tracer tracer;

    public void myMethod() {
        Span span = tracer.spanBuilder("myCustomOperation").startSpan();
        try {
            // Your code here
        } finally {
            span.end();
        }
    }
}

Code Monitoring with Snapshots

Capture variable state at specific execution points:

import dev.tracekit.TracekitSDK;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

@Service
public class PaymentService {

    @Autowired
    private TracekitSDK tracekitSDK;

    public Payment processPayment(String customerId, double amount) {
        // Collect variables you want to inspect
        Map<String, Object> variables = new HashMap<>();
        variables.put("customerId", customerId);
        variables.put("amount", amount);
        variables.put("timestamp", System.currentTimeMillis());

        // Capture snapshot - auto-registers breakpoint on first call
        tracekitSDK.captureSnapshot("payment-start", variables);

        Payment payment = executePayment(customerId, amount);

        // Capture another snapshot at a different point
        Map<String, Object> resultVars = new HashMap<>();
        resultVars.put("paymentId", payment.getId());
        resultVars.put("status", payment.getStatus());
        resultVars.put("processingTime", payment.getProcessingTimeMs());

        tracekitSDK.captureSnapshot("payment-complete", resultVars);

        return payment;
    }

    private Payment executePayment(String customerId, double amount) {
        // Payment processing logic...
        return new Payment();
    }
}