Quick Start¶

Get Curve up and running in your Spring Boot application in under 5 minutes.

Prerequisites¶

Java 17 or higher
Spring Boot 3.x
Apache Kafka (or Docker)

Step 1: Add Dependency¶

Add Curve to your project:

GradleMaven

build.gradle

dependencies {
    implementation 'io.github.closeup1202:curve:0.2.0'
}

pom.xml

<dependency>
    <groupId>io.github.closeup1202</groupId>
    <artifactId>curve</artifactId>
    <version>0.2.0</version>
</dependency>

Step 2: Configure Kafka¶

Add Kafka configuration to your application.yml:

application.yml

spring:
  kafka:
    bootstrap-servers: localhost:9092

curve:
  enabled: true
  kafka:
    topic: event.audit.v1
    dlq-topic: event.audit.dlq.v1

Local Kafka Setup

Don't have Kafka running? Use Docker Compose:

docker-compose up -d

Step 3: Publish Your First Event¶

Add the @PublishEvent annotation to any service method:

OrderService.java

import io.github.closeup1202.curve.spring.audit.annotation.PublishEvent;
import io.github.closeup1202.curve.core.type.EventSeverity;
import org.springframework.stereotype.Service;

@Service
public class OrderService {

    @PublishEvent(
        eventType = "ORDER_CREATED",
        severity = EventSeverity.INFO
    )
    public Order createOrder(OrderRequest request) {
        // Your business logic
        return orderRepository.save(new Order(request));
    }
}

Step 4: Verify¶

Start your application and create an order. Check the Kafka topic:

# View events in Kafka
kafka-console-consumer --bootstrap-server localhost:9092 \
    --topic event.audit.v1 --from-beginning

Expected output:

{
  "eventId": "7355889748156289024",
  "eventType": "ORDER_CREATED",
  "occurredAt": "2026-02-03T10:30:00Z",
  "publishedAt": "2026-02-03T10:30:00.123Z",
  "severity": "INFO",
  "metadata": {
    "source": {
      "serviceName": "order-service",
      "serviceVersion": "1.0.0",
      "hostname": "localhost"
    },
    "actor": {
      "userId": "user123",
      "sessionId": "session-abc"
    },
    "trace": {
      "traceId": "trace-xyz",
      "spanId": "span-123"
    }
  },
  "payload": {
    "orderId": 12345,
    "customerId": "CUST-001",
    "amount": 99.99
  }
}

Step 5: Monitor (Optional)¶

Check health and metrics:

# Health check
curl http://localhost:8080/actuator/health/curve

# Metrics
curl http://localhost:8080/actuator/curve-metrics

Success!¶

You've successfully published your first event with Curve!

Next Steps¶

Learn Features

Explore PII protection, DLQ, and observability

Features
Advanced Configuration

Production-ready settings and optimization

Configuration
API Reference

Detailed annotation and property reference

API Docs
Need Help?

Troubleshooting and FAQ

Troubleshooting

Common Issues¶

Kafka Connection Failed

If you see Connection to node -1 could not be established, ensure Kafka is running:

docker-compose ps

Events Not Publishing

Check curve.enabled=true in application.yml
Verify Kafka bootstrap servers
Check logs for errors

See Troubleshooting Guide for more solutions.