PSRule.Monitor/README.md

# PSRule to Azure Monitor

Log PSRule analysis results to Azure Monitor.

![ci-badge]

## Support

This project uses GitHub Issues to track bugs and feature requests.
Please search the existing issues before filing new issues to avoid duplicates.

- For new issues, file your bug or feature request as a new [issue].
- For help, discussion, and support questions about using this project, join or start a [discussion].

If you have any problems with the [PSRule][engine] engine, please check the project GitHub [issues](https://github.com/Microsoft/PSRule/issues) page instead.

Support for this project/ product is limited to the resources listed above.

## Getting the modules

This project requires the `PSRule` PowerShell module. For details on each see [install].

You can download and install these modules from the PowerShell Gallery.

Module             | Description | Downloads / instructions
------             | ----------- | ------------------------
PSRule.Monitor     | Log PSRule analysis results to Azure Monitor. | [latest][module] / [instructions][install]

## Getting started

### Upload results

To upload results from PSRule to Azure Monitor, use the `Send-PSRuleMonitorRecord` cmdlet.
Results can by piped directly from `Invoke-PSRule` or stored and piped from a variable.

The `Send-PSRuleMonitorRecord` cmdlet requires a Log Analytics workspace to send data to.
A workspace can be specified by using the `-WorkspaceId` and `-SharedKey` parameters.

For example:

```powershell
$data | Invoke-PSRule | Send-PSRuleMonitorRecord -WorkspaceId <workspaceId> -SharedKey <primaryKey>;
```

The following example shows using analysis results from a pre-built module:

```powershell
$results = Invoke-PSRule -InputPath .\*.json -Module 'PSRule.Rules.Azure';
$results | Send-PSRuleMonitorRecord -WorkspaceId <workspaceId> -SharedKey <primaryKey>;
```

### Querying logs from Azure Monitor

By default, PSRule results are stored in the `PSRule_CL` table.
The following query returns all rule records from the last hour that failed:

```text
PSRule_CL
| where Outcome_s == "Fail" and TimeGenerated > ago(1h)
```

To query these results from PowerShell use:

```powershell
Invoke-AzOperationalInsightsQuery -WorkspaceId <workspaceId> -Query 'PSRule_CL | where Outcome_s == "Fail" and TimeGenerated > ago(1h)'
```

## Language reference

### Commands

The following commands exist in the `PSRule.Monitor` module:

- [Send-PSRuleMonitorRecord](docs/commands/PSRule.Monitor/en-US/Send-PSRuleMonitorRecord.md) - Send analysis results from PSRule to Azure Monitor.

## Changes and versioning

Modules in this repository will use the [semantic versioning](http://semver.org/) model to declare breaking changes from v1.0.0.
Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments.
For a list of module changes please see the [change log](CHANGELOG.md).

> Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery.
> Pre-release versions should be considered experimental.
> Modules and change log details for pre-releases will be removed as standard releases are made available.

## Contributing

This project welcomes contributions and suggestions.
If you are ready to contribute, please visit the [contribution guide](CONTRIBUTING.md).

## Code of Conduct

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

## Maintainers

- [Bernie White](https://github.com/BernieWhite)

## License

This project is [licensed under the MIT License](LICENSE).

[install]: docs/scenarios/install-instructions.md
[ci-badge]: https://dev.azure.com/bewhite/PSRule.Monitor/_apis/build/status/PSRule.Monitor-CI?branchName=main
[module]: https://www.powershellgallery.com/packages/PSRule.Monitor
[engine]: https://github.com/Microsoft/PSRule
[issue]: https://github.com/Microsoft/PSRule.Monitor/issues
[discussion]: https://github.com/microsoft/PSRule.Monitor/discussions