GH-5686 feat: add query-plan telemetry and tracking plumbing

Author: hmottestad

core/common/iterator/src/main/java/org/eclipse/rdf4j/common/iteration/IndexReportingIterator.java

@@ -21,4 +21,16 @@ public interface IndexReportingIterator {
 
 	String getIndexName();
 
+	default long getSourceRowsScannedActual() {
+		return -1;
+	}
+
+	default long getSourceRowsMatchedActual() {
+		return -1;
+	}
+
+	default long getSourceRowsFilteredActual() {
+		return -1;
+	}
+
 }

core/query/src/main/java/org/eclipse/rdf4j/query/explanation/GenericPlanNode.java

@@ -66,6 +66,19 @@ public class GenericPlanNode {
 	// plans[0..n].totalTimeActual)
 	private Double totalTimeActual;
 
+	// Telemetry counters captured while iterating this node during executed/timed explanations.
+	private Long hasNextCallCountActual;
+	private Long hasNextTrueCountActual;
+	private Long hasNextTimeNanosActual;
+	private Long nextCallCountActual;
+	private Long nextTimeNanosActual;
+	private Long joinRightIteratorsCreatedActual;
+	private Long joinLeftBindingsConsumedActual;
+	private Long joinRightBindingsConsumedActual;
+	private Long sourceRowsScannedActual;
+	private Long sourceRowsMatchedActual;
+	private Long sourceRowsFilteredActual;
+
 	// true if this node introduces a new scope
 	private Boolean newScope;
 
@@ -176,6 +189,116 @@ public void setTotalTimeActual(Double totalTimeActual) {
 		}
 	}
 
+	public Long getHasNextCallCountActual() {
+		return hasNextCallCountActual;
+	}
+
+	public void setHasNextCallCountActual(Long hasNextCallCountActual) {
+		if (hasNextCallCountActual != null && hasNextCallCountActual >= 0) {
+			this.hasNextCallCountActual = hasNextCallCountActual;
+		}
+	}
+
+	public Long getHasNextTrueCountActual() {
+		return hasNextTrueCountActual;
+	}
+
+	public void setHasNextTrueCountActual(Long hasNextTrueCountActual) {
+		if (hasNextTrueCountActual != null && hasNextTrueCountActual >= 0) {
+			this.hasNextTrueCountActual = hasNextTrueCountActual;
+		}
+	}
+
+	public Long getHasNextTimeNanosActual() {
+		return hasNextTimeNanosActual;
+	}
+
+	public void setHasNextTimeNanosActual(Long hasNextTimeNanosActual) {
+		if (hasNextTimeNanosActual != null && hasNextTimeNanosActual >= 0) {
+			this.hasNextTimeNanosActual = hasNextTimeNanosActual;
+		}
+	}
+
+	public Long getNextCallCountActual() {
+		return nextCallCountActual;
+	}
+
+	public void setNextCallCountActual(Long nextCallCountActual) {
+		if (nextCallCountActual != null && nextCallCountActual >= 0) {
+			this.nextCallCountActual = nextCallCountActual;
+		}
+	}
+
+	public Long getNextTimeNanosActual() {
+		return nextTimeNanosActual;
+	}
+
+	public void setNextTimeNanosActual(Long nextTimeNanosActual) {
+		if (nextTimeNanosActual != null && nextTimeNanosActual >= 0) {
+			this.nextTimeNanosActual = nextTimeNanosActual;
+		}
+	}
+
+	public Long getJoinRightIteratorsCreatedActual() {
+		return joinRightIteratorsCreatedActual;
+	}
+
+	public void setJoinRightIteratorsCreatedActual(Long joinRightIteratorsCreatedActual) {
+		if (joinRightIteratorsCreatedActual != null && joinRightIteratorsCreatedActual >= 0) {
+			this.joinRightIteratorsCreatedActual = joinRightIteratorsCreatedActual;
+		}
+	}
+
+	public Long getJoinLeftBindingsConsumedActual() {
+		return joinLeftBindingsConsumedActual;
+	}
+
+	public void setJoinLeftBindingsConsumedActual(Long joinLeftBindingsConsumedActual) {
+		if (joinLeftBindingsConsumedActual != null && joinLeftBindingsConsumedActual >= 0) {
+			this.joinLeftBindingsConsumedActual = joinLeftBindingsConsumedActual;
+		}
+	}
+
+	public Long getJoinRightBindingsConsumedActual() {
+		return joinRightBindingsConsumedActual;
+	}
+
+	public void setJoinRightBindingsConsumedActual(Long joinRightBindingsConsumedActual) {
+		if (joinRightBindingsConsumedActual != null && joinRightBindingsConsumedActual >= 0) {
+			this.joinRightBindingsConsumedActual = joinRightBindingsConsumedActual;
+		}
+	}
+
+	public Long getSourceRowsScannedActual() {
+		return sourceRowsScannedActual;
+	}
+
+	public void setSourceRowsScannedActual(Long sourceRowsScannedActual) {
+		if (sourceRowsScannedActual != null && sourceRowsScannedActual >= 0) {
+			this.sourceRowsScannedActual = sourceRowsScannedActual;
+		}
+	}
+
+	public Long getSourceRowsMatchedActual() {
+		return sourceRowsMatchedActual;
+	}
+
+	public void setSourceRowsMatchedActual(Long sourceRowsMatchedActual) {
+		if (sourceRowsMatchedActual != null && sourceRowsMatchedActual >= 0) {
+			this.sourceRowsMatchedActual = sourceRowsMatchedActual;
+		}
+	}
+
+	public Long getSourceRowsFilteredActual() {
+		return sourceRowsFilteredActual;
+	}
+
+	public void setSourceRowsFilteredActual(Long sourceRowsFilteredActual) {
+		if (sourceRowsFilteredActual != null && sourceRowsFilteredActual >= 0) {
+			this.sourceRowsFilteredActual = sourceRowsFilteredActual;
+		}
+	}
+
 	public void setTimedOut(Boolean timedOut) {
 		this.timedOut = timedOut;
 	}

core/queryalgebra/evaluation/src/main/java/org/eclipse/rdf4j/query/algebra/evaluation/EvaluationStrategy.java

@@ -148,6 +148,14 @@ default void setTrackTime(boolean trackTime) {
 		// no-op for backwards compatibility
 	}
 
+	/**
+	 * Enable or disable time tracking for the query plan.
+	 */
+	@Experimental
+	default boolean isTrackTime() {
+		return false;
+	}
+
 	QueryEvaluationMode getQueryEvaluationMode();
 
 	void setQueryEvaluationMode(QueryEvaluationMode queryEvaluationMode);