Analytics

This page describes StackState version 4.2.
Go to the documentation for the latest StackState release.
Overview
The analytics environment allows you to directly query the 4T data model. The analytics environment uses the StackState Scripting Language (STSL) as the basis for querying StackState, so you can build and test your StackState scripts here.
Queries created in the analytics environment can be used to investigate issues, automate processes and build reports. Here are some examples of queries that you could execute:
Get the names of all pods running in a namespace.
Determine the maximum latency of a service since yesterday. 
Find all machines indirectly connected to a set of APIs.
Show which databases have been updated since last week.
The analytics environment
If your StackState user has the permission access-analytics, then you can access the analytics environment from the main menu. This will be available by default for all power users and admins. There are also places in the user interface where you can be directed to analytical environment if some data is available in the form of a query, a link will then say "Open in Analytics".
The analytics environment is divided into two sections:
The query you want to execute on the left
The results and query history on the right.
When executing a query for the first time, the result of the query is displayed in preview form if a preview is available for the type of data that is requested, for example a metric chart or a topology view. If no preview is available, the data will be shown in JSON form.
Every query that you have executed in StackState is shown in the query history, together with the query result at that point in time.
Analytics screenshot
Previews
Results of queries are typically displayed in raw JSON form, unless there is a preview available. Previews are currently available for:
Topology query results, see Topology.query​
Telemetry query results, see Telemetry.query 
Telemetry predictions, see Prediction.predictMetrics​
STML reports, see UI.showReport​
Queries
In the analytics environment, you use a combination of the StackState Scripting Language (STSL) and the StackState Query Language (STQL) to build your queries and scripts.
A query is a regular STSL script. For example, when you run the query: 1+1 you will get the result 2.
As a part of an STSL script, you can invoke the StackStake Query Language (STQL). A simple example of an analytical query that uses both STSL and STQL is:
1
Topology.query('environment in ("Production")').components()
Copied!
​Topology.query is a regular script function that takes ab STQL query (environment in ("Production") in the above example) as an argument. The .components() at the end, is a so-called builder method. This ensures that only the components, and not the relations between these components, are retrieved from the topology.
The combination of STSL and STQL allows you to chain together multiple queries. The following example gets all metrics of all databases in the production environment for the last day:
1
Topology
2
    .query('environment in ("Production") AND type = "Database"')
3
    .components()
4
    .metricStreams()
5
    .thenCollect { metricStream -> 
6
        Telemetry.query(metricStream)
7
            .aggregation("95th percentile"", "15m")
8
            .start("-1d")
9
    }
Copied!
This analytical query first gets all metrics streams of components from the Production environment that are of the type Database. The result of that query is then used to build up telemetry queries against these metric streams.
The full list of available functions can be found in the Script API documentation. To learn about chaining, see async script results.
Example queries
Below are some queries to get you started with an example of their expected output. You can find more examples in the StackState UI Analytics environment itself.
​Find the number of relations between two components​
​Compare the Staging environment to the Production environment​
​Predict disk space of a server for the next week ​
Find the number of relations between two components
Query
Example result
1
Topology.query('name IN ("Alice", "Bob")')
2
  .relations()
3
  .count()
Copied!
1
1
Copied!
Compare the Staging environment to the Production environment
Query
Example result
1
Topology.query('environment = "Staging"')
2
    .diff(Topology.query('environment = "Production"'))
3
    .then { diff ->
4
        diff
5
            .diffResults[0]
6
            .result
7
            .addedComponents
8
            .collect { comp -> comp.name }
9
    }
Copied!
1
[
2
  "customer E_appl02",
3
  "MobileApp",
4
  "customer B_appl01",
5
  "customer E_appl01",
6
  "customer B_appl02"
7
]
Copied!
Predict disk space of a server for the next week
Query
Example result
1
Prediction.predictMetrics("linear", "7d",
2
    Telemetry.query("StackState metrics", 'host="lnx01" AND name="diskspace" AND mount="/dev/disk1s1"')
3
        .metricField("value")
4
        .aggregation("min", "1d")
5
        .start("-4w") // based on last month
6
        .compileQuery()
7
).predictionPoints(7).then { result -> resut.prediction  }
Copied!
1
{
2
    "_type":"MetricTelemetryData",
3
    "data":[
4
        [
5
            52.35911407877176,
6
            1611091854483
7
        ],
8
        [
9
            51.400303131762215,
10
            1611092754483
11
        ],
12
        [
13
            48.64705240252446,
14
            1611093654483
15
        ],
16
        [
17
            49.62017120667122,
18
            1611094554483
19
        ],
20
        [
21
            49.55251201458979,
22
            1611095454483
23
        ],
24
        [
25
            54.46042805305259,
26
            1611096354483
27
        ],
28
        [
29
            48.681355107261204,
30
            1611097254483
31
        ],
32
    ],
33
    "dataFormat":[
34
        "value",
35
        "timestamp"
36
    ],
37
    "isPartial":false
38
}
Copied!
See also
​StackState scripting language (STSL)​
​StackState script APIs​
​StackState Query Language (STQL)​

Browse telemetry

Next - Use

Health state and event notifications

Last modified 6mo ago

Copy link

Contents

Overview

The analytics environment

Previews

Queries

Example queries