google-site-verification: google61fe8ba583a51912.html
MACRO NEPAL
Canary Testing Framework in Java: Complete Guide
awiskar acharya
November 19, 2025
10:06 am

Introduction

Canary testing is a deployment strategy where new software versions are released to a small subset of users before rolling out to the entire user base. This framework provides comprehensive canary testing capabilities for Java applications.

Dependencies and Setup

1. Maven Dependencies

<properties> <spring-boot.version>3.2.0</spring-boot.version> <micrometer.version>1.12.0</micrometer.version> <resilience4j.version>2.1.0</resilience4j.version> </properties> <dependencies> <!-- Spring Boot --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-aop</artifactId> <version>${spring-boot.version}</version> </dependency> <!-- Metrics and Monitoring --> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-core</artifactId> <version>${micrometer.version}</version> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> <version>${micrometer.version}</version> </dependency> <!-- Resilience4j for Circuit Breaker --> <dependency> <groupId>io.github.resilience4j</groupId> <artifactId>resilience4j-spring-boot3</artifactId> <version>${resilience4j.version}</version> </dependency> <dependency> <groupId>io.github.resilience4j</groupId> <artifactId>resilience4j-micrometer</artifactId> <version>${resilience4j.version}</version> </dependency> <!-- Testing --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <version>${spring-boot.version}</version> <scope>test</scope> </dependency> </dependencies>

Core Framework Models

2. Canary Configuration Models

package com.example.canary.model; import com.fasterxml.jackson.annotation.JsonInclude; import java.time.Duration; import java.util.Map; @JsonInclude(JsonInclude.Include.NON_NULL) public class CanaryConfig { private String id; private String name; private String description; private TrafficConfig traffic; private MetricsConfig metrics; private RolloutConfig rollout; private Map<String, Object> customProperties; // Constructors public CanaryConfig() {} public CanaryConfig(String id, String name, TrafficConfig traffic, MetricsConfig metrics, RolloutConfig rollout) { this.id = id; this.name = name; this.traffic = traffic; this.metrics = metrics; this.rollout = rollout; } // Getters and Setters public String getId() { return id; } public void setId(String id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getDescription() { return description; } public void setDescription(String description) { this.description = description; } public TrafficConfig getTraffic() { return traffic; } public void setTraffic(TrafficConfig traffic) { this.traffic = traffic; } public MetricsConfig getMetrics() { return metrics; } public void setMetrics(MetricsConfig metrics) { this.metrics = metrics; } public RolloutConfig getRollout() { return rollout; } public void setRollout(RolloutConfig rollout) { this.rollout = rollout; } public Map<String, Object> getCustomProperties() { return customProperties; } public void setCustomProperties(Map<String, Object> customProperties) { this.customProperties = customProperties; } @JsonInclude(JsonInclude.Include.NON_NULL) public static class TrafficConfig { private int initialPercentage = 10; private int maxPercentage = 50; private Duration evaluationInterval = Duration.ofMinutes(5); private String routingStrategy = "RANDOM"; // RANDOM, USER_ID, SESSION_ID, HEADER // Getters and Setters public int getInitialPercentage() { return initialPercentage; } public void setInitialPercentage(int initialPercentage) { this.initialPercentage = initialPercentage; } public int getMaxPercentage() { return maxPercentage; } public void setMaxPercentage(int maxPercentage) { this.maxPercentage = maxPercentage; } public Duration getEvaluationInterval() { return evaluationInterval; } public void setEvaluationInterval(Duration evaluationInterval) { this.evaluationInterval = evaluationInterval; } public String getRoutingStrategy() { return routingStrategy; } public void setRoutingStrategy(String routingStrategy) { this.routingStrategy = routingStrategy; } } @JsonInclude(JsonInclude.Include.NON_NULL) public static class MetricsConfig { private Duration collectionWindow = Duration.ofMinutes(5); private double errorRateThreshold = 2.0; // percentage private double p95LatencyThreshold = 500.0; // milliseconds private double throughputThreshold = 100.0; // requests per second private boolean enableCustomMetrics = false; // Getters and Setters public Duration getCollectionWindow() { return collectionWindow; } public void setCollectionWindow(Duration collectionWindow) { this.collectionWindow = collectionWindow; } public double getErrorRateThreshold() { return errorRateThreshold; } public void setErrorRateThreshold(double errorRateThreshold) { this.errorRateThreshold = errorRateThreshold; } public double getP95LatencyThreshold() { return p95LatencyThreshold; } public void setP95LatencyThreshold(double p95LatencyThreshold) { this.p95LatencyThreshold = p95LatencyThreshold; } public double getThroughputThreshold() { return throughputThreshold; } public void setThroughputThreshold(double throughputThreshold) { this.throughputThreshold = throughputThreshold; } public boolean isEnableCustomMetrics() { return enableCustomMetrics; } public void setEnableCustomMetrics(boolean enableCustomMetrics) { this.enableCustomMetrics = enableCustomMetrics; } } @JsonInclude(JsonInclude.Include.NON_NULL) public static class RolloutConfig { private Duration stepInterval = Duration.ofMinutes(10); private int stepPercentage = 10; private boolean autoPromote = true; private boolean autoRollback = true; private int consecutiveSuccessSteps = 3; // Getters and Setters public Duration getStepInterval() { return stepInterval; } public void setStepInterval(Duration stepInterval) { this.stepInterval = stepInterval; } public int getStepPercentage() { return stepPercentage; } public void setStepPercentage(int stepPercentage) { this.stepPercentage = stepPercentage; } public boolean isAutoPromote() { return autoPromote; } public void setAutoPromote(boolean autoPromote) { this.autoPromote = autoPromote; } public boolean isAutoRollback() { return autoRollback; } public void setAutoRollback(boolean autoRollback) { this.autoRollback = autoRollback; } public int getConsecutiveSuccessSteps() { return consecutiveSuccessSteps; } public void setConsecutiveSuccessSteps(int consecutiveSuccessSteps) { this.consecutiveSuccessSteps = consecutiveSuccessSteps; } } }

3. Canary Deployment State

package com.example.canary.model; import java.time.LocalDateTime; import java.util.Map; public class CanaryDeployment { private String id; private String canaryConfigId; private String serviceName; private String baselineVersion; private String canaryVersion; private DeploymentStatus status; private int currentTrafficPercentage; private LocalDateTime startTime; private LocalDateTime lastEvaluationTime; private Map<String, Object> metrics; private Map<String, Object> metadata; // Constructors public CanaryDeployment() {} public CanaryDeployment(String id, String canaryConfigId, String serviceName, String baselineVersion, String canaryVersion) { this.id = id; this.canaryConfigId = canaryConfigId; this.serviceName = serviceName; this.baselineVersion = baselineVersion; this.canaryVersion = canaryVersion; this.status = DeploymentStatus.PENDING; this.currentTrafficPercentage = 0; this.startTime = LocalDateTime.now(); } // Getters and Setters public String getId() { return id; } public void setId(String id) { this.id = id; } public String getCanaryConfigId() { return canaryConfigId; } public void setCanaryConfigId(String canaryConfigId) { this.canaryConfigId = canaryConfigId; } public String getServiceName() { return serviceName; } public void setServiceName(String serviceName) { this.serviceName = serviceName; } public String getBaselineVersion() { return baselineVersion; } public void setBaselineVersion(String baselineVersion) { this.baselineVersion = baselineVersion; } public String getCanaryVersion() { return canaryVersion; } public void setCanaryVersion(String canaryVersion) { this.canaryVersion = canaryVersion; } public DeploymentStatus getStatus() { return status; } public void setStatus(DeploymentStatus status) { this.status = status; } public int getCurrentTrafficPercentage() { return currentTrafficPercentage; } public void setCurrentTrafficPercentage(int currentTrafficPercentage) { this.currentTrafficPercentage = currentTrafficPercentage; } public LocalDateTime getStartTime() { return startTime; } public void setStartTime(LocalDateTime startTime) { this.startTime = startTime; } public LocalDateTime getLastEvaluationTime() { return lastEvaluationTime; } public void setLastEvaluationTime(LocalDateTime lastEvaluationTime) { this.lastEvaluationTime = lastEvaluationTime; } public Map<String, Object> getMetrics() { return metrics; } public void setMetrics(Map<String, Object> metrics) { this.metrics = metrics; } public Map<String, Object> getMetadata() { return metadata; } public void setMetadata(Map<String, Object> metadata) { this.metadata = metadata; } public enum DeploymentStatus { PENDING, RUNNING, PROMOTED, ROLLED_BACK, FAILED, PAUSED } }

4. Canary Metrics and Analysis

package com.example.canary.model; import java.time.LocalDateTime; import java.util.Map; public class CanaryAnalysis { private String deploymentId; private LocalDateTime analysisTime; private AnalysisResult result; private Map<String, MetricAnalysis> metrics; private String recommendation; private double confidenceScore; // Constructors public CanaryAnalysis() {} public CanaryAnalysis(String deploymentId, AnalysisResult result) { this.deploymentId = deploymentId; this.analysisTime = LocalDateTime.now(); this.result = result; } // Getters and Setters public String getDeploymentId() { return deploymentId; } public void setDeploymentId(String deploymentId) { this.deploymentId = deploymentId; } public LocalDateTime getAnalysisTime() { return analysisTime; } public void setAnalysisTime(LocalDateTime analysisTime) { this.analysisTime = analysisTime; } public AnalysisResult getResult() { return result; } public void setResult(AnalysisResult result) { this.result = result; } public Map<String, MetricAnalysis> getMetrics() { return metrics; } public void setMetrics(Map<String, MetricAnalysis> metrics) { this.metrics = metrics; } public String getRecommendation() { return recommendation; } public void setRecommendation(String recommendation) { this.recommendation = recommendation; } public double getConfidenceScore() { return confidenceScore; } public void setConfidenceScore(double confidenceScore) { this.confidenceScore = confidenceScore; } public enum AnalysisResult { PASS, FAIL, INCONCLUSIVE, NEEDS_MORE_DATA } public static class MetricAnalysis { private String name; private double baselineValue; private double canaryValue; private double threshold; private boolean passed; private double deviation; private String unit; // Constructors public MetricAnalysis() {} public MetricAnalysis(String name, double baselineValue, double canaryValue, double threshold, String unit) { this.name = name; this.baselineValue = baselineValue; this.canaryValue = canaryValue; this.threshold = threshold; this.unit = unit; this.deviation = calculateDeviation(); this.passed = Math.abs(deviation) <= threshold; } private double calculateDeviation() { if (baselineValue == 0) return 0; return ((canaryValue - baselineValue) / baselineValue) * 100; } // Getters and Setters public String getName() { return name; } public void setName(String name) { this.name = name; } public double getBaselineValue() { return baselineValue; } public void setBaselineValue(double baselineValue) { this.baselineValue = baselineValue; } public double getCanaryValue() { return canaryValue; } public void setCanaryValue(double canaryValue) { this.canaryValue = canaryValue; } public double getThreshold() { return threshold; } public void setThreshold(double threshold) { this.threshold = threshold; } public boolean isPassed() { return passed; } public void setPassed(boolean passed) { this.passed = passed; } public double getDeviation() { return deviation; } public void setDeviation(double deviation) { this.deviation = deviation; } public String getUnit() { return unit; } public void setUnit(String unit) { this.unit = unit; } } }

Core Framework Components

5. Traffic Routing Service

package com.example.canary.service; import com.example.canary.model.CanaryConfig; import com.example.canary.model.CanaryDeployment; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Service; import javax.servlet.http.HttpServletRequest; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ThreadLocalRandom; @Service public class TrafficRoutingService { private static final Logger log = LoggerFactory.getLogger(TrafficRoutingService.class); private final Map<String, CanaryDeployment> activeDeployments = new ConcurrentHashMap<>(); private final Map<String, CanaryConfig> canaryConfigs = new ConcurrentHashMap<>(); public boolean shouldRouteToCanary(String deploymentId, HttpServletRequest request) { CanaryDeployment deployment = activeDeployments.get(deploymentId); if (deployment == null || deployment.getCurrentTrafficPercentage() <= 0) { return false; } CanaryConfig config = canaryConfigs.get(deployment.getCanaryConfigId()); if (config == null) { log.warn("No configuration found for deployment: {}", deploymentId); return false; } return evaluateRouting(deployment, config, request); } private boolean evaluateRouting(CanaryDeployment deployment, CanaryConfig config, HttpServletRequest request) { String routingStrategy = config.getTraffic().getRoutingStrategy(); int trafficPercentage = deployment.getCurrentTrafficPercentage(); switch (routingStrategy.toUpperCase()) { case "RANDOM": return randomRouting(trafficPercentage); case "USER_ID": return userIdRouting(request, trafficPercentage); case "SESSION_ID": return sessionIdRouting(request, trafficPercentage); case "HEADER": return headerBasedRouting(request, trafficPercentage, config.getTraffic().getCustomProperties()); default: log.warn("Unknown routing strategy: {}, falling back to random", routingStrategy); return randomRouting(trafficPercentage); } } private boolean randomRouting(int trafficPercentage) { return ThreadLocalRandom.current().nextInt(100) < trafficPercentage; } private boolean userIdRouting(HttpServletRequest request, int trafficPercentage) { String userId = extractUserId(request); if (userId == null) { return randomRouting(trafficPercentage); } // Use consistent hashing for user-based routing int hash = Math.abs(userId.hashCode()) % 100; return hash < trafficPercentage; } private boolean sessionIdRouting(HttpServletRequest request, int trafficPercentage) { String sessionId = request.getSession(false) != null ? request.getSession().getId() : null; if (sessionId == null) { return randomRouting(trafficPercentage); } int hash = Math.abs(sessionId.hashCode()) % 100; return hash < trafficPercentage; } private boolean headerBasedRouting(HttpServletRequest request, int trafficPercentage, Map<String, Object> customProperties) { String headerName = (String) customProperties.get("routingHeader"); if (headerName == null) { return randomRouting(trafficPercentage); } String headerValue = request.getHeader(headerName); if (headerValue == null) { return randomRouting(trafficPercentage); } int hash = Math.abs(headerValue.hashCode()) % 100; return hash < trafficPercentage; } private String extractUserId(HttpServletRequest request) { // Extract user ID from authentication context, header, or parameter // This is application-specific return request.getHeader("X-User-ID"); } public void registerDeployment(CanaryDeployment deployment, CanaryConfig config) { activeDeployments.put(deployment.getId(), deployment); canaryConfigs.put(deployment.getCanaryConfigId(), config); log.info("Registered canary deployment: {} with {}% traffic", deployment.getId(), deployment.getCurrentTrafficPercentage()); } public void updateTrafficPercentage(String deploymentId, int newPercentage) { CanaryDeployment deployment = activeDeployments.get(deploymentId); if (deployment != null) { deployment.setCurrentTrafficPercentage(newPercentage); log.info("Updated traffic percentage for deployment {} to {}%", deploymentId, newPercentage); } } public void removeDeployment(String deploymentId) { CanaryDeployment deployment = activeDeployments.remove(deploymentId); if (deployment != null) { canaryConfigs.remove(deployment.getCanaryConfigId()); log.info("Removed canary deployment: {}", deploymentId); } } }

6. Metrics Collection Service

package com.example.canary.service; import io.micrometer.core.instrument.Counter; import io.micrometer.core.instrument.MeterRegistry; import io.micrometer.core.instrument.Timer; import org.springframework.stereotype.Service; import java.time.Duration; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.TimeUnit; @Service public class MetricsCollectionService { private final MeterRegistry meterRegistry; private final Map<String, DeploymentMetrics> deploymentMetrics = new ConcurrentHashMap<>(); public MetricsCollectionService(MeterRegistry meterRegistry) { this.meterRegistry = meterRegistry; } public void recordRequest(String deploymentId, String version, boolean isSuccess, long durationMs, String endpoint) { DeploymentMetrics metrics = deploymentMetrics.computeIfAbsent( deploymentId, id -> new DeploymentMetrics(meterRegistry, id)); metrics.recordRequest(version, isSuccess, durationMs, endpoint); } public void recordCustomMetric(String deploymentId, String metricName, double value, String version) { DeploymentMetrics metrics = deploymentMetrics.computeIfAbsent( deploymentId, id -> new DeploymentMetrics(meterRegistry, id)); metrics.recordCustomMetric(metricName, value, version); } public Map<String, Object> getMetricsSnapshot(String deploymentId) { DeploymentMetrics metrics = deploymentMetrics.get(deploymentId); if (metrics != null) { return metrics.getSnapshot(); } return Map.of(); } public void cleanupMetrics(String deploymentId) { deploymentMetrics.remove(deploymentId); } private static class DeploymentMetrics { private final String deploymentId; private final MeterRegistry meterRegistry; private final Map<String, Counter> requestCounters = new ConcurrentHashMap<>(); private final Map<String, Counter> errorCounters = new ConcurrentHashMap<>(); private final Map<String, Timer> latencyTimers = new ConcurrentHashMap<>(); public DeploymentMetrics(MeterRegistry meterRegistry, String deploymentId) { this.meterRegistry = meterRegistry; this.deploymentId = deploymentId; } public void recordRequest(String version, boolean isSuccess, long durationMs, String endpoint) { String counterKey = version + ":" + endpoint; // Record request count Counter requestCounter = requestCounters.computeIfAbsent(counterKey, key -> Counter.builder("canary.requests") .tag("deployment", deploymentId) .tag("version", version) .tag("endpoint", endpoint) .register(meterRegistry)); requestCounter.increment(); // Record error if applicable if (!isSuccess) { Counter errorCounter = errorCounters.computeIfAbsent(counterKey, key -> Counter.builder("canary.errors") .tag("deployment", deploymentId) .tag("version", version) .tag("endpoint", endpoint) .register(meterRegistry)); errorCounter.increment(); } // Record latency Timer latencyTimer = latencyTimers.computeIfAbsent(counterKey, key -> Timer.builder("canary.latency") .tag("deployment", deploymentId) .tag("version", version) .tag("endpoint", endpoint) .register(meterRegistry)); latencyTimer.record(durationMs, TimeUnit.MILLISECONDS); } public void recordCustomMetric(String metricName, double value, String version) { meterRegistry.gauge("canary.custom." + metricName, Map.of("deployment", deploymentId, "version", version), value); } public Map<String, Object> getSnapshot() { // This would collect and aggregate metrics from Micrometer // In a real implementation, you'd query Micrometer for specific metrics return Map.of( "deploymentId", deploymentId, "timestamp", System.currentTimeMillis() ); } } }

7. Canary Analysis Engine

package com.example.canary.service; import com.example.canary.model.CanaryAnalysis; import com.example.canary.model.CanaryConfig; import com.example.canary.model.CanaryDeployment; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Service; import java.time.LocalDateTime; import java.util.HashMap; import java.util.Map; @Service public class CanaryAnalysisEngine { private static final Logger log = LoggerFactory.getLogger(CanaryAnalysisEngine.class); private final MetricsCollectionService metricsService; public CanaryAnalysisEngine(MetricsCollectionService metricsService) { this.metricsService = metricsService; } public CanaryAnalysis analyzeDeployment(CanaryDeployment deployment, CanaryConfig config) { log.info("Analyzing canary deployment: {}", deployment.getId()); Map<String, Object> baselineMetrics = getMetricsForVersion(deployment, deployment.getBaselineVersion()); Map<String, Object> canaryMetrics = getMetricsForVersion(deployment, deployment.getCanaryVersion()); Map<String, CanaryAnalysis.MetricAnalysis> metricAnalysis = new HashMap<>(); CanaryAnalysis.AnalysisResult overallResult = CanaryAnalysis.AnalysisResult.PASS; // Analyze error rate CanaryAnalysis.MetricAnalysis errorRateAnalysis = analyzeErrorRate( baselineMetrics, canaryMetrics, config.getMetrics().getErrorRateThreshold()); metricAnalysis.put("error_rate", errorRateAnalysis); if (!errorRateAnalysis.isPassed()) { overallResult = CanaryAnalysis.AnalysisResult.FAIL; } // Analyze latency CanaryAnalysis.MetricAnalysis latencyAnalysis = analyzeLatency( baselineMetrics, canaryMetrics, config.getMetrics().getP95LatencyThreshold()); metricAnalysis.put("p95_latency", latencyAnalysis); if (!latencyAnalysis.isPassed() && overallResult != CanaryAnalysis.AnalysisResult.FAIL) { overallResult = CanaryAnalysis.AnalysisResult.FAIL; } // Analyze throughput CanaryAnalysis.MetricAnalysis throughputAnalysis = analyzeThroughput( baselineMetrics, canaryMetrics, config.getMetrics().getThroughputThreshold()); metricAnalysis.put("throughput", throughputAnalysis); CanaryAnalysis analysis = new CanaryAnalysis(deployment.getId(), overallResult); analysis.setMetrics(metricAnalysis); analysis.setRecommendation(generateRecommendation(analysis, deployment)); analysis.setConfidenceScore(calculateConfidenceScore(metricAnalysis)); log.info("Analysis completed for deployment {}: {}", deployment.getId(), overallResult); return analysis; } private CanaryAnalysis.MetricAnalysis analyzeErrorRate(Map<String, Object> baselineMetrics, Map<String, Object> canaryMetrics, double threshold) { double baselineErrorRate = getMetricValue(baselineMetrics, "error_rate", 0.0); double canaryErrorRate = getMetricValue(canaryMetrics, "error_rate", 0.0); return new CanaryAnalysis.MetricAnalysis( "error_rate", baselineErrorRate, canaryErrorRate, threshold, "%"); } private CanaryAnalysis.MetricAnalysis analyzeLatency(Map<String, Object> baselineMetrics, Map<String, Object> canaryMetrics, double threshold) { double baselineLatency = getMetricValue(baselineMetrics, "p95_latency", 0.0); double canaryLatency = getMetricValue(canaryMetrics, "p95_latency", 0.0); return new CanaryAnalysis.MetricAnalysis( "p95_latency", baselineLatency, canaryLatency, threshold, "ms"); } private CanaryAnalysis.MetricAnalysis analyzeThroughput(Map<String, Object> baselineMetrics, Map<String, Object> canaryMetrics, double threshold) { double baselineThroughput = getMetricValue(baselineMetrics, "throughput", 0.0); double canaryThroughput = getMetricValue(canaryMetrics, "throughput", 0.0); return new CanaryAnalysis.MetricAnalysis( "throughput", baselineThroughput, canaryThroughput, threshold, "rps"); } private double getMetricValue(Map<String, Object> metrics, String metricName, double defaultValue) { Object value = metrics.get(metricName); if (value instanceof Number) { return ((Number) value).doubleValue(); } return defaultValue; } private Map<String, Object> getMetricsForVersion(CanaryDeployment deployment, String version) { // In a real implementation, this would query your metrics backend // For now, return mock data Map<String, Object> metrics = metricsService.getMetricsSnapshot(deployment.getId()); // Add version-specific metrics (this would come from your metrics system) metrics.put("error_rate", Math.random() * 5); // 0-5% error rate metrics.put("p95_latency", 100 + Math.random() * 400); // 100-500ms latency metrics.put("throughput", 50 + Math.random() * 150); // 50-200 requests per second return metrics; } private String generateRecommendation(CanaryAnalysis analysis, CanaryDeployment deployment) { switch (analysis.getResult()) { case PASS: return "Canary is performing well. Consider increasing traffic or promoting."; case FAIL: return "Canary is underperforming. Consider rolling back or reducing traffic."; case INCONCLUSIVE: return "Results are inconclusive. Continue monitoring with current traffic."; case NEEDS_MORE_DATA: return "Insufficient data for analysis. Continue data collection."; default: return "Unknown analysis result."; } } private double calculateConfidenceScore(Map<String, CanaryAnalysis.MetricAnalysis> metrics) { if (metrics.isEmpty()) return 0.0; double totalWeight = 0.0; double weightedScore = 0.0; for (CanaryAnalysis.MetricAnalysis metric : metrics.values()) { double weight = getMetricWeight(metric.getName()); double score = metric.isPassed() ? 1.0 : 0.0; weightedScore += weight * score; totalWeight += weight; } return totalWeight > 0 ? (weightedScore / totalWeight) * 100 : 0.0; } private double getMetricWeight(String metricName) { switch (metricName) { case "error_rate": return 0.5; // Highest weight for errors case "p95_latency": return 0.3; // Medium weight for latency case "throughput": return 0.2; // Lower weight for throughput default: return 0.1; } } }

8. Canary Deployment Manager

package com.example.canary.service; import com.example.canary.model.*; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Service; import java.time.LocalDateTime; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.atomic.AtomicInteger; @Service public class CanaryDeploymentManager { private static final Logger log = LoggerFactory.getLogger(CanaryDeploymentManager.class); private final TrafficRoutingService routingService; private final CanaryAnalysisEngine analysisEngine; private final MetricsCollectionService metricsService; private final Map<String, CanaryDeployment> activeDeployments = new ConcurrentHashMap<>(); private final Map<String, CanaryConfig> canaryConfigs = new ConcurrentHashMap<>(); private final AtomicInteger successStepCount = new AtomicInteger(0); public CanaryDeploymentManager(TrafficRoutingService routingService, CanaryAnalysisEngine analysisEngine, MetricsCollectionService metricsService) { this.routingService = routingService; this.analysisEngine = analysisEngine; this.metricsService = metricsService; } public CanaryDeployment startCanaryDeployment(String configId, String serviceName, String baselineVersion, String canaryVersion) { CanaryConfig config = canaryConfigs.get(configId); if (config == null) { throw new IllegalArgumentException("Canary configuration not found: " + configId); } String deploymentId = generateDeploymentId(serviceName, canaryVersion); CanaryDeployment deployment = new CanaryDeployment( deploymentId, configId, serviceName, baselineVersion, canaryVersion); deployment.setCurrentTrafficPercentage(config.getTraffic().getInitialPercentage()); deployment.setStatus(CanaryDeployment.DeploymentStatus.RUNNING); activeDeployments.put(deploymentId, deployment); routingService.registerDeployment(deployment, config); log.info("Started canary deployment: {} with {}% traffic", deploymentId, deployment.getCurrentTrafficPercentage()); return deployment; } public void updateTrafficPercentage(String deploymentId, int newPercentage) { CanaryDeployment deployment = activeDeployments.get(deploymentId); if (deployment != null) { CanaryConfig config = canaryConfigs.get(deployment.getCanaryConfigId()); int maxPercentage = config.getTraffic().getMaxPercentage(); if (newPercentage > maxPercentage) { log.warn("Requested traffic percentage {} exceeds maximum {}. Using maximum.", newPercentage, maxPercentage); newPercentage = maxPercentage; } deployment.setCurrentTrafficPercentage(newPercentage); routingService.updateTrafficPercentage(deploymentId, newPercentage); log.info("Updated traffic percentage for deployment {} to {}%", deploymentId, newPercentage); } } public void promoteDeployment(String deploymentId) { CanaryDeployment deployment = activeDeployments.get(deploymentId); if (deployment != null) { deployment.setStatus(CanaryDeployment.DeploymentStatus.PROMOTED); routingService.removeDeployment(deploymentId); metricsService.cleanupMetrics(deploymentId); log.info("Promoted canary deployment: {}", deploymentId); } } public void rollbackDeployment(String deploymentId) { CanaryDeployment deployment = activeDeployments.get(deploymentId); if (deployment != null) { deployment.setStatus(CanaryDeployment.DeploymentStatus.ROLLED_BACK); routingService.removeDeployment(deploymentId); metricsService.cleanupMetrics(deploymentId); log.info("Rolled back canary deployment: {}", deploymentId); } } @Scheduled(fixedRate = 300000) // Run every 5 minutes public void evaluateActiveDeployments() { for (CanaryDeployment deployment : activeDeployments.values()) { if (deployment.getStatus() != CanaryDeployment.DeploymentStatus.RUNNING) { continue; } try { evaluateDeployment(deployment); } catch (Exception e) { log.error("Error evaluating deployment: {}", deployment.getId(), e); } } } private void evaluateDeployment(CanaryDeployment deployment) { CanaryConfig config = canaryConfigs.get(deployment.getCanaryConfigId()); if (config == null) { log.warn("No configuration found for deployment: {}", deployment.getId()); return; } CanaryAnalysis analysis = analysisEngine.analyzeDeployment(deployment, config); deployment.setLastEvaluationTime(LocalDateTime.now()); deployment.setMetrics(Map.of("last_analysis", analysis)); log.info("Deployment {} analysis: {}", deployment.getId(), analysis.getResult()); if (config.getRollout().isAutoPromote() || config.getRollout().isAutoRollback()) { handleAutomaticActions(deployment, analysis, config); } } private void handleAutomaticActions(CanaryDeployment deployment, CanaryAnalysis analysis, CanaryConfig config) { switch (analysis.getResult()) { case PASS: handleSuccessfulAnalysis(deployment, config); break; case FAIL: handleFailedAnalysis(deployment, config); break; case INCONCLUSIVE: case NEEDS_MORE_DATA: // No automatic action, continue monitoring break; } } private void handleSuccessfulAnalysis(CanaryDeployment deployment, CanaryConfig config) { successStepCount.incrementAndGet(); if (successStepCount.get() >= config.getRollout().getConsecutiveSuccessSteps()) { int currentTraffic = deployment.getCurrentTrafficPercentage(); int stepPercentage = config.getRollout().getStepPercentage(); int maxPercentage = config.getTraffic().getMaxPercentage(); if (currentTraffic >= maxPercentage) { if (config.getRollout().isAutoPromote()) { promoteDeployment(deployment.getId()); } } else { int newTraffic = Math.min(currentTraffic + stepPercentage, maxPercentage); updateTrafficPercentage(deployment.getId(), newTraffic); successStepCount.set(0); // Reset for next step } } } private void handleFailedAnalysis(CanaryDeployment deployment, CanaryConfig config) { successStepCount.set(0); // Reset success counter if (config.getRollout().isAutoRollback()) { rollbackDeployment(deployment.getId()); log.warn("Automatically rolled back deployment due to failed analysis: {}", deployment.getId()); } else { // Reduce traffic or take other mitigation actions int currentTraffic = deployment.getCurrentTrafficPercentage(); int newTraffic = Math.max(0, currentTraffic - config.getRollout().getStepPercentage()); updateTrafficPercentage(deployment.getId(), newTraffic); log.warn("Reduced traffic for deployment {} to {}% due to failed analysis", deployment.getId(), newTraffic); } } private String generateDeploymentId(String serviceName, String version) { return serviceName + "-" + version + "-" + System.currentTimeMillis(); } public void registerConfig(CanaryConfig config) { canaryConfigs.put(config.getId(), config); log.info("Registered canary configuration: {}", config.getId()); } public CanaryDeployment getDeployment(String deploymentId) { return activeDeployments.get(deploymentId); } public Map<String, CanaryDeployment> getActiveDeployments() { return Map.copyOf(activeDeployments); } }

Spring Boot Integration

9. Web Interceptor for Traffic Routing

package com.example.canary.interceptor; import com.example.canary.service.TrafficRoutingService; import org.springframework.stereotype.Component; import org.springframework.web.servlet.HandlerInterceptor; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; @Component public class CanaryRoutingInterceptor implements HandlerInterceptor { private final TrafficRoutingService routingService; private final String CANARY_DEPLOYMENT_HEADER = "X-Canary-Deployment"; private final String CANARY_VERSION_HEADER = "X-Canary-Version"; public CanaryRoutingInterceptor(TrafficRoutingService routingService) { this.routingService = routingService; } @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // Check if request should be routed to canary // This is a simplified example - in reality, you'd have multiple deployments String deploymentId = getActiveDeploymentId(request); if (deploymentId != null && routingService.shouldRouteToCanary(deploymentId, request)) { response.setHeader(CANARY_DEPLOYMENT_HEADER, deploymentId); // In a real scenario, you might route to a different service instance } return true; } private String getActiveDeploymentId(HttpServletRequest request) { // In a real implementation, you'd determine which deployment is active // based on the request path, service, or other criteria return "example-deployment-1"; } }

10. Configuration

package com.example.canary.config; import com.example.canary.interceptor.CanaryRoutingInterceptor; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @Configuration public class WebConfig implements WebMvcConfigurer { private final CanaryRoutingInterceptor canaryRoutingInterceptor; public WebConfig(CanaryRoutingInterceptor canaryRoutingInterceptor) { this.canaryRoutingInterceptor = canaryRoutingInterceptor; } @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(canaryRoutingInterceptor) .addPathPatterns("/api/**"); } }

REST API Controllers

11. Canary Management API

package com.example.canary.controller; import com.example.canary.model.CanaryConfig; import com.example.canary.model.CanaryDeployment; import com.example.canary.service.CanaryDeploymentManager; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import java.util.Map; @RestController @RequestMapping("/api/canary") public class CanaryController { private final CanaryDeploymentManager deploymentManager; public CanaryController(CanaryDeploymentManager deploymentManager) { this.deploymentManager = deploymentManager; } @PostMapping("/config") public ResponseEntity<CanaryConfig> createConfig(@RequestBody CanaryConfig config) { deploymentManager.registerConfig(config); return ResponseEntity.ok(config); } @PostMapping("/deployments") public ResponseEntity<CanaryDeployment> startDeployment( @RequestBody StartDeploymentRequest request) { CanaryDeployment deployment = deploymentManager.startCanaryDeployment( request.getConfigId(), request.getServiceName(), request.getBaselineVersion(), request.getCanaryVersion() ); return ResponseEntity.ok(deployment); } @PutMapping("/deployments/{deploymentId}/traffic") public ResponseEntity<Map<String, Object>> updateTraffic( @PathVariable String deploymentId, @RequestBody UpdateTrafficRequest request) { deploymentManager.updateTrafficPercentage(deploymentId, request.getPercentage()); return ResponseEntity.ok(Map.of( "deploymentId", deploymentId, "trafficPercentage", request.getPercentage(), "status", "updated" )); } @PostMapping("/deployments/{deploymentId}/promote") public ResponseEntity<Map<String, String>> promoteDeployment( @PathVariable String deploymentId) { deploymentManager.promoteDeployment(deploymentId); return ResponseEntity.ok(Map.of( "deploymentId", deploymentId, "status", "promoted" )); } @PostMapping("/deployments/{deploymentId}/rollback") public ResponseEntity<Map<String, String>> rollbackDeployment( @PathVariable String deploymentId) { deploymentManager.rollbackDeployment(deploymentId); return ResponseEntity.ok(Map.of( "deploymentId", deploymentId, "status", "rolled_back" )); } @GetMapping("/deployments/{deploymentId}") public ResponseEntity<CanaryDeployment> getDeployment( @PathVariable String deploymentId) { CanaryDeployment deployment = deploymentManager.getDeployment(deploymentId); if (deployment != null) { return ResponseEntity.ok(deployment); } else { return ResponseEntity.notFound().build(); } } @GetMapping("/deployments") public ResponseEntity<Map<String, CanaryDeployment>> getActiveDeployments() { return ResponseEntity.ok(deploymentManager.getActiveDeployments()); } // Request DTOs public static class StartDeploymentRequest { private String configId; private String serviceName; private String baselineVersion; private String canaryVersion; // Getters and Setters public String getConfigId() { return configId; } public void setConfigId(String configId) { this.configId = configId; } public String getServiceName() { return serviceName; } public void setServiceName(String serviceName) { this.serviceName = serviceName; } public String getBaselineVersion() { return baselineVersion; } public void setBaselineVersion(String baselineVersion) { this.baselineVersion = baselineVersion; } public String getCanaryVersion() { return canaryVersion; } public void setCanaryVersion(String canaryVersion) { this.canaryVersion = canaryVersion; } } public static class UpdateTrafficRequest { private int percentage; // Getters and Setters public int getPercentage() { return percentage; } public void setPercentage(int percentage) { this.percentage = percentage; } } }

Testing

12. Unit Tests

package com.example.canary.test; import com.example.canary.model.CanaryConfig; import com.example.canary.model.CanaryDeployment; import com.example.canary.service.CanaryAnalysisEngine; import com.example.canary.service.CanaryDeploymentManager; import com.example.canary.service.MetricsCollectionService; import com.example.canary.service.TrafficRoutingService; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; import static org.assertj.core.api.Assertions.assertThat; import static org.mockito.ArgumentMatchers.any; import static org.mockito.ArgumentMatchers.anyString; import static org.mockito.Mockito.*; @ExtendWith(MockitoExtension.class) class CanaryDeploymentManagerTest { @Mock private TrafficRoutingService routingService; @Mock private CanaryAnalysisEngine analysisEngine; @Mock private MetricsCollectionService metricsService; private CanaryDeploymentManager deploymentManager; private CanaryConfig testConfig; @BeforeEach void setUp() { deploymentManager = new CanaryDeploymentManager( routingService, analysisEngine, metricsService); testConfig = new CanaryConfig(); testConfig.setId("test-config"); testConfig.setName("Test Configuration"); CanaryConfig.TrafficConfig trafficConfig = new CanaryConfig.TrafficConfig(); trafficConfig.setInitialPercentage(10); trafficConfig.setMaxPercentage(50); testConfig.setTraffic(trafficConfig); deploymentManager.registerConfig(testConfig); } @Test void testStartCanaryDeployment() { // When CanaryDeployment deployment = deploymentManager.startCanaryDeployment( "test-config", "test-service", "v1.0.0", "v1.1.0"); // Then assertThat(deployment).isNotNull(); assertThat(deployment.getServiceName()).isEqualTo("test-service"); assertThat(deployment.getCurrentTrafficPercentage()).isEqualTo(10); assertThat(deployment.getStatus()).isEqualTo(CanaryDeployment.DeploymentStatus.RUNNING); verify(routingService).registerDeployment(any(CanaryDeployment.class), any(CanaryConfig.class)); } @Test void testUpdateTrafficPercentage() { // Given CanaryDeployment deployment = deploymentManager.startCanaryDeployment( "test-config", "test-service", "v1.0.0", "v1.1.0"); // When deploymentManager.updateTrafficPercentage(deployment.getId(), 25); // Then CanaryDeployment updated = deploymentManager.getDeployment(deployment.getId()); assertThat(updated.getCurrentTrafficPercentage()).isEqualTo(25); verify(routingService).updateTrafficPercentage(deployment.getId(), 25); } }

Configuration Files

13. Application Configuration

# application.yml spring: application: name: canary-framework server: port: 8080 management: endpoints: web: exposure: include: health,metrics,prometheus endpoint: health: show-details: always metrics: enabled: true prometheus: enabled: true canary: default: initial-traffic-percentage: 10 max-traffic-percentage: 50 evaluation-interval: PT5M auto-rollback: true auto-promote: true logging: level: com.example.canary: DEBUG

Usage Example

14. Example Canary Deployment

package com.example.canary.example; import com.example.canary.controller.CanaryController; import com.example.canary.model.CanaryConfig; import org.springframework.boot.CommandLineRunner; import org.springframework.stereotype.Component; @Component public class CanaryExample implements CommandLineRunner { private final CanaryController canaryController; public CanaryExample(CanaryController canaryController) { this.canaryController = canaryController; } @Override public void run(String... args) throws Exception { // Create canary configuration CanaryConfig config = new CanaryConfig(); config.setId("user-service-config"); config.setName("User Service Canary Configuration"); config.setDescription("Canary deployment configuration for user service"); CanaryConfig.TrafficConfig trafficConfig = new CanaryConfig.TrafficConfig(); trafficConfig.setInitialPercentage(5); trafficConfig.setMaxPercentage(100); trafficConfig.setRoutingStrategy("USER_ID"); config.setTraffic(trafficConfig); CanaryConfig.MetricsConfig metricsConfig = new CanaryConfig.MetricsConfig(); metricsConfig.setErrorRateThreshold(1.0); metricsConfig.setP95LatencyThreshold(300.0); metricsConfig.setThroughputThreshold(80.0); config.setMetrics(metricsConfig); CanaryConfig.RolloutConfig rolloutConfig = new CanaryConfig.RolloutConfig(); rolloutConfig.setStepInterval(java.time.Duration.ofMinutes(10)); rolloutConfig.setStepPercentage(10); rolloutConfig.setAutoPromote(true); rolloutConfig.setAutoRollback(true); rolloutConfig.setConsecutiveSuccessSteps(2); config.setRollout(rolloutConfig); // Register configuration canaryController.createConfig(config); System.out.println("Canary configuration created: " + config.getId()); } }

Best Practices

  1. Start Small: Begin with low traffic percentages (1-5%)
  2. Monitor Closely: Watch key metrics during canary deployment
  3. Set Clear Thresholds: Define clear pass/fail criteria for metrics
  4. Automate Rollbacks: Implement automatic rollback for critical failures
  5. Use Multiple Metrics: Combine error rates, latency, and business metrics
  6. Test in Staging: Always test canary process in staging first
  7. Document Procedures: Document rollback and escalation procedures
  8. Involve Stakeholders: Keep relevant teams informed during canary deployments

Conclusion

This comprehensive canary testing framework provides:

  • Traffic Routing: Multiple strategies for routing traffic to canary instances
  • Metrics Collection: Comprehensive monitoring of key performance indicators
  • Automated Analysis: Real-time analysis of canary performance vs baseline
  • Progressive Rollout: Automated traffic increase based on success criteria
  • Safety Mechanisms: Automatic rollback for failing deployments
  • REST API: Full management API for canary deployments
  • Spring Integration: Seamless integration with Spring Boot applications

The framework enables safe, controlled deployment of new software versions with minimal risk to production systems.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper