+ * This element uses jmeter-prometheus-plugin.
+ *
+ * @since 1.28
+ */
+public class DslPrometheusListener extends BaseListener {
+
+ private final List
+ * By default, this element publishes a default set of metrics in endpoint
+ * http://0.0.0.0:9270/metrics. Use {@link #host(String)} and {@link #port(int)} to change the
+ * endpoint, and {@link #metrics(PrometheusMetric...)} to set your own metrics.
+ *
+ * The default published metrics are:
+ *
+ * Warning: port setting is test plan wide. This means that if you set different values in
+ * different prometheus listeners, then all the metrics will be published in the last set port.
+ *
+ * @param port specifies the port to publish the metrics. By default, it is 9270.
+ * @return the listener instance for further configuration or usage.
+ */
+ public DslPrometheusListener port(int port) {
+ this.port = port;
+ return this;
+ }
+
+ /**
+ * Specifies the host the internal prometheus server whill listen to requests for metrics.
+ *
+ * Warning: host setting is test plan wide. This means that if you set different values in
+ * different prometheus listeners, then all the metrics will be published in the last set host.
+ *
+ * @param host specifies the host to publish the metrics. By default, it is 0.0.0.0.
+ * @return the listener instance for further configuration or usage.
+ */
+ public DslPrometheusListener host(String host) {
+ this.host = host;
+ return this;
+ }
+
+ /**
+ * Specifies a duration to wait after the test run ends, before stop publishing the metrics.
+ *
+ * Warning: It is very important to set this value greater than Prometheus server
+ * scrape_interval to avoid missing metrics at the end of test execution.
+ *
+ * Warning: this setting is test plan wide. This means that if you set different values in
+ * different prometheus listeners, then only the last set value will be used.
+ *
+ * @param duration specifies the duration to wait before stop publishing the metrics. Take into
+ * consideration that the JMeter plugin supports seconds granularity, so, if a
+ * finer value is used, only the provided seconds will be used. By default, it is
+ * set to 10 seconds.
+ * @return the listener instance for further configuration or usage.
+ */
+ public DslPrometheusListener endWait(Duration duration) {
+ this.delay = duration;
+ return this;
+ }
+
+ @Override
+ protected TestElement buildTestElement() {
+ if (metrics.isEmpty()) {
+ metrics(PrometheusMetric.responseTime("ResponseTime", "the response time of samplers")
+ .labels(PrometheusMetric.SAMPLE_LABEL, PrometheusMetric.RESPONSE_CODE)
+ .quantile(0.75, 0.5)
+ .quantile(0.95, 0.1)
+ .quantile(0.99, 0.01)
+ .maxAge(Duration.ofMinutes(1)),
+ PrometheusMetric.successRatio("Ratio", "the success ratio of samplers")
+ .labels(PrometheusMetric.SAMPLE_LABEL, PrometheusMetric.RESPONSE_CODE));
+ }
+ JMeterUtils.setProperty(PrometheusServer.PROMETHEUS_PORT, String.valueOf(port));
+ JMeterUtils.setProperty(PrometheusServer.PROMETHEUS_IP, host);
+ JMeterUtils.setProperty(PrometheusServer.PROMETHEUS_DELAY, String.valueOf(delay.getSeconds()));
+ PrometheusListener ret = new PrometheusListener();
+ ret.setCollectorConfigs(metrics.stream()
+ .map(PrometheusMetric::buildCollectorConfig)
+ .collect(Collectors.toList()));
+ return ret;
+ }
+
+ /**
+ * Allows configuring metrics to be published by the listener.
+ */
+ public abstract static class PrometheusMetric
+ * By default, Prometheus Summary
+ * metrics are collected. Use {@link #labels(String...)},
+ * {@link SummaryPrometheusMetric#quantile(double, double)} or
+ * {@link SummaryPrometheusMetric#quantile(double, double)}{@link
+ * SummaryPrometheusMetric#histogram(double...)} to further configure details on response time
+ * collected metrics.
+ *
+ * @param name specifies the name of the metric.
+ * @return the metric instance for further configuration or usage.
+ */
+ public static SummaryPrometheusMetric responseTime(String name) {
+ return PrometheusMetric.responseTime(name, "");
+ }
+
+ /**
+ * Same as {@link #responseTime(String)} but allows to set a help text.
+ *
+ * @see #responseTime(String)
+ */
+ public static SummaryPrometheusMetric responseTime(String name, String help) {
+ return new SummaryPrometheusMetric(name, help, Measurable.ResponseTime);
+ }
+
+ /**
+ * Configures a metric collect information about samples success and failures.
+ *
+ * Review the JMeter
+ * plugin documentation for more details.
+ *
+ * @param name specifies the name of the metric.
+ * @return the metric instance for further configuration or usage.
+ */
+ public static SuccessRatioPrometheusMetric successRatio(String name) {
+ return PrometheusMetric.successRatio(name, "");
+ }
+
+ /**
+ * Same as {@link #successRatio(String)} but allows to set a help text.
+ *
+ * @see #successRatio(String)
+ */
+ public static SuccessRatioPrometheusMetric successRatio(String name, String help) {
+ return new SuccessRatioPrometheusMetric(name, help, Measurable.SuccessRatio);
+ }
+
+ /**
+ * Add labels that enrich the collected metric data.
+ *
+ * You can use pre-defined values {@link PrometheusMetric#SAMPLE_LABEL} and
+ * {@link PrometheusMetric#RESPONSE_CODE} to get labels for each sample label and response
+ * code.
+ *
+ * Additionally, you can use JMeter variables values as labels. Check this
+ * section of JMeter plugin documentation for more details.
+ *
+ * @param labels specifies the labels to add to the metric.
+ * @return the metric instance for further configuration or usage.
+ */
+ public T labels(String... labels) {
+ this.labels.addAll(Arrays.asList(labels));
+ return (T) this;
+ }
+
+ public ListenerCollectorConfig buildCollectorConfig() {
+ ListenerCollectorConfig ret = new ListenerCollectorConfig();
+ ret.setMetricName(name);
+ ret.setHelp(help);
+ ret.setLabels(labels.toArray(new String[0]));
+ configureCollectorConfig(ret);
+ ret.setListenTo(ListenerCollectorConfig.SAMPLES);
+ ret.setMeasuring(measuring.toString());
+ return ret;
+ }
+
+ protected abstract void configureCollectorConfig(ListenerCollectorConfig config);
+
+ }
+
+ public static class SummaryPrometheusMetric extends PrometheusMetric
+ * Check Prometheus Documentation
+ * for an explanation on differences between using histograms and summaries.
+ *
+ * @param buckets specifies the bucket upper bounds where information is collected. This
+ * determines the granularity of the generated histogram.
+ * @return the metric instance for further configuration or usage.
+ */
+ public HistogramPrometheusMetric histogram(double... buckets) {
+ return new HistogramPrometheusMetric(this.name, this.help, this.measuring, buckets)
+ .labels(this.labels.toArray(new String[0]));
+ }
+
+ /**
+ * Adds a quantile value to calculate for the summary metric.
+ *
+ * @param quantile specifies the quantile value to calculate. Eg: 0.95 for the 95th percentile.
+ * This must be a value between 0 and 1.
+ * @param error specifies the tolerance error for the calculated quantile. Smaller values
+ * require more resources (CPU and RAM). This must be a value between 0 and 1.
+ * Consider using 0.001 for quantiles greater than 0.99 or smaller than 0.01,
+ * and 0.01 or bigger for the rest.
+ * @return the metric instance for further configuration or usage.
+ */
+ public SummaryPrometheusMetric quantile(double quantile, double error) {
+ quantiles += "|" + String.format("%f,%f", quantile, error);
+ return this;
+ }
+
+ /**
+ * Sets the size of the moving time window to calculate the quantiles.
+ *
+ * This value depends on the period of time you want the quantiles calculation to be based on. A
+ * bigger value requires more resources (CPU & RAM).
+ *
+ * @param duration specifies the size of the moving time window. Prometheus supports up to
+ * seconds granularity for the time window, so if you use a more granular value
+ * (like millis) on ly the seconds will be taken into consideration. By default,
+ * this value is set to 1 minute.
+ * @return the metric instance for further configuration or usage.
+ */
+ public SummaryPrometheusMetric maxAge(Duration duration) {
+ maxAge = duration;
+ return this;
+ }
+
+ @Override
+ protected void configureCollectorConfig(ListenerCollectorConfig config) {
+ config.setType(JMeterCollectorType.SUMMARY.toString());
+ quantiles = !quantiles.isEmpty() ? quantiles.substring(1) : "";
+ quantiles += ";" + maxAge.getSeconds();
+ config.setQuantileOrBucket(quantiles);
+ }
+
+ }
+
+ public static class HistogramPrometheusMetric extends
+ PrometheusMetric{@code
+ * PrometheusMetric.responseTime("ResponseTime", "the response time of samplers")
+ * .labels(PrometheusMetric.SAMPLE_LABEL, PrometheusMetric.RESPONSE_CODE)
+ * .quantile(0.75, 0.5)
+ * .quantile(0.95, 0.1)
+ * .quantile(0.99, 0.01)
+ * .maxAge(Duration.ofMinutes(1)),
+ * PrometheusMetric.successRatio("Ratio", "the success ratio of samplers")
+ * .labels(PrometheusMetric.SAMPLE_LABEL, PrometheusMetric.RESPONSE_CODE)
+ * }
+ *
+ * @return the listener instance for further configuration or usage.
+ */
+ public static DslPrometheusListener prometheusListener() {
+ return new DslPrometheusListener();
+ }
+
+ /**
+ * Specifies a custom set of metrics to publish.
+ *
+ * @param metrics specifies the set of metrics to publish.
+ * @return the listener instance for further configuration or usage.
+ * @see PrometheusMetric
+ */
+ public DslPrometheusListener metrics(PrometheusMetric... metrics) {
+ this.metrics.addAll(Arrays.asList(metrics));
+ return this;
+ }
+
+ /**
+ * Specifies the port where to publish the metrics.
+ *