LogoDark mode logo
LogoDark mode logo
Contact SupportLoading Light/Dark Toggle

Data sources

data sourcesprometheus plugin

Prometheus plugin

The Prometheus plugin enables you to query data from your Prometheus environment for use in your dashboards, analytics and monitoring.

For more information about what this plugin does and the data streams it retrieves, see:

Prometheus

Hybrid plugin

The Prometheus plugin is a "hybrid" plugin, meaning it is available in SquaredUp as both a cloud and an on-prem plugin.

  • Use the cloud plugin if your Prometheus instance is available on the internet. You do not need to configure a relay agent.
  • Use the on-prem plugin to access a Prometheus instance that is on a private network and is not publicly accessible. You will need to configure a relay agent before you configure the Prometheus on-prem plugin.

    An on-prem data source uses a relay agent to connect SquaredUp to a data source running on your internal network.

    A relay agent is installed on a server on your internal network, and has access to your data source.

    Using a relay agent means that you don't need to open your firewall to allow access.

Adding a data source

To add a data source click on the + next to Data Sources on the left-hand menu in SquaredUp. Search for the data source and click on it to open the Configure data source page.

Before you start

If you are adding a plugin marked as On-Prem, you will need a relay agent that can access the server hosting your on-prem data source. You do not need a relay agent for cloud plugins.

If you have already created a relay agent in SquaredUp that can access this data source, then you can skip this step and choose the agent group you want to use while Configuring the data source.

You can install an agent on either Windows or Linux:

  • Configuring an agent (Windows platforms)
  • Configuring an agent (Linux platforms)

Object Indexing

Prometheus time series are described by a set of labels. These labels can be indexed by SquaredUp to make it easier to query, explore and correlate metrics.

The indexed labels are stored in SquaredUp as objects, making it easier to query data, correlate Prometheus data with other data sources, and explore the data interactively. For example, when the job label is indexed, an object is created for each unique value, such as prometheus-local.

If Index OpenTelemetry labels is selected when you add a Prometheus data source to SquaredUp, then additional labels that conform to the OpenTelemetry Semantic Conventions for resources are also indexed. For example, the k8s_pod_name label will be indexed as Kubernetes Pod objects. See https://opentelemetry.io/docs/specs/semconv/resource/ for more examples of resource labels.

These objects can then be selected in the tile editor when using the Simple Query data stream. They can also be viewed in the map, and you can even use them to configure custom correlations between Prometheus objects and objects from other data sources.

To index custom labels that are not automatically indexed by selecting Index OpenTelemetry labels, select the Index custom labels option when configuring the data source.

Configuring the data source

  1. Display name:
    Enter a display name for the data source. If connecting to multiple Prometheus instances, you may want to give this data source a more descriptive name such as Prometheus Prod.
  2. Agent group:
    Select the Agent Group that contains the agent(s) you want to use.

    This field will only appear if you are adding the on-prem plugin.

  3. Prometheus URL:
    Enter the URL of your Prometheus instance. Use the On-prem version to access a Prometheus instance that is not publicly accessible.
  4. Authentication type:
    Select one of the following authentication types, used to access your server, from the Query Type field:
    • None: No authentication is required.
    • API token: You must enter the API authentication token in the API Token field.
    • Basic authentication: You must enter a Username and Password in the corresponding fields.
  5. Ignore certificate errors:
    If you activate this checkbox the data source will ignore certificate errors when accessing the server. This is useful if you have self-signed certificates.

  6. Enable object indexing:
    Select to index Prometheus labels as objects in SquaredUp. Indexing labels as objects makes it easier to correlate, explore and query your Prometheus data (see Object indexing). Selecting this option will, at a minimum, index Prometheus jobs (the "job" label). The following options display:
    1. Import common Kubernetes labels:
      Select to index labels commonly used for Kubernetes environments. The indexed labels are compatible with the Prometheus example config for Kubernetes.
    2. Index OpenTelemetry labels:
      Select to index Open Telemetry Semantic Conventions labels. For example, the k8s_pod_name label will be indexed as Kubernetes Pod objects. For more information on Open Telemetry Semantic Conventions, see https://opentelemetry.io/docs/specs/semconv/resource/.
    3. Index custom labels:
      Select to index custom labels as. Custom labels are configured using the following JSON format:
      [
        {
          "labels": ["label1"],
          "type": "my type"    
        }
      ]
  7. (Optional) Restrict access to this data source:
    You can enable this option if you only want certain users or groups to have access to the data source, or the permission to link it to new workspaces. See data source access control for more information.

    The term data source here really means data source instance. For example, a user may configure two instances of the AWS data source, one for their development environment and one for production. In that case, each data source instance has its own access control settings.

    By default, Restrict access to this data source is set to off. The data source can be viewed, edited and administered by anyone. If you would like to control who has access to this data source, switch Restrict access to this data source to on.

    Use the Restrict access to this data source dropdown to control who has access to the workspace:

    • By default, the user setting the permissions for the data source will be given Full Control and the Everyone group will be given Link to workspace permissions.
    • Tailor access to the data source, as required, by selecting individual users or user groups from the dropdown and giving them Link to workspace or Full Control permissions.
    • If the user is not available from the dropdown, you are able to invite them to the data source by typing in their email address and then clicking Add. The new user will then receive an email inviting them to create an account on SquaredUp. Once the account has been created, they will gain access to the organization.
    • At least one user or group must be given Full Control.
    • Admin users can edit the configuration, modify the Access Control List (ACL) and delete the data source, regardless of the ACL chosen.

    Access level
    Permissions
    Link to workspace
    • User can link the data source to any workspace they have at least Editor permissions for.
    • Data from the data source can then be viewed by anyone with any access to the workspace.
    • User can share the data source data with anyone they want.
    • User cannot configure the data source in any way, or delete it.
    Full Control
    • User can change the data source configuration, ACL, and delete the data source.

    See Access control for more information.

  8. Click Test and add to validate the data source configuration. SquaredUp will now attempt to connect to SquaredUp using the provided authentication method.

    • Testing passed – a success message will be displayed and then the configuration will be saved.
    • Testing passed with warnings – warnings will be listed and potential fixes suggested. You can still use the data source with warnings. Select Save with warnings if you believe that you can still use the data source as required with the warnings listed. Alternatively, address the issues listed and then select Rerun tests to validate the data source configuration again. If the validation now passes, click Save.
    • Testing Failed – errors will be listed and potential fixes suggested. You cannot use the data source with errors. You are able to select Save with errors if you believe that a system outside of SquaredUp is causing the error that you need to fix. Alternatively, address the issues listed and then select Rerun tests to validate the data source configuration again. If the validation now passes, click Save.

    You can edit any data source configurations at any time from Settings > Data Sources.

Next steps

PromQL vs Simple Query

PromQL is commonly used for querying Prometheus and there are many resources available that include tutorials and example queries. PromQL can be difficult to get right however, even for experienced users.

The Simple Query data streams offer an alternative, easier-to-use method of querying Prometheus data for common queries. Simple Query is the recommended data stream for non-experience PromQL users. To use Simple Query, select Enable object indexing in the data source configuration.

Query results

With the exception of the Alerts data stream, all data streams return data in a tabular format, with the following columns:

  • Timestamp: timestamp of the metric value. If single values are requests (typically an ‘instant’ query) the the timestamp should be the current time. For ‘range’ queries, the timestamps will be at regular intervals across the configured timeframe.
  • Value: the metric value. This is displayed with 5 decimal places by default. Use the Columns step of the tile editor to change the number of decimal places.
  • Auto Label: this is a column automatically created by the data stream to be used as a series label on graphs and other visualizations. It is constructed from the labels that uniquely identify a distinct time series in the returned data. This columns is not stored in Prometheus and cannot be used for aggregations and filtering.
  • Labels: the remaining columns are all the labels for the Prometheus time series.

Troubleshooting query timeouts

It can be common for queries to timeout if they attempt to return a large dataset. To reduce the chance of timeouts, follow these best practices:

  • Scope queries to only the required labels. Use object selections (with object-aware data streams) and label filters to filter the query to the data of interest.
  • Aggregate by labels. A common cause of timeouts is a query that attempts to return a large number of unique time series. For example, a query for an HTTP response time may try to return a time series for each unique client IP address. Aggregating by the client IP address will reduce the number of time series returned
  • Increase the time interval. If queries are still causing timeouts, try increasing the time interval to reduce the number of data points returned.

If the query causes a timeout and you are not sure why, try changing the query to an "instant" or "single value" query that returns just the latest data point for each time series. Use this to filter and aggregate labels to reduce the number of time series returned by the query.

Data streams

You can use these data streams to create new tiles to show data, or if there are preconfigured dashboards installed you can copy or edit those.

Data streams standardize data from all the different shapes and formats your tools use into a straightforward tabular format.

While creating a tile you can tweak data streams by grouping or aggregating specific columns.

Depending on the kind of data, SquaredUp will automatically suggest how to visualize the result, for example as a table or line graph.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

See Data Streams for more information.

The following data streams are installed with this plugin.

Data stream
Description
Alerts
Returns all active alerts. This data stream does not have any parameters, but you can use the Shaping step of the tile editor to optionally filter and aggregate.
Status / Runtime
The runtime info of the Prometheus instance.
Status / Targets
The health of the Prometheus targets
Status / TSDB
The health of the Prometheus TSDB

Configurable data streams

The following data streams installed with this plugin have configurable Parameters.

Data stream
Description
Parameters
PromQL
Executes a PromQL query.
  1. Query:
    Enter a Query, for example:
    sum by (instance) (rate(kubedns_probe_dnsmasq_latency_ms_sum[1m])) / sum by (instance) (rate(kubedns_probe_dnsmasq_latency_ms_count[1m]))
  2. Query type:
    Select the query type. Typically, Range queries are used for graphing results but some Instant queries can also return results over a time range:
    • Range: Evaluates over the timeframe at regular intervals.
    • Instant: Evaluates once. Typically this will be at the current time, but may be a past evaluation time if the timeframe is set to the past (for example, last month).
  3. Interval:
    If Range is selected as the Query type, select the time interval for the query:
    • Automatic (based on timeframe): The interval is selected automatically based on the timeframe. For example, 60 seconds for a timeframe of the last hour, and 1 hour for a timeframe of the last 7 days.
    • Custom: Specify an interval in the Custom interval field. This can be specified as the number of seconds, or a Prometheus time duration (a number followed by s, m, h, d, w or y for seconds, minutes, days, weeks or years).
Simple Query
An easy-to-use alternative to PromQL for common queries.
Metric:
Select a metric. If using the scoped data stream, the available metrics for the objects selected are listed, otherwise all metrics are listed. The list shows the metric name followed by the unit and metric type in brackets.
The remaining parameters depend on the type of metric selected. Prometheus supports four types of metrics- counter, gauge, histogram and summary.
  1. Counter query type:
    Select the type of query:
    • Total count: this uses the PromQL increase function.
    • Rate (per second) over time (typically used for graphing): this uses the PromQL rate function.
  2. Filter by label:
    Specify a label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  3. Filter by second label:
    Specify a second label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the second label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  4. Aggregation:
    Select the type of label aggregation for each timestamp:
    • None (default): No aggregation is applied.
    • Average: Calculates the mean of all values at a given timestamp.
    • Minimum: Selects the smallest value among all data points at the timestamp.
    • Maximum: Selects the largest value among all data points at the timestamp.
    • Sum: Computes the total sum of all values at the timestamp.
    • Top: Specify the top n results to return in the Top/bottom count field.
    • Bottom: Specify the bottom n results to return in the Top/bottom count field.
  5. Group by:
    Choose which labels to aggregate:
    • None: Aggregates over all labels.
    • Selected labels: Aggregates by the labels you specify in the Labels field.
    • All labels except selected: Aggregates by all labels except the labels you specify in the Labels field.
  6. Interval:
    If Rate per second over time is selected as the Counter query type, select the time interval for the query:
    • Automatic (based on timeframe): The interval is selected automatically based on the timeframe. For example, 60 seconds for a timeframe of the last hour, and 1 hour for a timeframe of the last 7 days.
    • Custom: Specify an interval in the Custom interval field. This can be specified as the number of seconds, or a Prometheus time duration (a number followed by s, m, h, d, w or y for seconds, minutes, days, weeks or years).
  1. Gauge query type:
    Select the type of query
    • Single value: Equivalent to a PromQL instant query.
    • Values over time: Equivalent to a PromQL gauge query.
  2. Aggregation over time interval:
    Select the time-based aggregation. For a single value query this is evaluated over the whole timeframe. For a values over time query this is evaluated over each time interval (step).
    • Latest (most recent, or last value in the timeframe or interval)
    • Average
    • Minimum
    • Maximum
  3. Filter by label:
    Specify a label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  4. Filter by second label:
    Specify a second label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the second label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  5. Aggregation:
    Select the type of label aggregation for each timestamp:
    • None (default): No aggregation is applied.
    • Average: Calculates the mean of all values at a given timestamp.
    • Minimum: Selects the smallest value among all data points at the timestamp.
    • Maximum: Selects the largest value among all data points at the timestamp.
    • Sum: Computes the total sum of all values at the timestamp.
    • Top: Specify the top n results to return in the Top/bottom count field.
    • Bottom: Specify the bottom n results to return in the Top/bottom count field.
  6. Group by:
    Choose which labels to aggregate:
    • None: Aggregates over all labels.
    • Selected labels: Aggregates by the labels you specify in the Labels field.
    • All labels except selected: Aggregates by all labels except the labels you specify in the Labels field.
  7. Interval:
    If Values over time is selected as the Gauge query type, select the time interval for the query:
    • Automatic (based on timeframe): The interval is selected automatically based on the timeframe. For example, 60 seconds for a timeframe of the last hour, and 1 hour for a timeframe of the last 7 days.
    • Custom: Specify an interval in the Custom interval field. This can be specified as the number of seconds, or a Prometheus time duration (a number followed by s, m, h, d, w or y for seconds, minutes, days, weeks or years).
  1. Histogram query type:
    Select the type of query:
    • Total count of samples
    • Rate per second of samples over time
    • Sample values over time
  2. Aggregation over time interval:
    If Sample values over time is selected as the query type, choose how to aggregate the individual sample values over each time interval (step):
    • Average: The average value for the time interval.
    • Quantile: Determines the value for which a specified Quantile % of samples are within. For example, specifying 95% calculates the value that 95% of samples are within. The value calculated by Prometheus may be approximate.
  3. Filter by label:
    Specify a label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  4. Filter by second label:
    Specify a second label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the second label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  5. Aggregation:
    Select the type of label aggregation for each timestamp:
    • None (default): No aggregation is applied.
    • Average: Calculates the mean of all values at a given timestamp.
    • Minimum: Selects the smallest value among all data points at the timestamp.
    • Maximum: Selects the largest value among all data points at the timestamp.
    • Sum: Computes the total sum of all values at the timestamp.
    • Top: Specify the top n results to return in the Top/bottom count field.
    • Bottom: Specify the bottom n results to return in the Top/bottom count field.
  6. Group by:
    Choose which labels to aggregate:
    • None: Aggregates over all labels.
    • Selected labels: Aggregates by the labels you specify in the Labels field.
    • All labels except selected: Aggregates by all labels except the labels you specify in the Labels field.
  7. Interval:
    If Values over time is selected as the Histogram query type, select the time interval for the query:
    • Automatic (based on timeframe): The interval is selected automatically based on the timeframe. For example, 60 seconds for a timeframe of the last hour, and 1 hour for a timeframe of the last 7 days.
    • Custom: Specify an interval in the Custom interval field. This can be specified as the number of seconds, or a Prometheus time duration (a number followed by s, m, h, d, w or y for seconds, minutes, days, weeks or years).
  1. Summary query type:
    Select the type of query:
    • Rate (per second) of samples over time
    • Sample values over time
    • Total count of samples
  2. Aggregation over time interval:
    If Sample values over time is selected as the query type, choose how to aggregate the individual sample values over each time interval (step):
    • Average: The average value for the time interval.
    • Quantile: Determines the value for which a specified Quantile % of samples are within. For example, specifying 95% calculates the value that 95% of samples are within. The value calculated by Prometheus may be approximate.
  3. Filter by label:
    Specify a label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  4. Filter by second label:
    Specify a second label to filter by.
    1. Exclude values:
      Select this check box is you want to exclude the specified values for the second label from the results, instead of including them.
    2. Values:
      Select the label values to filter. The values will be logical ORed (the label may match any of the values). Regex expressions are supported.
  5. Aggregation:
    Select the type of label aggregation for each timestamp:
    • None (default): No aggregation is applied.
    • Average: Calculates the mean of all values at a given timestamp.
    • Minimum: Selects the smallest value among all data points at the timestamp.
    • Maximum: Selects the largest value among all data points at the timestamp.
    • Sum: Computes the total sum of all values at the timestamp.
    • Top: Specify the top n results to return in the Top/bottom count field.
    • Bottom: Specify the bottom n results to return in the Top/bottom count field.
  6. Group by:
    Choose which labels to aggregate:
    • None: Aggregates over all labels.
    • Selected labels: Aggregates by the labels you specify in the Labels field.
    • All labels except selected: Aggregates by all labels except the labels you specify in the Labels field.
  7. Interval:
    If Values over time is selected as the Summary query type, select the time interval for the query:
    • Automatic (based on timeframe): The interval is selected automatically based on the timeframe. For example, 60 seconds for a timeframe of the last hour, and 1 hour for a timeframe of the last 7 days.
    • Custom: Specify an interval in the Custom interval field. This can be specified as the number of seconds, or a Prometheus time duration (a number followed by s, m, h, d, w or y for seconds, minutes, days, weeks or years).

Was this article helpful?


Have more questions or facing an issue?
Submit a ticket

On this page

  • Hybrid plugin
  • Adding a data source
  • Before you start
  • Object Indexing
  • Configuring the data source
  • Next steps
  • PromQL vs Simple Query
  • Query results
  • Troubleshooting query timeouts
  • Data streams
  • Configurable data streams

Footer

Sites

  • SquaredUp
  • SQUAREDUP DS
  • DOWNLOAD
  • COMMUNITY ANSWERS

Quick Links

  • Contact Support
  • Events
  • Careers

Small Print

  • Privacy Policy
  • Terms and Conditions
YoutubeX (Twitter)LinkedInBlueSky

© SquaredUp 2025