Get-HgsTrace
Collects and analyzes data relevant to the operation of a guarded fabric.
Syntax
Get-HgsTrace
[-Collector <String[]>]
[-Target <InputTarget[]>]
[[-Path] <String>]
[-WriteManifest]
[-Detailed]
[-Compact]
[-Diagnostic <String[]>]
[<CommonParameters>] Get-HgsTrace
[-RunDiagnostics]
[-Target <InputTarget[]>]
[[-Path] <String>]
[-WriteManifest]
[-Detailed]
[-Compact]
[-Diagnostic <String[]>]
[<CommonParameters>] Description
The Get-HgsTrace cmdlet collects and analyzes data relevant to the operation of a guarded fabric, diagnosing confirmed and potential failures in the environment that will impact the operation of the Host Guardian Service (HGS), guarded hosts, and shielded virtual machines.
Examples
Example 1: Diagnose the local host
PS C:\> Get-HgsTrace -RunDiagnosticsThis command diagnoses the local host. The traces are stored in a temporary folder and diagnosis results are reported to the user.
Example 2: Collect traces from the specified target
PS C:\> Get-HgsTrace -Target $VMhost -Path ".\Traces"This command collects traces from the target specified in the VMhost variable. The command then stores the trace files to the specified path. Since the RunDiagnostics parameter is not used, the cmdlet does not run diagnostics against the collected targets.
Example 3: Diagnose multiple targets
PS C:\> Get-HgsTrace -Target $VMhost,$Server -RunDiagnosticsThis command runs diagnostics on the targets stored in the $VMHost and $Server variables.
Example 4: Diagnose the local host using hardware
PS C:\> Get-HgsTrace -RunDiagnostics -Diagnostic "Hardware"This command runs diagnostics named Hardware on the local host.
Example 5: Diagnose previously collected traces stored in the specified folder
PS C:\> Get-HgsTrace -RunDiagnostics -Path ".\GatheredTraces"This command runs diagnostics on collected traces that are stored in the folder named GatheredTraces.
Parameters
-Collector
Specifies a list of collectors to be executed when gathering traces. This parameter is used to collect only specific traces when you do not specify a list of diagnostics and you do not run diagnostics with the RunDiagnostics switch.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Compact
Indicates that the output object is provided should be a minimal subset of the results generated instead of the complete result set. This switch parameter is ignored if more than one target is provided.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Detailed
Specifies that the output object has full details, which includes all results omitted from the default output report.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Diagnostic
Specifies a list of diagnostics that are run if you also provide the RunDiagnostics switch parameter. If you do not provide the RunDiagnostics switch parameter, this list of diagnostics is used to determine which collectors are executed. Diagnostics and collectors whose requirements are not satisfied by the provided targets will not be executed.
| Type: | String[] |
| Accepted values: | Base, All, GuardedFabric, GuardedFabricTpmMode, GuardedFabricADMode, BestPractices, GuardedHost, HostGuardianService, Networking, Https, Hardware |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Path
Specifies an absolute or relative path to a folder where trace files are stored. If the folder already exists, any traces contained therein are reused. New traces are collected to augment existing traces if they are missing from the pre-populated traces.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-RunDiagnostics
Indicates that diagnostics are immediately run against the collected traces and that the result set describes the result of diagnosing the collected information.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Target
Specifies a list of targets created by New-HgsTraceTarget to be traced and diagnosed. If no targets are provided, but a collection path has been specified, the path is searched for pre-existing traces to be analyzed. If none are found, the localhost is targeted using the current session's credentials inferring the host's role from installed Windows features.
| Type: | InputTarget[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-WriteManifest
Indicates that a manifest of all trace files collected are written. This can then be used by the Get-HgsTraceFileData cmdlet to get secured information about trace files.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
Microsoft.Windows.HostGuardianService.Diagnostics.Payload.InputTarget
This cmdlet pipes one or more targets created with New-HgsTraceTarget to trace and diagnose.
Outputs
Microsoft.Windows.HostGuardianService.Diagnostics.Payload.RemoteResultSet
This cmdlet returns a collection of results for various operations and tests performed on the provided targets. These results are grouped by target and category with each group possessing an aggregate result that reflects the status of all child operation.