ServicePilot SaaS Documentation

Search

ServicePilot provides access to the data it collects as graphs, tables and summaries as well as the raw data as stored in its databases. All of this is filtered and categorized to produce useful statistics.

When deploying resources, the packages come with pre-defined dashboards to display information related to these resources. These dashboards might already show the information you require but it is possible to filter this information further or create completely new queries.

Time span

Whenever queries are made for historical data, there is always a time span filter presented at the top left of the screen. All queries will be made based on this filter.

To speed up queries, always select the smallest time span required and only expand the time span as needed once the query is known to contain the correct data. This is particularly true of event type data rather than polled data.

Time span menu

Dashboard query

It is possible to further filter any dashboard by adding an extra query to the data that is already presented.

  1. Select the query button when viewing a dashboard Dashboard query button
  2. Add a filter and click Apply Dashboard query field

Use the + icon the build up more complex queries using a dialog to select the elements required. If you need help with the query syntax, open the query help using the Question mark link.

Query syntax notes

If names contain spaces, then you can use double quotes or escape the space. If you want to use wild cards then you cannot use double quotes as the wild card is then not interpreted.

object:"my server"

or

object:my\ server*

Also note that some characters have special meaning and so need to be escaped. The list of escaped characters is provided in the help.

status:\?

This will return items that have a status set to ? (unknown)

duration:[10 TO 60] AND -quality:*

This will return records with duration between 10 and 60 inclusive that do not contain a quality indicator.

Common queries

Limit search to a part of the hierarchy

It is often useful to limit output to a part of the supervised equipment by filtering by view. If you select the view tag then this will only discover objects that are members of the view and not objects that are in all sub-views of the view selected.

view:"server - interfaces"

This will query objects that are in the server - interfaces view.

view3:site\ *\ servers

This will query all objects that are under a view at level 3, and beneath, that has the pattern site * servers. A level 3 view is a view at the third level of the monitoring hierarchy. For example MAIN > Sites > Site A > Site A Servers

Limit search to items over a limit

It can be interesting to limit results to objects with indicator values above or below a value. By including this type of filter, data that no longer matches the information will be removed which might affect other queries that do not contain this indicator.

cpu usage>3

Be careful not to add extra spaces before or after the operator.

Look for records where a field contains text

When parsing logs, it might be interesting to find all records that contain or do not contain a particular string.

text:*error*

or

!text:*error*

Please note that these types of queries take a lot of processing time and might even timeout. Limit the time span to get results in this case.

Data types

There are two main data types for information stored by ServicePilot in its databases. String fields store text. Integer fields store numerical data.

Indicator thresholds

When testing thresholds, String indicators can only use the = and <> operators while Integer indicators can also be checked using < and > to see if the value is greater or less than a limit. As well as fixed thresholds, Integer indicators can also have thresholds set against analytical analysis of the data series to find Spikes, Level step changes and Trends. More information about Data Anomalies can be found under Analytics > Anomalies.

Database Query operators

When extracting data from the ServicePilot database, a number of series of data are collected to be presented. Each series is collected within the same time period specified. Either a Field is specified and a Field Statistic operator is applied or a Formula is applied to the data.

Field statistics

Field Statistics are limited by the type of data being queried.

Data Type Field Statistic Use
String & Integer Count Count the number of records in the database that contain this field within the time period specified. Not all records in the database contain all of the fields.
First value Obtain the first value of the field selected within the time period specified.
Last value Obtain the last value of the field selected within the time period specified.
Missing data Count the number of records in the database that do not contain this field within the time period specified.
Unique Count the number of different values that the field selected takes within the time period specified.
Integer only Sum Sum all of the values for the field specified within the time period specified.
Mean Find the average for all of the values of the field specified within the time period specified.
Min Find the smallest value from all of the values of the field specified within the time period specified.
Max Find the largest value from all of the values of the field specified within the time period specified.
Sum2 The squared sum all of the values for the field specified within the time period specified.
Percentile An estimated value for the specified percentile from all of the values for the field specified within the time period specified. For example: The 20th percentile is the value below which 20% of the observations may be found.
Spike Count the number of values that start falling outside a dynamically calculated range around the plot of values from the field specified.
Level Count the number of times that the values start causing the dynamically calculated range to change significantly from the field specified.
Trend A sliding trend expressed in as a percentage from the field specified.
When A time forecast as to when this field will cross the critical threshold associated with this indicator.

The more complicated statistical formula are best represented graphically using an example graph. This graph plots one indicator with associated range, spikes outside the range and range level changes.

Example graph

Formulas

Rather than obtaining a statistic directly from the data, a Formula can be applied to create a new series from the existing series. For example: A series is defined obtaining the sum of inbound network traffic and a second series is defined, obtaining the sum of outbound traffic. A third series is then defined as the sum of the first two series so that total traffic can be viewed.

Formula Use
sum(x,y,...) Add the series values together. Example: sum(series0,series1)
sub(x,y) Subtract the second series from the first. Example: sub(series0,series1)
product(x,y,...) Multiply the series values together. Example: product(series0,series1)
div(x,y) Divide the first series by the second. Example: div(series0,series1)
termfreq(series#,term) Count the number of times term is found in the series. Example: div(series0,'ok')
viewpath(series#) Obtain the view hierarchy for the series. Example: viewpath(series0)
status(series#) Obtain the status of the series. Example: status(series0)

Create custom queries

If existing dashboards do not contain data presented as you require, new custom queries can be created and stored for use in custom dashboards and PDF reports. See Reporting for more details.

Select the source data

  1. Start by opening the Analytics > Search page. Analytics menu item
  2. Change the time span to the smallest time period to reduce query times while developing a new custom query. Minimum time period
  3. Select a Search template as a starting point, based on the data to be queried. Templates are organised by the database in which the data is stored. Existing custom searches are presented at the bottom of the list under custom. Search template list
  4. Click on the Event view button to see the raw data as it is found in the database. Event view button
  5. Expand a record by clicking on the > icon and use the mouse wheel to scroll up and down the list of fields available in the record. Expanded database record
  6. To change the way in which the events are presented, click on the Properties button and select which data to show and highlight in the table as well as toggling the graph visibility. Search presentation properties

It is possible to present this data directly as a table of records, however it is almost always more useful to filter, summarize, sort and graph the data.

Apply a query

It is possible to filter the data retrieved from the database before it is presented. The query filter will be associated with the widget created. Note that data will be filtered automatically based what a particular user is allowed to monitor. Dashboard users may apply further filters to all widgets on the same dashboard.

  1. Click on the Query icon. Query filter icon
  2. Add a query filter and click on Apply.

Define the data series

Series can be added, modified and deleted from the Series list at the top left of the screen.

Series list

A number of different series might be defined and displayed in the same widget. Each series has three critical parameters; Field or formula, Field Statistic and Title. Series fields

Other series parameters depend on these initial settings. Note the Table options and Heat map options tabs that contain further settings for how this series data will be presented.

Data presentation

Once the data is selected and filtered, it can be presented in many different ways. Use the Widget presentation buttons to select how the data is to be visualized.

Data presentation type buttons

View Type Use
Table View each of the series as a column in the table. The table rows are defined by the Group by filter.
Capacity Display a trend and projection table for one series. The table rows are defined by the Group by filter.
Charts Display a chart of the series data. Each series will produce a different line or value on the chart depending on the chart type selected.
Events Display the raw list of event records in the database, one per line. A chart of series can also be included.
Chart Top Display a chart of up to 10 of the most important groups. The data is first grouped by the Group by field and then one series is selected as the Top series. One line is presented on the graph for each of the top 10 groups form the top series. For example: A Top Disk Spage usage graph might be generated by setting the Top series to an Average Disk Space Usage field series and the Group by field to object to separate the data by disk.
Scatter A scatter plot comparing one series against a second series with a group by field selector.
Mapping A graphical map linking a number of Group by series with one Top series.

Saving queries

Once a new widget has been developed and tested, it can be given a name by saving it so that it might be further modified or added to custom dashboards and PDF reports.

Search save button

Get started Now