Merge pull request #1058 from aguzev/sql_assessment_api_docs

Update SQL Assessment APi documentation

Author: ebruersan

samples/manage/sql-assessment-api/docs/Customization/DataTransformation.md

@@ -0,0 +1,28 @@
+# Data Transformation
+
+Sometimes data needs to go through series of transformations.
+
+When dta comes in an unconvenient format, a transformation can be applied in the probe implementation. For example, the following T-SQL query returns `host_release` as a string like '10.0.19044.2006'.
+
+```SQL
+SELECT host_platform, host_release
+FROM sys.dm_os_host_info
+```
+
+While it is possible to parse the string in T-SQL, a transformation make the code more readable and easier to create and maintain:
+
+```json
+"implementation": {
+    "query": "SELECT host_platform, host_release FROM sys.dm_os_host_info",
+    "transform": {
+        "type": "parse",
+        "map": {
+            "host_release": "/^(?<major>\\d+)\\.(?<minor>\\d+)"
+        }
+    }
+}
+```
+
+Transformations can be applied in [probe references](./ProbeReference.md) to increase probe reuse. When one check needs an average value for some metric while another best practice involves maximum for the same metric. Both checks can have references to the same probe but each applies its own specific transformation. In this case not only the probe code is reused, but the data is reused as well, because the probe will be called only once.
+
+See [Data transformation reference](../Reference/DataTransformation/README.md) for more details.

samples/manage/sql-assessment-api/docs/Customization/LocalVariables.md

@@ -0,0 +1,17 @@
+# Local Variables
+
+A check can define local variables available for conditions and message templates. Local variables are any expressions involving literals, probe data, and transformation results.
+
+```json
+{
+    "probes": ["SysDmOsSysInfo"],
+    "locals": {
+        "workers": {"sub": [ "@max_workers_count", 1 ] }
+    },
+    "message": "Workers = @{workers}.",
+    "condition": {
+        "lt": [ 0, "@workers" ],
+        "lt": [ "@workers", 4 ]
+    }
+}
+```

samples/manage/sql-assessment-api/docs/Customization/Probe.md

@@ -0,0 +1,42 @@
+# Probe
+
+A *Probe* is a JSON property. The property name is the probe ID used in checks. The property value is an array of [probe implementations](#probe-implementation). The SQL Assessment API engine selects the first implementation with matching target pattern. This means that the order of the implementations in the array is important. A probe can be comprised by a mix of CLR and SQL implementations.
+
+Another ruleset may add probe implementations on top of the list.
+
+A probe should be designed as a function with no side effects. The order of calling probes is not determined. The engine may reorder probe calls to optimize the target SQL Server load. When no check needs data from a probe, that probe will not be called.
+
+Probes from the default rule set read metadata only, e.g. update logs or server properties. They do not read user data from tables or write anything to databases or instances. Probes do not set any flags or properties.
+
+## Probe implementation
+
+Probe implementation is represented by a JSON object. Its properties define procedures for getting data and selecting appropriate implementation.
+
+![Probe structure](img\ProbeStructure.svg)
+
+## Probe properties
+
+### implementation
+
+The `implementation` property contains probe parameters and [data transformations](DataTransformation.md) affecting the probe output. For example, for a T-SQL probe the main parameter is the query for selecting data.
+
+Probe parameters are specific for [probe type](#type).
+
+### target
+
+Target object [pattern](TargetPattern.md).
+
+### type
+
+Probe `type` determines the mechanism used to get data. it may be a T-SQL or a WMI. Available probe types are listed in the following table.
+
+|Type|Description|
+|---|---|
+|[AzGraph](../Reference/Probes/AzGraphProbe.md)|Kusto query to Azure resource graph|
+|[AzMetadata](../Reference/Probes/AzMetadataProbe.md)|JSONPath for the object returned by Azure Instance Metadata Service|
+|[CMD](../Reference/Probes/CMDShellProbes.md)|Command shell script run on the target machine|
+|[External](../Reference//Probes/ExternalProbe.md)|Arbitrary .NET code|
+|[PowerShell](../Reference/Probes/PowerShellProbes.md)|PowerShell script|
+|[Registry](../Reference/Probes/RegistryProbes.md)|Data from registry|
+|[SQL](../Reference/Probes/TSQLProbes.md)|T-SQl query|
+|[WMI](../Reference/Probes/WMIProbes.md)|WMI query|

samples/manage/sql-assessment-api/docs/Customization/ProbeReference.md

@@ -0,0 +1,102 @@
+# Probe reference
+
+Data for checks comes from probes. Probe reference is a JSON object that describes a probe needed by the check. When a probe is referenced with no additional options or parameters, a probe reference may be abbreviated to a string containing probe ID.
+
+![Probe reference structure](img\ProbeRefStructure.svg)
+
+## Properties
+
+### alias
+
+An alternative name used for this probe.
+
+Alias is an alternative name for the probe which can be used in expressions in this check. It is useful in two scenarios: [calling a probe multiple times](#calling-probe-multiple-times) and [passing data from one probe to another one](#using-data-from-another-probe).
+
+### id
+
+Referenced probe ID.
+
+### params
+
+Parameters passed to the probe called for this check. They are represented as properties of a JSON object. Property name is the parameter name while property value can be any [expression](Expression.md). Expression can include constants, global and local variables, and data returned by other probes (see [alias](#alias)).
+
+### transform
+
+Data transformation applied to the data before calculation the condition value, see [Data transformation](DataTransformation.md).
+
+## Calling probe multiple times
+
+For some checks you may need to call a probe multiple times with different parameters. In this case add multiple probe references with the same `id`. To distinguish results returned for different parameters prepend the output variable name with probe alias and double colon '::'.
+
+The following check compares f4ree space on disks C: and D:.
+
+```json
+"probes": [
+    {
+        "type": "DiskInfo",
+        "alias": "FirstDisk",
+        "params": {
+            "DiskName": "C:"
+        }
+    },
+    {
+        "type": "DiskInfo",
+        "alias": "SecondDisk",
+        "params": {
+            "DiskName": "D:"
+        }
+    }
+],
+"condition": {
+    "greater": [
+        "@FirstDisk::FreeSpace",
+        "@SecondDisk::FreeSpace"
+    ]
+}
+```
+
+## Using data from another probe
+
+Data returned by one probe can be passed to another one as a parameter. The expression for the parameter should contain the output variable name prefixed with the previous probe id or alias.
+
+In the following example *DatabaseMasterFiles* probe finds volume IDs for all disks used by the target database. The *AzStorage* probe is called for each volume ID and adds  Azure related storage properties along with volume ID.
+
+```json
+"probes": [
+    {
+        "id": "DatabaseMasterFiles",
+        "alias": "db_files",
+        "params": {
+            "dbId": null,
+            "type": null
+        },
+        "transform": [
+            {
+                "type": "aggregate",
+                "group": [
+                    "volume_mount_point",
+                    "volume_id"
+                ]
+            },
+            {
+                "type": "aggregate",
+                "group": "volume_id",
+                "map": {
+                    "volume_mount_point": "join"
+                }
+            }
+        ]
+    },
+    {
+        "id": "AzStorage",
+        "params": {
+            "path": "@db_files::volume_id"
+        }
+    }
+]
+```
+
+
+
+
+

samples/manage/sql-assessment-api/docs/Customization/README.md

@@ -0,0 +1,12 @@
+# Customization
+
+The SQL Assessment API is a comprehensive solution that allows you not only to use the functionality that comes out of the box, but also customize the assessment workflows, depending on your needs.
+
+## In This Section
+
+- [Understanding rules and probes](RulesandProbes.md)
+- [Rule](Rule.md)
+- [Probe reference](ProbeReference.md)
+- [Probe](Probe.md)
+- [Data Transformation](DataTransformation.md)
+- [Local Variables](LocalVariables.md)

samples/manage/sql-assessment-api/docs/Customization/Rule.md

@@ -0,0 +1,65 @@
+# SQL Assessment API Rule
+
+A rule is represented by a JSON object. A rule applies its properties to a new or existing check.
+
+![Rule structure](img\RuleStructure.svg)
+
+## Rule properties
+
+### itemType
+
+__Allowed values:__ *definition*, *override*
+
+This property specifies whether this rule defines a new check or modifies an existing one. A check can be modified by more than one rule.
+
+### tags
+
+An array of short strings used to categorize checks. For example, checks marked with the "Memory" tag are coming from memory-related best practices. Single-word tags work best.
+
+### id
+
+An ID of the check to be defined or modified by this rule.  A check can be modified by more than one rule.
+
+An array of IDs or tags of checks to be modified by this rule. A rule can modify multiple checks at once. Checks are selected either by ID or by tag. If multiple tags are specified, every check having _any_ listed tag will be affected by this rule.
+
+### target
+
+Target pattern is a JSON object used to select applicable rules. A rule will be applied if the assessed object matches the `target` pattern. For more information, see [Target pattern]().
+
+### targetFilter
+
+Target pattern with the same syntax as the target property, but used exclusively in overrides. For more information on the usage and object format, see [Overrides]() and [Target pattern](), respectively.
+
+### displayName
+
+Short display names are shown in checklists. You may think of a display name as of a file name if a rule was stored in a separate file. Usually, the display name tells what the check is looking for.
+
+### message
+
+A string which is used as a template for generating messages to the user. Such a message appears when the check detects configurations that are not in compliance with the best practice recommendation. For more information, see [Message template]().
+
+### description
+
+Long description that explains why the check looks for this particular issue. It briefly discusses the impact of the detected issue.
+
+### helpLink
+
+Hyperlink to an article that explains the best practice recommendations and remediation suggestions.
+
+### level
+
+__Allowed values:__ `Information`, `Low`, `Medium`, 'High'
+
+The severity level of the issue detected by this check.
+
+### probes
+
+The `probes` array contains references to probes to be used to get data required by this check. For more information, see [Probe References]().
+
+### condition
+
+Condition is an expression in form of JSON object tree. It uses check parameters and data from probes This expression should return _true_ when the best practice found implemented. If condition evaluates to _false_, the message is displayed to the user.
+
+### parameters
+
+Arbitrary properties passed to conditions, message templates, probe parameters, and transforms along with the data from probes.

samples/manage/sql-assessment-api/docs/Customization/RulesandProbes.md

@@ -0,0 +1,95 @@
+# Understanding rules and probes
+
+The SQL Assessment API uses sets of best practice recommendations to check if a SQL Server environment or configuration could be improved. Best practices are not universal. Guidelines depend on SQL Server version, edition, and configuration, hosting platform, and even usage pattern. For example, some best practices are applicable only to cloud environments, whereas others work for SQL Server instances installed on a physical machine. Databases may also be of different types. For example, a set of best practices for the `msdb` database might be different from that used for user databases. 
+
+SQL Assessment API makes recommendations more specific by implementing a two-step process:
+
+1. Build a checklist for the given target
+
+    Such a checklist contains a complete set of checks, depending on the specified target.
+
+2. Go through the checklist and report every best practice violation
+
+    At this step, the SQL Assessment API goes through the checklist to validate whether the given target satisfies the given best practice.
+
+The checklist construction process is based on rules. Each rule either defines a new check or modifies one or more of the existing ones. Rules are stored in rulesets. Each ruleset has its own name and version. Users can add multiple rulesets to the SQL Assessment API engine one by one. While building the checklist, the engine will apply rules in the order they were added.
+
+A single check can be affected by multiple rules. The first rule must define the check and assign a unique string ID. Checks may have tags that allow managing them in groups. The following rules override checks referred by IDs or tags, which gives the override the ability to modify multiple checks at once.
+
+For example, the following rule makes a check with the `MaxMemory` ID appear in the checklist for all SQL Server 2012 instances and higher. Note that the rule sets the `limit` parameter to 2147483647.
+
+```json
+{
+    "id": "MaxMemory",
+    "itemType": "definition",
+    "target": 
+    {
+        "type": "Server",
+        "version": "[11.0,)"
+    },
+    "limit": 2147483647
+}
+```
+
+The rule below modifies the limit parameter for the `MaxMemory` check defined above.
+
+```json
+{
+    "id": "MaxMemory",
+    "itemType": "override",
+    "limit": 2000000000
+}
+```
+
+Note that the rule override can modify checks for selected targets if needed. The following rules modify the limit of the `MaxMemory` check for specific SQL Server editions.
+
+```json
+{
+    "id": "MaxMemory",
+    "itemType": "override",
+    "targetFilter": 
+    {
+        "engineEdition": "Standard"
+    },
+    "limit": 131072
+},
+
+{
+    "id": "MaxMemory",
+    "itemType": "override",
+    "targetFilter": 
+    {
+        "engineEdition": "Express"
+    },
+    "limit": 1410
+}
+```
+
+Having a check in the checklist does not mean this check will be run by the assessment engine. Each check has the `enabled` property which is set to *true* by default. If the property becomes false after all rules are applied, the engine will skip the check.
+
+The following rule disables the `MaxMemory` check and all performance-related checks for all instances running on Linux.
+
+```json
+{
+    "id": [ "MaxMemory", "Performance" ],
+    "itemType": "override",
+    "targetFilter": {
+        "platform": "Linux"
+    },
+    "enabled": false
+}
+```
+
+Each check needs data to analyze. Checks do not retrieve any data from the target server or database but refer to *probes* instead. Most of the probes use T-SQL queries, but the SQL Assessment API also supports probes for WMI, Windows registry, Azure Instance Metadata Service, as well as custom probes implemented as .NET classes.
+
+Each probe returns zero or more data rows containing named items. If a check gets data from multiple probes, the resulting data set is constructed as *all* combinations of rows. This behavior is similar to `CROSS JOIN` in T-SQL. 
+
+A check has a condition expression which formally describes best practice as an arithmetic expression referring to data from a data row. Condition is calculated and checked if it holds for each row separately. For example, when a database uses 3 disks for storing its files, then a free space best practice may apply to each disk independently. If a check uses data from two probes, and one probe produces 2 rows while another one produces 3, the check condition will be evaluated 2×3=6 times. If condition gives *false* 2 times out of 6, the check will produce 2 messages.
+
+At the same time, probe implementation may depend on the SQL Server version. For example, dynamic management views may vary between  SQL Server releases. This is why a probe may have multiple implementations. Each implementation has a target specification, the same way the rules do. The assessment engine uses  the most appropriate implementation for each target.
+
+## Related topics
+
+- [Probes](../Reference/Probes/README.md)
+- [Tutorials](../Tutorials/README.md)
+- [How-To](../How-To/README.md)