Package com.elastisys.autoscaler.metricstreamers.opentsdb.query

Class OpenTsdbQueryBuilder

  • public class OpenTsdbQueryBuilder
extends java.lang.Object
    An OpenTSDB query builder that uses the builder pattern to construct a query string that can be submitted to a OpenTSDB server endpoint.

    Note that the returned query is not a complete URL. More specifically, it does not include the host/port-part of a full URL. A returned query string may, for instance, look as follows: 

     /q?&m=sum:proc.stat.cpu&ascii&nocache
    The client needs to turn the query string into a full URL by adding protocol, host, and a port.

    The OpenTsdbQueryBuilder supports all functionality offered by the OpenTSDB HTTP API specification.

    Read about metrics and tags and OpenTSDB query exeution to learn more about OpenTSDB's operation.

    • Constructor Detail

    • Method Detail

      • withMetric

        public OpenTsdbQueryBuilder withMetric​(java.lang.String metric)
        Sets the metric for the query being built.
        Parameters:
        metric - The metric for which to retrieve values.
        Returns:
        The builder itself, enabling chaining of build instructions.

      • withAggregator

        public OpenTsdbQueryBuilder withAggregator​(MetricAggregator aggregator)
        Sets the MetricAggregator function used to aggregate values from different time-series of the metric for the query being built.
        Parameters:
        aggregator - The aggregation function to use for aggregating values.
        Returns:
        The builder itself, enabling chaining of build instructions.

      • withDownsamplingSpecification

        public OpenTsdbQueryBuilder withDownsamplingSpecification​(DownsamplingSpecification downsamplingSpecification)
        Adds a down-sampling specification to the query being built.
        Parameters:
        downsamplingSpecification - The down-sampling specification to add.
        Returns:
        The builder itself, enabling chaining of build instructions.

      • withRateConversion

        public OpenTsdbQueryBuilder withRateConversion​(boolean convertToRate)
        Adds a flag indicating whether returned metric values are to be converted to rate. When true, the built query will ask for the change rate of the metric, rather than the absolute values of the metric.
        Parameters:
        convertToRate - A boolean flag that when true causes the built query to ask for the change rate of the metric, rather than the absolute values of the metric.
        Returns:
        The builder itself, enabling chaining of build instructions.

      • withInterval

        public OpenTsdbQueryBuilder withInterval​(org.joda.time.Interval interval)
        Sets the interval of interest, limiting the built query to include only MetricValues reported within the specified points in time.
        Parameters:
        interval - The interval of interest.
        Returns:
        The builder itself, enabling chaining of build instructions.

      • withTags

        public OpenTsdbQueryBuilder withTags​(java.util.Map<java.lang.String,​java.util.List<java.lang.String>> tags)
        Adds a collection of filter tags to the query being built.

        Tags can, for example, be used to filter query results specifying that only MetricValues with a given tag be returned or to specify that MetricValues are to be returned on a per-host basis rather than in aggregated form.

        Read about OpenTSDB query exeution for more details on how to use filter tags.

        As an example, if MetricValues are tagged with a host tag, a host filter tag can be set to the list of hosts for which to return MetricValues. It is also possible to use a wild-card ( *) as value for a given tag, which causes the OpenTSDB system to report all metrics that have the given tag, regardless of value.

        Parameters:
        tags - A mapping between tag keys and the list of requested values for each tag key.
        Returns:
        The builder itself, enabling chaining of build instructions.

      • build

        public java.lang.String build()
                       throws java.lang.RuntimeException
        Builds the query string that has been constructed with the OpenTsdbQueryBuilder's methods. The returned query can be sent (by HTTP GET) to a OpenTSDB server.
        Returns:
        The query string produced by the builder. Note that the returned query is not a complete URL. More specifically, it does not include the host/port-part of a full URL. The client needs to turn the query string into a full URL by adding protocol, host, and a port.
        Throws:
        java.lang.RuntimeException - If the query could not be built.