tessl/maven-org-apache-curator--curator-client
Low-level API for Apache ZooKeeper client library providing connection management, retry policies, and basic ZooKeeper operations
—
Pending
tracing-metrics.mddocs/
Tracing and Metrics
Pluggable tracing framework for monitoring ZooKeeper operations, connection events, and performance metrics in Apache Curator. The tracing system provides hooks for collecting operational data without impacting core functionality.
Capabilities
TracerDriver Interface
Core interface for implementing custom tracing and metrics collection systems.
/**
* Interface for tracing and metrics collection
*/
public interface TracerDriver {
/**
* Add a timing trace for an operation
* @param name Operation name or identifier
* @param time Duration of the operation
* @param unit Time unit for the duration
*/
void addTrace(String name, long time, TimeUnit unit);
/**
* Add a counter increment for an event
* @param name Counter name or identifier
* @param increment Amount to increment counter (typically 1)
*/
void addCount(String name, int increment);
}Usage Examples:
import org.apache.curator.drivers.TracerDriver;
import java.util.concurrent.TimeUnit;
// Custom tracing implementation
TracerDriver customTracer = new TracerDriver() {
@Override
public void addTrace(String name, long time, TimeUnit unit) {
long millis = unit.toMillis(time);
System.out.printf("TRACE: %s took %d ms%n", name, millis);
// Send to metrics system (e.g., Micrometer, Dropwizard Metrics)
metricsRegistry.timer(name).record(time, unit);
}
@Override
public void addCount(String name, int increment) {
System.out.printf("COUNT: %s incremented by %d%n", name, increment);
// Send to metrics system
metricsRegistry.counter(name).increment(increment);
}
};AdvancedTracerDriver Abstract Class
Extended tracing interface with additional capabilities for sophisticated monitoring systems.
/**
* Abstract class extending TracerDriver with advanced tracing capabilities
*/
public abstract class AdvancedTracerDriver implements TracerDriver {
// Provides additional tracing capabilities beyond basic TracerDriver
// Implementations can override to provide enhanced tracing features
}DefaultTracerDriver Class
No-operation implementation of TracerDriver for cases where tracing is not needed.
/**
* Default no-operation implementation of TracerDriver
*/
public class DefaultTracerDriver implements TracerDriver {
/**
* No-op trace method - discards timing information
*/
@Override
public void addTrace(String name, long time, TimeUnit unit) {
// No operation - tracing disabled
}
/**
* No-op count method - discards counter information
*/
@Override
public void addCount(String name, int increment) {
// No operation - counting disabled
}
}TimeTrace Class
Utility class for measuring operation duration and automatically reporting traces.
/**
* Utility for measuring and tracing operation duration
*/
public class TimeTrace {
/**
* Create a time trace for an operation
* @param name Operation name for tracing
* @param driver TracerDriver to receive the timing data
*/
public TimeTrace(String name, TracerDriver driver);
/**
* Complete the time measurement and send trace
* Call this when the operation completes
*/
public void commit();
}Usage Examples:
import org.apache.curator.TimeTrace;
import org.apache.curator.drivers.TracerDriver;
// Measure operation duration
TracerDriver tracer = getTracerDriver();
TimeTrace trace = new TimeTrace("zookeeper.getData", tracer);
try {
// Perform ZooKeeper operation
byte[] data = zookeeper.getData("/some/path", false, null);
// ... process data ...
} finally {
// Always commit the trace to record timing
trace.commit();
}
// Try-with-resources pattern (if TimeTrace implements AutoCloseable in your version)
try (TimeTrace trace = new TimeTrace("zookeeper.create", tracer)) {
zookeeper.create("/new/path", data, ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT);
// trace.commit() called automatically
}OperationTrace Class
Detailed operation tracing with session information for comprehensive monitoring.
/**
* Detailed operation tracing with session context
*/
public class OperationTrace {
/**
* Create operation trace with session information
* @param name Operation name
* @param driver TracerDriver for receiving trace data
* @param sessionId ZooKeeper session ID for context
*/
public OperationTrace(String name, TracerDriver driver, long sessionId);
/**
* Complete the operation trace
*/
public void commit();
}Usage Examples:
import org.apache.curator.drivers.OperationTrace;
// Trace operations with session context
long sessionId = zookeeper.getSessionId();
OperationTrace opTrace = new OperationTrace("create-ephemeral", tracer, sessionId);
try {
zookeeper.create("/ephemeral/node", data, ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.EPHEMERAL);
} finally {
opTrace.commit();
}EventTrace Class
Event-based tracing for discrete events and state changes.
/**
* Event-based tracing for discrete events
*/
public class EventTrace {
/**
* Create event trace
* @param name Event name
* @param driver TracerDriver for receiving event data
*/
public EventTrace(String name, TracerDriver driver);
/**
* Commit the event trace
*/
public void commit();
}Usage Examples:
import org.apache.curator.drivers.EventTrace;
// Trace discrete events
EventTrace connectionEvent = new EventTrace("connection.established", tracer);
connectionEvent.commit();
EventTrace sessionEvent = new EventTrace("session.expired", tracer);
sessionEvent.commit();
// Count-based events
tracer.addCount("connection.retry", 1);
tracer.addCount("operation.timeout", 1);Integration Patterns
Curator Client Tracing Integration
import org.apache.curator.CuratorZookeeperClient;
import org.apache.curator.drivers.TracerDriver;
// Custom tracer for production monitoring
TracerDriver productionTracer = new TracerDriver() {
private final MeterRegistry meterRegistry = Metrics.globalRegistry;
@Override
public void addTrace(String name, long time, TimeUnit unit) {
Timer.Sample.start(meterRegistry)
.stop(Timer.builder(name).register(meterRegistry));
}
@Override
public void addCount(String name, int increment) {
Counter.builder(name).register(meterRegistry).increment(increment);
}
};
// Configure client with tracing
CuratorZookeeperClient client = new CuratorZookeeperClientBuilder()
.connectString("localhost:2181")
.sessionTimeoutMs(5000)
.connectionTimeoutMs(5000)
.retryPolicy(new ExponentialBackoffRetry(1000, 3))
.tracerDriver(productionTracer) // Enable tracing
.build();Custom Tracing Implementations
// Console tracing for development
TracerDriver consoleTracer = new TracerDriver() {
@Override
public void addTrace(String name, long time, TimeUnit unit) {
System.out.printf("[TRACE] %s: %d %s%n", name, time, unit.name());
}
@Override
public void addCount(String name, int increment) {
System.out.printf("[COUNT] %s: +%d%n", name, increment);
}
};
// File-based tracing
TracerDriver fileTracer = new TracerDriver() {
private final PrintWriter logWriter = new PrintWriter(new FileWriter("curator-traces.log", true));
@Override
public void addTrace(String name, long time, TimeUnit unit) {
logWriter.printf("%s TRACE %s %d %s%n",
Instant.now(), name, time, unit.name());
logWriter.flush();
}
@Override
public void addCount(String name, int increment) {
logWriter.printf("%s COUNT %s %d%n",
Instant.now(), name, increment);
logWriter.flush();
}
};
// Composite tracer (send to multiple destinations)
TracerDriver compositeTracer = new TracerDriver() {
private final List<TracerDriver> tracers = Arrays.asList(consoleTracer, fileTracer);
@Override
public void addTrace(String name, long time, TimeUnit unit) {
tracers.forEach(tracer -> tracer.addTrace(name, time, unit));
}
@Override
public void addCount(String name, int increment) {
tracers.forEach(tracer -> tracer.addCount(name, increment));
}
};Common Trace Names and Patterns
// Connection lifecycle tracing
tracer.addCount("curator.connection.started", 1);
tracer.addCount("curator.connection.lost", 1);
tracer.addCount("curator.connection.reconnected", 1);
// Operation timing
TimeTrace createTrace = new TimeTrace("curator.zk.create", tracer);
TimeTrace getTrace = new TimeTrace("curator.zk.getData", tracer);
TimeTrace deleteTrace = new TimeTrace("curator.zk.delete", tracer);
// Retry tracking
tracer.addCount("curator.retry.attempt", 1);
tracer.addCount("curator.retry.exhausted", 1);
tracer.addCount("curator.retry.success", 1);
// Session tracking
tracer.addCount("curator.session.created", 1);
tracer.addCount("curator.session.expired", 1);Monitoring Best Practices
Performance Monitoring
// Monitor critical operations
TracerDriver performanceTracer = new TracerDriver() {
@Override
public void addTrace(String name, long time, TimeUnit unit) {
long millis = unit.toMillis(time);
// Alert on slow operations
if (millis > 5000) {
alertingSystem.sendAlert("Slow ZooKeeper operation: " + name + " took " + millis + "ms");
}
// Record metrics
metricsSystem.recordTiming(name, millis);
}
@Override
public void addCount(String name, int increment) {
// Track operation counts
metricsSystem.incrementCounter(name, increment);
// Alert on high error rates
if (name.contains("error") || name.contains("timeout")) {
errorRateTracker.recordError(name);
}
}
};Health Check Integration
// Use tracing data for health checks
public class CuratorHealthCheck {
private final AtomicLong lastSuccessfulOperation = new AtomicLong(System.currentTimeMillis());
private final TracerDriver healthTracer = new TracerDriver() {
@Override
public void addTrace(String name, long time, TimeUnit unit) {
if (!name.contains("error")) {
lastSuccessfulOperation.set(System.currentTimeMillis());
}
}
@Override
public void addCount(String name, int increment) {
if (name.contains("success")) {
lastSuccessfulOperation.set(System.currentTimeMillis());
}
}
};
public boolean isHealthy() {
long timeSinceLastSuccess = System.currentTimeMillis() - lastSuccessfulOperation.get();
return timeSinceLastSuccess < 30000; // Healthy if successful operation within 30s
}
}Install with Tessl CLI
npx tessl i tessl/maven-org-apache-curator--curator-client