Skip to content

Commit 7bcb0f5

Browse files
alexprotsenkoalexprotsenko
authored
Updated readme.md for GA
1 parent bb62d2f commit 7bcb0f5

1 file changed

Lines changed: 95 additions & 79 deletions

File tree

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

Lines changed: 95 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,95 @@
1-
# SQL Assessment API
2-
3-
SQL Assessment API provides a mechanism to evaluate the configuration of your SQL Server for best practices. The API is delivered with a ruleset containing best practice rules suggested by SQL Server Team. This ruleset is enhancing with the release of new versions but at the same time, the API is built with the intent to give a highly customizable and extensible solution. So, users can tune the default rules and create their own ones. The API can be used to assess SQL Server versions 2012 and higher and Azure SQL Database Managed Instance (more to come).
4-
5-
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).
6-
7-
8-
## QuickStart.md
9-
10-
Learn how to assess your SQL Server configuration for best practices in 2 simple steps.
11-
12-
## config.json
13-
14-
This is the default set of rules shipped with SQL Assessment API. Feel free to open issues to have us fix or add rules. Also, we're happy to see your pull requests to this file.
15-
16-
## DisablingBuiltInChecks_sample.json
17-
18-
Contains two parts. First shows how you can disable a specified rule by its ID. The second disables all the rules with the "TraceFlag" tag.
19-
20-
## MakingCustomChecks_sample.json
21-
22-
Demonstrates how to make a custom ruleset containing two checks. The sample contains two sections: `rules` and `probes`. `Rules` is for rule (sometimes refered to as check) definitions. Usually, rules are best practices or a company's internal policies that should be applied to SQL Server configuration. Here's one of the rules from this sample with comments on each property:
23-
24-
```
25-
{
26-
"target": { //Object to describe which SQL Server object this check is applied.
27-
"type": "Database", //This check targets at Database object.
28-
"version": "[12.0,)", //Applies to SQL Server 2014 and higher.
29-
//Another example: "[12.0,13.0)" reads as "any SQL Server with version >= 12.0 and < 13.0.
30-
"platform": "Windows", //Applies to SQL Server on Windows.
31-
"name": { "not": "/^(master|msdb)$/" } //Applies to any database but master and msdb.
32-
},
33-
"id": "CustomCheck1", //Check ID.
34-
"tags": [ "InternalBestPracticeSet", "Performance" ], //Tags combine checks in different subsets.
35-
"displayName": "Query Store should be on", //Short name for check.
36-
"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.",
37-
//Some more detailed explanation of the best practice or policy.
38-
"message": "Turn Query Store option on to improve query performance troubleshooting.",
39-
//Usually, it's for recommendation what the user should do if the check fires up
40-
"helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store",
41-
//Reference material
42-
"probes": [ "DatabaseConfiguration" ], //List of probes that are used to get the required data for this check.
43-
//Probes will be explained below.
44-
"condition": "@is_query_store_on" //Check will pass if condition is true. Otherwise, the check fires up.
45-
}
46-
```
47-
48-
`Probes` describes 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.
49-
```
50-
"probes":{
51-
"DatabaseConfiguration": [ //Probe name that is used to reference the probe from a check.
52-
//Probe can have a few implementations that will be used for different targets.
53-
//This probe has two implementations for different version of SQL Server.
54-
{
55-
"type": "SQL", //Probe uses a T-SQL query to get the required data
56-
"target": {
57-
"type": "Database", //Targets at database
58-
"version": "(,12.0)", //This implementation is for SQL Server before 2014
59-
"platform": "Windows" //Targets at SQL on Windows
60-
},
61-
"implementation": { //Implementation object with a T-SQL query.
62-
//sys.databases of SQL Server before 2014 doesn't have the field is_query_store_on so we replace it with 0.
63-
"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'"
64-
}
65-
},
66-
{ //Second implementation
67-
"type": "SQL",
68-
"target": {
69-
"type": "Database",
70-
"version": "[12.0,)", //This implementation is for SQL Server 2014 and up.
71-
"platform": "Windows"
72-
},
73-
"implementation": { //Query of the second implementation.
74-
"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'"
75-
}
76-
}
77-
]
78-
}
79-
```
1+
# SQL Assessment API
2+
3+
SQL Assessment API provides a mechanism to evaluate the configuration of your SQL Server for best practices. The API is delivered with a ruleset containing best practice rules suggested by SQL Server Team. This ruleset is enhancing with the release of new versions but at the same time, the API is built with the intent to give a highly customizable and extensible solution. So, users can tune the default rules and create their own ones. The API can be used to assess SQL Server versions 2012 and higher and Azure SQL Database Managed Instance (more to come).
4+
5+
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).
6+
7+
## QuickStart.md
8+
9+
Learn how to assess your SQL Server configuration for best practices in 2 simple steps.
10+
11+
## config.json
12+
13+
This is the default set of rules shipped with SQL Assessment API. Feel free to open issues to have us fix or add rules. Also, we're happy to see your pull requests to this file.
14+
15+
## DisablingBuiltInChecks_sample.json
16+
17+
Contains three parts. First shows how you can disable a specified rule by its ID. The second disables all the rules with the "TraceFlag" tag. The last disables to run all rules of the default ruleset (using the DefaultRuleset tag) against databases named "DBName1" and "DBName2".
18+
19+
## MakingCustomChecks_sample.json
20+
21+
Demonstrates how to make a custom ruleset containing two checks. The sample contains two sections: `rules` and `probes`. `Rules` is for rule (sometimes referred to as check) definitions. Usually, rules are best practices or a company's internal policies that should be applied to SQL Server configuration. Here's one of the rules from this sample with explanations for each line:
22+
23+
```json
24+
{
25+
"target": { //Target describes a SQL Server object the check is supposed to run against
26+
"type": "Database", //This check targets Database object
27+
"version": "[13.0,)", //Applies to SQL Server 2016 and higher
28+
//Another example: "[12.0,13.0)" reads as "any SQL Server version >= 12.0 and < 13.0"
29+
"platform": "/^(Windows|Linux)$/", //Applies to SQL Server on Windows and Linux
30+
"engineEdition": "OnPremises, ManagedInstance", //Applies to SQL on Premises and Azure SQL Managed Instance. Here you can also filter specific editions of SQL Server
31+
"name": { "not": "/^(master|tempdb|model)$/" } //Applies to any database excluding master, tempdb, and msdb
32+
},
33+
"id": "QueryStoreOn", //Rule ID
34+
"itemType": "definition", //Can be "definition" or "override". First is to declare a rule, the latter is to override/customize an existing rule. See also DisablingBuiltInChecks_sample.json
35+
"tags": [ "CustomRuleset", "Performance", "QueryStore", "Statistics" ], //Tags combine rules in different subsets.
36+
"displayName": "Query Store should be active", //Short name for the rule
37+
"description": "The 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. While Query Store collects queries, execution plans and statistics, its size in the database grows until this limit is reached. When that happens, Query Store automatically changes the operation mode to read-only and stops collecting new data, which means that your performance analysis is no longer accurate.",
38+
//A more detailed explanation of a best practice or policy that the rule check
39+
"message": "Make sure Query Store actual operation mode is 'Read Write' to keep your performance analysis accurate",
40+
//Usually, it's for recommendation what user should do if the rule raises up an alert
41+
"helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store",
42+
//Reference material
43+
"probes": [ "Custom_DatabaseConfiguration" ], //List of probes that are used to get the required data for this check. See below to know more about probes.
44+
"condition": { //Condition object is to define "good" and "bad" state, the latter is when the rule should raise an alert. When the condition is true, it means that the checked object complies with the best practice or policy. Otherwise, the rule raises an alert (it actually adds its message to the resulting set of recommendations)
45+
"equal": [ "@query_store_state", 2 ] //It means that the variable came from the probe should be equal to 2
46+
}
47+
}
48+
49+
```
50+
51+
`Probes` describes how and where to get the required data to check compliance with a rule. You can use T-SQL queries as well as methods from some assemblies. The probe below uses a T-SQL query.
52+
53+
```json
54+
"Custom_DatabaseConfiguration": [ //Probe name is used to reference the probe from a rule
55+
//Probe can have a few implementations that will be used for different targets
56+
//This probe has two implementations for different version of SQL Server
57+
{
58+
"type": "SQL", //Probe uses a T-SQL query to get the required data. Use 'CLR' for assemblies.
59+
"target": { //Probes have their own target, usually to separate implementation for different versions, editions, or platforms. Probe targets work the same way as rule targets do.
60+
"type": "Database",
61+
"version": "(,12.0)", //This target is for SQL Server of versions prior to 2014
62+
"platform": "/^(Windows|Linux)$/",
63+
"engineEdition": "OnPremises, ManagedInstance"
64+
},
65+
"implementation": { //Implementation object with a T-SQL query. This probe is used in many rules, that's why the query return so many fields
66+
"query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, 0 AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, NULL AS is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName"
67+
}
68+
},
69+
{ //This implementation object is to get the required data from SQL Server 2014 (look at target.version)
70+
"type": "SQL",
71+
"target": {
72+
"type": "Database",
73+
"version": "[12.0, 13.0)",
74+
"platform": "/^(Windows|Linux)$/",
75+
"engineEdition": "OnPremises, ManagedInstance"
76+
},
77+
"implementation": {
78+
"query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, 0 AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, db.is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName"
79+
}
80+
},
81+
{
82+
"type": "SQL", //This implementation object is to get the required data from SQL Server 2016 and up (look at target.version)
83+
"target": {
84+
"type": "Database",
85+
"version": "[13.0,)",
86+
"platform": "/^(Windows|Linux)$/",
87+
"engineEdition": "OnPremises, ManagedInstance"
88+
},
89+
"implementation": {
90+
"useDatabase": true, //Use this key if your query requires to run on a database that is being assessed (it's a replacement for 'USE <DATABASENAME>;')
91+
"query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, (SELECT CAST(actual_state AS DECIMAL) FROM [sys].[database_query_store_options]) AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, db.is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName"
92+
}
93+
}
94+
]
95+
```

0 commit comments

Comments
 (0)