PowerShell/tools/ResxGen/ResxGen.ps1

62 lines
1.6 KiB
PowerShell
Raw Normal View History

# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.
Redirect ETW logging to Syslog on Linux (#5144) This PR is divided into the following areas: 1. Add/Rename the PowerShell/Windows ETW manifest to the repo and change both the provider id (guid) and name. See #4939. The manifest is at tools/resxgen/PowerShell-Core-Instrumentation.man 2. Generate a resx file containing the string resources needed for logging ETW events to syslog. This is accomplished by tools\resxgen\resxgen.psm1 and resxgen.ps1. The tool generates two files A resx file containing string resources for each message string from the manifest. This is generated in the System.Management.Automation\gen directory. A C# class (EventResource) that provides the mapping between the integer event id and the associated string resource name. The file is generated in the System.Management.Automation\CoreCLR directory with a compile-time condition of UNIX NOTE: The EventResource.cs class generated by resgen is explicitly ignored in the csproj file; it is not used. 3. SMA\utils\tracing\PSSysLogProvider.cs Implements the abstract LogProvider class and is the syslog equivalent of PSEtwLogProvider. The class contains a number of logical methods for logging lifecycle, health, and normal events. 4. SMA\utils\tracing\SysLogProvider.cs This is the Syslog equivalent of ETW's log provider class and implements a Log method versus ETW's EventWrite. It is also responsible for resolving event ids to resource names and performing the Syslog call. There is a large comment block in the class XML doc that describes the types of log output it produces. 5. SMA\utils\tracing\PSEtwLog.cs PowerShell's current implementation is tightly coupled to this class; with code calling it directly for all events. To simplify integration of syslog, I updated the class to create an instance of PSSysLogProvider on Linux and removed the Linux-specific stub file. 6. SMA\engine\PropertyAccessor.cs This class provides a wrapper around PowerShellProperties.json and has been extended to have Unix-specific assessors for configuring logging. Note that the file is expected to be in the $PSHOME directory to ensure SxS. Currently, there are four configuration properties: - LogIdentity - the string identifier for the source application. This defaults to 'powershell' and can be configured to enable distinguishing between side-by-side installations. - LogLevel - configures the tracing level (log level). Informational is the defauilt. - LogChannels - used to enable operational and analytic logging. Operational is the default. - LogKeywords - used to configure enabling tracing by keyword. All keywords other than `UseAlwaysAnalytic` are enabled by default. NOTE: This will likely change. PowerShell sometimes confuses the analytic channel with this keyword and sends logging to the wrong channel. Once this is cleared up, `UseAlwaysAnalytic` and `UseAlwaysOperational` keywords will likely be removed. Additional Notes: 1. The current implementation writes directly to syslog and writing to a separate log file is still pending. 2. The generated class and resx are not part of the build; instead, it is expected that Resxgen should be run when events are added to the manifest. To fully automate the process, resxgen will need to be updated to generate the other dependent enums such as 'PSChannel', 'PSEventId', 'PSTask', 'PSOpcode', etc. You will see parsing logic in resxgen.psm1 to prepare for that but it is not enabled at this point. 4. Documentation is pending that documents the format of the syslog output as well as associated configuration. 5. As mentioned at the start, tests are pending
2017-11-06 17:32:29 +01:00
<#
.SYNOPSIS
Generates a resx file and code file from an ETW manifest
for use with UNIX builds.
.PARAMETER Manifest
The path to the ETW manifest file to read.
.PARAMETER Name
The name to use for the C# class, the code file, and the resx file.
The default value is EventResource.
.PARAMETER Namespace
The namespace to place the C# class.
The default is System.Management.Automation.Tracing.
.PARAMETER ResxPath
The path to the directory to use to create the resx file.
.PARAMETER CodePath
The path to the directory to use to create the C# code file.
.EXAMPLE
.\tools\ResxGen\ResxGen.ps1 -Manifest .\src\PowerShell.Core.Instrumentation\PowerShell.Core.Instrumentation.man -ResxPath .\src\System.Management.Automation\resources -CodePath .\src\System.Management.Automation\CoreCLR
Redirect ETW logging to Syslog on Linux (#5144) This PR is divided into the following areas: 1. Add/Rename the PowerShell/Windows ETW manifest to the repo and change both the provider id (guid) and name. See #4939. The manifest is at tools/resxgen/PowerShell-Core-Instrumentation.man 2. Generate a resx file containing the string resources needed for logging ETW events to syslog. This is accomplished by tools\resxgen\resxgen.psm1 and resxgen.ps1. The tool generates two files A resx file containing string resources for each message string from the manifest. This is generated in the System.Management.Automation\gen directory. A C# class (EventResource) that provides the mapping between the integer event id and the associated string resource name. The file is generated in the System.Management.Automation\CoreCLR directory with a compile-time condition of UNIX NOTE: The EventResource.cs class generated by resgen is explicitly ignored in the csproj file; it is not used. 3. SMA\utils\tracing\PSSysLogProvider.cs Implements the abstract LogProvider class and is the syslog equivalent of PSEtwLogProvider. The class contains a number of logical methods for logging lifecycle, health, and normal events. 4. SMA\utils\tracing\SysLogProvider.cs This is the Syslog equivalent of ETW's log provider class and implements a Log method versus ETW's EventWrite. It is also responsible for resolving event ids to resource names and performing the Syslog call. There is a large comment block in the class XML doc that describes the types of log output it produces. 5. SMA\utils\tracing\PSEtwLog.cs PowerShell's current implementation is tightly coupled to this class; with code calling it directly for all events. To simplify integration of syslog, I updated the class to create an instance of PSSysLogProvider on Linux and removed the Linux-specific stub file. 6. SMA\engine\PropertyAccessor.cs This class provides a wrapper around PowerShellProperties.json and has been extended to have Unix-specific assessors for configuring logging. Note that the file is expected to be in the $PSHOME directory to ensure SxS. Currently, there are four configuration properties: - LogIdentity - the string identifier for the source application. This defaults to 'powershell' and can be configured to enable distinguishing between side-by-side installations. - LogLevel - configures the tracing level (log level). Informational is the defauilt. - LogChannels - used to enable operational and analytic logging. Operational is the default. - LogKeywords - used to configure enabling tracing by keyword. All keywords other than `UseAlwaysAnalytic` are enabled by default. NOTE: This will likely change. PowerShell sometimes confuses the analytic channel with this keyword and sends logging to the wrong channel. Once this is cleared up, `UseAlwaysAnalytic` and `UseAlwaysOperational` keywords will likely be removed. Additional Notes: 1. The current implementation writes directly to syslog and writing to a separate log file is still pending. 2. The generated class and resx are not part of the build; instead, it is expected that Resxgen should be run when events are added to the manifest. To fully automate the process, resxgen will need to be updated to generate the other dependent enums such as 'PSChannel', 'PSEventId', 'PSTask', 'PSOpcode', etc. You will see parsing logic in resxgen.psm1 to prepare for that but it is not enabled at this point. 4. Documentation is pending that documents the format of the syslog output as well as associated configuration. 5. As mentioned at the start, tests are pending
2017-11-06 17:32:29 +01:00
#>
[CmdletBinding()]
param
(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string] $Manifest,
[string] $Name = 'EventResource',
[Parameter()]
[ValidateNotNullOrEmpty()]
[string] $Namespace = 'System.Management.Automation.Tracing',
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string] $ResxPath,
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string] $CodePath
)
Import-Module $PSScriptRoot\ResxGen.psm1 -Force
Redirect ETW logging to Syslog on Linux (#5144) This PR is divided into the following areas: 1. Add/Rename the PowerShell/Windows ETW manifest to the repo and change both the provider id (guid) and name. See #4939. The manifest is at tools/resxgen/PowerShell-Core-Instrumentation.man 2. Generate a resx file containing the string resources needed for logging ETW events to syslog. This is accomplished by tools\resxgen\resxgen.psm1 and resxgen.ps1. The tool generates two files A resx file containing string resources for each message string from the manifest. This is generated in the System.Management.Automation\gen directory. A C# class (EventResource) that provides the mapping between the integer event id and the associated string resource name. The file is generated in the System.Management.Automation\CoreCLR directory with a compile-time condition of UNIX NOTE: The EventResource.cs class generated by resgen is explicitly ignored in the csproj file; it is not used. 3. SMA\utils\tracing\PSSysLogProvider.cs Implements the abstract LogProvider class and is the syslog equivalent of PSEtwLogProvider. The class contains a number of logical methods for logging lifecycle, health, and normal events. 4. SMA\utils\tracing\SysLogProvider.cs This is the Syslog equivalent of ETW's log provider class and implements a Log method versus ETW's EventWrite. It is also responsible for resolving event ids to resource names and performing the Syslog call. There is a large comment block in the class XML doc that describes the types of log output it produces. 5. SMA\utils\tracing\PSEtwLog.cs PowerShell's current implementation is tightly coupled to this class; with code calling it directly for all events. To simplify integration of syslog, I updated the class to create an instance of PSSysLogProvider on Linux and removed the Linux-specific stub file. 6. SMA\engine\PropertyAccessor.cs This class provides a wrapper around PowerShellProperties.json and has been extended to have Unix-specific assessors for configuring logging. Note that the file is expected to be in the $PSHOME directory to ensure SxS. Currently, there are four configuration properties: - LogIdentity - the string identifier for the source application. This defaults to 'powershell' and can be configured to enable distinguishing between side-by-side installations. - LogLevel - configures the tracing level (log level). Informational is the defauilt. - LogChannels - used to enable operational and analytic logging. Operational is the default. - LogKeywords - used to configure enabling tracing by keyword. All keywords other than `UseAlwaysAnalytic` are enabled by default. NOTE: This will likely change. PowerShell sometimes confuses the analytic channel with this keyword and sends logging to the wrong channel. Once this is cleared up, `UseAlwaysAnalytic` and `UseAlwaysOperational` keywords will likely be removed. Additional Notes: 1. The current implementation writes directly to syslog and writing to a separate log file is still pending. 2. The generated class and resx are not part of the build; instead, it is expected that Resxgen should be run when events are added to the manifest. To fully automate the process, resxgen will need to be updated to generate the other dependent enums such as 'PSChannel', 'PSEventId', 'PSTask', 'PSOpcode', etc. You will see parsing logic in resxgen.psm1 to prepare for that but it is not enabled at this point. 4. Documentation is pending that documents the format of the syslog output as well as associated configuration. 5. As mentioned at the start, tests are pending
2017-11-06 17:32:29 +01:00
try
{
ConvertTo-Resx -Manifest $Manifest -Name $Name -ResxPath $ResxPath -CodePath $CodePath -Namespace $Namespace
}
finally
{
Remove-Module ResxGen -Force -ErrorAction Ignore
}