Skip to content

Commit 4c859cf

Browse files
LordHepipudLordHepipud
authored
Merge pull request #203 from Icinga:doc/adds_code_cache_docs
Adds code caching docs and removes experimental Removes experimental state of the Icinga PowerShell Framework code caching and adds docs on how to use the feature
2 parents ee03d74 + 27e8bca commit 4c859cf

7 files changed

+63
-16
lines changed

‎doc/06-Framework-Usage.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
88
* [Enable Proxy Server](frameworkusage/02-Enable-Proxy-Server.md)
99
* [Install Wizard Guide](frameworkusage/03-Install-Wizard-Guide.md)
1010
* [Disable Certificate Validation](frameworkusage/04-Disable-Certificate-Validation.md)
11+
* [Enable Framework Code Caching](frameworkusage/05-Enable-Framework-Code-Caching.md)
1112

1213
## Icinga Agent Management
1314

@@ -17,4 +18,4 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
1718
* [Run Icinga Agent as other Service User](frameworkusage/33-Run-Icinga-Agent-As-Other-Service-User.md)
1819
* [Install/Update Icinga Agent](frameworkusage/35-Install-Update-Icinga-Agent.md)
1920
* [Uninstall Icinga Agent](frameworkusage/34-Uninstall-Icinga-Agent.md)
20-
* [Flush Icinga Agent API Directory](frameworkusage/36-Flush-Icinga-Agent-API-Directory.md)
21+
* [Flush Icinga Agent API Directory](frameworkusage/36-Flush-Icinga-Agent-API-Directory.md)

‎doc/31-Changelog.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
1515

1616
* [#193](https://github.com/Icinga/icinga-powershell-framework/pull/193) Adds optional support for adding milliseconds to `Get-IcingaUnixTime` with the `-Milliseconds` argument for more detailed time comparison
1717
* [#198](https://github.com/Icinga/icinga-powershell-framework/pull/198) Adds support to flush the content of the Icinga Agent API directory with a single Cmdlet `Clear-IcingaAgentApiDirectory`
18+
* [#203](https://github.com/Icinga/icinga-powershell-framework/pull/203) Removes experimental state of the Icinga PowerShell Framework code caching and adds docs on how to use the feature
1819

1920
## 1.3.1 (2021-02-04)
2021

‎doc/frameworkusage/05-Enable-Framework-Code-Caching.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Enable Framework Code Caching
2+
3+
On certain systems with fewer CPU cores, there might be an impact while running Icinga for Windows because of long loading times for the Icinga PowerShell Framework. To mitigate this issue, we added the possibility to create a code cache file for the entire Icinga PowerShell Framework.
4+
5+
What it does is to load every single module and content file into one single `cache.psm1` file which is loaded in case the caching is enabled.
6+
7+
## Pre-Cautions
8+
9+
By enabling this feature, you will have to generate a new cache file whenever you apply changes to any code for the Icinga PowerShell Framework. This can be done by running the Cmdlet
10+
11+
```powershell
12+
Write-IcingaFrameworkCodeCache
13+
```
14+
15+
Please note that the code cache feature must be enabled first.
16+
17+
In case you upgrade to a newer version of the Icinga PowerShell Framework, you will only require to manually proceed in case the code cache feature was disabled beforehand. In case the code cache feature is enabled during the upgrade, the cache file will be generated and updated automatically.
18+
19+
## Enable Icinga Framework Code Cache
20+
21+
To enable the Icinga PowerShell Framework code cache, simply run the following command within an Icinga Shell:
22+
23+
```powershell
24+
Enable-IcingaFrameworkCodeCache
25+
```
26+
27+
Once activated, you should make sure to generate a new cache file before using the Framework:
28+
29+
```powershell
30+
Write-IcingaFrameworkCodeCache
31+
```
32+
33+
If you leave the code caching feature enabled, future updates of the Framework will automatically generate a new cache file. If you disabled the feature in-between, please write the cache file manually.
34+
35+
In case no cache file is present while the feature is activated, a cache file is generated on the first use of `Use-Icinga` or `icinga`.
36+
37+
## Disable Icinga Framework Code Cache
38+
39+
To disable the code caching feature again, you can simply run
40+
41+
```powershell
42+
Disable-IcingaFrameworkCodeCache
43+
```
44+
45+
Please note that even though the cache file is no longer loaded it still remains. Therefor you will have to manually use `Write-IcingaFrameworkCodeCache` in case you activate the feature later again. This is especially required if you update the Icinga PowerShell Framework while the feature was disabled.

‎icinga-powershell-framework.psm1

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ function Write-IcingaFrameworkCodeCache()
9393
if (Get-IcingaFrameworkCodeCache) {
9494
Import-IcingaLib '\' -Init -CompileCache;
9595
} else {
96-
Write-IcingaConsoleNotice 'The experimental code caching feature is currently not enabled. You can enable it with "Enable-IcingaFrameworkCodeCache"';
96+
Write-IcingaConsoleNotice 'The code caching feature is currently not enabled. You can enable it with "Enable-IcingaFrameworkCodeCache"';
9797
}
9898
}
9999

@@ -332,7 +332,7 @@ function Invoke-IcingaCommand()
332332
Write-Output ([string]::Format('** Copyright {0}', $IcingaFrameworkData.Copyright));
333333
Write-Output ([string]::Format('** User environment {0}\{1}', $env:USERDOMAIN, $env:USERNAME));
334334
if (Get-IcingaFrameworkCodeCache) {
335-
Write-Output ([string]::Format('** Warning: Icinga Framework Code Caching is enabled'));
335+
Write-Output ([string]::Format('** Note: Icinga Framework Code Caching is enabled'));
336336
}
337337
Write-Output '******************************************************';
338338
}

‎lib/core/framework/Disable-IcingaFrameworkCodeCache.psm1

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
<#
22
.SYNOPSIS
3-
Disables the experimental feature to cache all functions into a single file,
3+
Disables the feature to cache all functions into a single file,
44
allowing quicker loading times of the Icinga PowerShell Framework
55
.DESCRIPTION
6-
Disables the experimental feature to cache all functions into a single file,
6+
Disables the feature to cache all functions into a single file,
77
allowing quicker loading times of the Icinga PowerShell Framework
88
.FUNCTIONALITY
9-
Experimental: Disables the Icinga for Windows code caching
9+
Disables the Icinga for Windows code caching
1010
.EXAMPLE
1111
PS>Disable-IcingaFrameworkCodeCache;
1212
.LINK
@@ -15,5 +15,5 @@
1515

1616
function Disable-IcingaFrameworkCodeCache()
1717
{
18-
Set-IcingaPowerShellConfig -Path 'Framework.Experimental.CodeCaching' -Value $FALSE;
18+
Set-IcingaPowerShellConfig -Path 'Framework.CodeCaching' -Value $FALSE;
1919
}

‎lib/core/framework/Enable-IcingaFrameworkCodeCache.psm1

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
<#
22
.SYNOPSIS
3-
Enables the experimental feature to cache all functions into a single file,
3+
Enables the feature to cache all functions into a single file,
44
allowing quicker loading times of the Icinga PowerShell Framework
55
.DESCRIPTION
6-
Enables the experimental feature to cache all functions into a single file,
6+
Enables the feature to cache all functions into a single file,
77
allowing quicker loading times of the Icinga PowerShell Framework
88
.FUNCTIONALITY
9-
Experimental: Enables the Icinga for Windows code caching
9+
Enables the Icinga for Windows code caching
1010
.EXAMPLE
1111
PS>Enable-IcingaFrameworkCodeCache;
1212
.LINK
@@ -15,7 +15,7 @@
1515

1616
function Enable-IcingaFrameworkCodeCache()
1717
{
18-
Set-IcingaPowerShellConfig -Path 'Framework.Experimental.CodeCaching' -Value $TRUE;
18+
Set-IcingaPowerShellConfig -Path 'Framework.CodeCaching' -Value $TRUE;
1919

20-
Write-IcingaConsoleWarning 'This is an experimental feature and might cause some side effects during usage. Please use this function with caution. Please run "Write-IcingaFrameworkCodeCache" in addition to ensure your cache is updated. This should be done after each update of the Framework in case the feature was disabled during the update run.';
20+
Write-IcingaConsoleWarning 'Please run "Write-IcingaFrameworkCodeCache" in addition to ensure your cache is updated. This should be done after each update of the Framework in case the feature was disabled during the update run.';
2121
}

‎lib/core/framework/Get-IcingaFrameworkCodeCache.psm1

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
<#
22
.SYNOPSIS
3-
Fetches the current enable/disable state of the experimental feature
3+
Fetches the current enable/disable state of the feature
44
for caching the Icinga PowerShell Framework code
55
.DESCRIPTION
6-
Fetches the current enable/disable state of the experimental feature
6+
Fetches the current enable/disable state of the feature
77
for caching the Icinga PowerShell Framework code
88
.FUNCTIONALITY
9-
Experimental: Get the current code caching configuration of the
9+
Get the current code caching configuration of the
1010
Icinga PowerShell Framework
1111
.EXAMPLE
1212
PS>Get-IcingaFrameworkCodeCache;
@@ -18,7 +18,7 @@
1818

1919
function Get-IcingaFrameworkCodeCache()
2020
{
21-
$CodeCaching = Get-IcingaPowerShellConfig -Path 'Framework.Experimental.CodeCaching';
21+
$CodeCaching = Get-IcingaPowerShellConfig -Path 'Framework.CodeCaching';
2222

2323
if ($null -eq $CodeCaching) {
2424
return $FALSE;

0 commit comments

Comments
 (0)