Skip to content

Commit 7adf5b3

Browse files
markingmynamemarkingmyname
authored
Merge pull request #599 from markingmyname/api
[SQL Assessment API] Added JSON files to the sql-assessment-api folder
2 parents 690fc3f + 05508da commit 7adf5b3

4 files changed

Lines changed: 1678 additions & 0 deletions

File tree

‎samples/manage/sql-assessment-api/DisablingBuiltInChecks_sample.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"checks":[
3+
{
4+
"id": "SqlServer.Database.AutoCreateStats",
5+
"enabled": false
6+
},
7+
{
8+
"select": ["TraceFlag"],
9+
"enabled": false
10+
}
11+
]
12+
}

‎samples/manage/sql-assessment-api/MakingCustomChecks_sample.json‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{
2+
"checks":[
3+
{
4+
"target": {
5+
"type": "Database",
6+
"platform": "Windows"
7+
},
8+
"id": "Custom_SqlServer.Database.AutoUpdateStats",
9+
"tags": [ "InternalBestPracticeSet", "Performance" ],
10+
"displayName": "Auto-Update Statistics should be on",
11+
"description": "The query optimizer needs up-to-date and accurate statistics in order to generate good plans. In most cases, it's best to let SQL Server maintain the statistics. If you turn 'Auto Create Stats' and 'Auto Update Stats' off, then it is up to you to keep the statistics up-to-date somehow. Failure to do so will lead to poor query performance. Most applications should have these options ON.\n \n When the Auto Update Statistics setting is ON, the query optimizer updates statistics when they are used by a query and when they might be out-of-date. Statistics become out-of-date after insert, update, delete, or merge operations change the data distribution in the table or indexed view. The query optimizer determines when statistics might be out-of-date by counting the number of data modifications since the last statistics update and comparing the number of modifications to a threshold. The threshold is based on the number of rows in the table or indexed view. The query optimizer checks for out-of-date statistics before compiling a query and before executing a cached query plan. Before compiling a query, the query optimizer uses the columns, tables, and indexed views in the query predicate to determine which statistics might be out-of-date. Before executing a cached query plan, the Database Engine verifies that the query plan references up-to-date statistics. The AUTO_UPDATE_STATISTICS option applies to statistics created for indexes, single-columns in query predicates, and statistics that are created by using the CREATE STATISTICS statement. This option also applies to filtered statistics.",
12+
"message": "Turn Auto-Update Statistics option on to improve query performance.",
13+
"helpLink": "https://blogs.msdn.microsoft.com/buckwoody/2009/08/18/sql-server-best-practices-auto-create-and-auto-update-statistics-should-be-on-most-of-the-time/",
14+
"probes": [ "DatabaseConfiguration" ],
15+
"condition": "@is_auto_update_stats_on"
16+
},
17+
{
18+
"target": {
19+
"type": "Database",
20+
"version": "[12.0,)",
21+
"platform": "Windows",
22+
"name": { "not": "/^(master|msdb)$/" }
23+
},
24+
"id": "Custom_SqlServer.Database.QueryStoreOn",
25+
"tags": [ "InternalBestPracticeSet", "Performance" ],
26+
"displayName": "Query Store should be on",
27+
"description": "The SQL Server Query Store feature provides you with insight on query plan choice and performance. It simplifies performance troubleshooting by helping you quickly find performance differences caused by query plan changes. Query Store automatically captures a history of queries, plans, and runtime statistics, and retains these for your review. It separates data by time windows so you can see database usage patterns and understand when query plan changes happened on the server.",
28+
"message": "Turn Query Store option on to improve query performance troubleshooting.",
29+
"helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store",
30+
"probes": [ "DatabaseConfiguration" ],
31+
"condition": "@is_query_store_on"
32+
}
33+
],
34+
"probes":{
35+
"DatabaseConfiguration": [
36+
{
37+
"type": "SQL",
38+
"target": {
39+
"type": "Database",
40+
"version": "(,12.0)",
41+
"platform": "Windows"
42+
},
43+
"implementation": {
44+
"query": "SELECT db.[is_auto_create_stats_on] AS is_auto_create_stats_on, db.[is_auto_update_stats_on] AS is_auto_update_stats_on, 0 AS is_query_store_on FROM sys.databases AS db WHERE db.[name]='@DatabaseName'"
45+
}
46+
},
47+
{
48+
"type": "SQL",
49+
"target": {
50+
"type": "Database",
51+
"version": "[12.0,)",
52+
"platform": "Windows"
53+
},
54+
"implementation": {
55+
"query": "SELECT db.[is_auto_create_stats_on] AS is_auto_create_stats_on, db.[is_auto_update_stats_on] AS is_auto_update_stats_on, db.[is_query_store_on] AS is_query_store_on FROM sys.databases AS db WHERE db.[name]='@DatabaseName'"
56+
}
57+
}
58+
]
59+
}
60+
}

‎samples/manage/sql-assessment-api/README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# SQL Assessment API samples
2+
3+
Contains samples for customizing SQL Assessment API. Learn more about the API on the [SQL Assessment API docs page](https://docs.microsoft.com/en-us/sql/sql-assessment-api/sql-assessment-api-overview).
4+
5+
## config.json
6+
7+
This is the default set of checks shipped with SQL Assessment API. Feel free to open issues to have us fix or add checks. Also, we're happy to see your pull requests to this file.
8+
9+
## DisablingBuiltInChecks_sample.json
10+
11+
Contains two parts. First shows how you can disable a specified check by its ID. The second disables all the checks with the "TraceFlag" tag.
12+
13+
## MakingCustomChecks_sample.json
14+
15+
Demonstrates how to make a custom rule set containing two checks. The sample contains two sections: `checks` and `probes`. `Checks` is for check (or rule) definitions. Usually, checks or rules are best practices or a company's internal policies that should be applied to SQL Server. Here's one of the checks from this sample with comments on each property:
16+
17+
```
18+
{
19+
"target": { //Object to describe which SQL Server object this check is applied.
20+
"type": "Database", //This check targets at Database object.
21+
"version": "[12.0,)", //Applies to SQL Server 2014 and higher.
22+
//Another example: "[12.0,13.0)" reads as "any SQL Server with version >= 12.0 and < 13.0.
23+
"platform": "Windows", //Applies to SQL Server on Windows.
24+
"name": { "not": "/^(master|msdb)$/" } //Applies to any database but master and msdb.
25+
},
26+
"id": "CustomCheck1", //Check ID.
27+
"tags": [ "InternalBestPracticeSet", "Performance" ], //Tags combine checks in different subsets.
28+
"displayName": "Query Store should be on", //Short name for check.
29+
"description": "The SQL Server Query Store feature provides you with insight on query plan choice and performance. It simplifies performance troubleshooting by helping you quickly find performance differences caused by query plan changes. /n Query Store automatically captures a history of queries, plans, and runtime statistics, and retains these for your review. It separates data by time windows so you can see database usage patterns and understand when query plan changes happened on the server.",
30+
//Some more detailed explanation of the best practice or policy.
31+
"message": "Turn Query Store option on to improve query performance troubleshooting.",
32+
//Usually, it's for recommendation what the user should do if the check fires up
33+
"helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store",
34+
//Reference material
35+
"probes": [ "DatabaseConfiguration" ], //List of probes that are used to get the required data for this check.
36+
//Probes will be explained below.
37+
"condition": "@is_query_store_on" //Check will pass if condition is true. Otherwise, the check fires up.
38+
}
39+
```
40+
41+
`Probes` describe how and where get required data to perform a check. For this, you can use T-SQL queries as well as methods from assemblies. The probe below uses a T-SQL query.
42+
```
43+
"probes":{
44+
"DatabaseConfiguration": [ //Probe name that is used to reference the probe from a check.
45+
//Probe can have a few implementations that will be used for different targets.
46+
//This probe has two implementations for different version of SQL Server.
47+
{
48+
"type": "SQL", //Probe uses a T-SQL query to get the required data
49+
"target": {
50+
"type": "Database", //Targets at database
51+
"version": "(,12.0)", //This implementation is for SQL Server before 2014
52+
"platform": "Windows" //Targets at SQL on Windows
53+
},
54+
"implementation": { //Implementation object with a T-SQL query.
55+
//sys.databases of SQL Server before 2014 doesn't have the field is_query_store_on so we replace it with 0.
56+
"query": "SELECT db.[is_auto_create_stats_on] AS is_auto_create_stats_on, db.[is_auto_update_stats_on] AS is_auto_update_stats_on, 0 AS is_query_store_on FROM sys.databases AS db WHERE db.[name]='@DatabaseName'"
57+
}
58+
},
59+
{ //Second implementation
60+
"type": "SQL",
61+
"target": {
62+
"type": "Database",
63+
"version": "[12.0,)", //This implementation is for SQL Server 2014 and up.
64+
"platform": "Windows"
65+
},
66+
"implementation": { //Query of the second implementation.
67+
"query": "SELECT db.[is_auto_create_stats_on] AS is_auto_create_stats_on, db.[is_auto_update_stats_on] AS is_auto_update_stats_on, db.[is_query_store_on] AS is_query_store_on FROM sys.databases AS db WHERE db.[name]='@DatabaseName'"
68+
}
69+
}
70+
]
71+
}
72+
```

0 commit comments

Comments
 (0)