CI Logging Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Continuous Integration (CI) logging within the PowerShell project serves as a critical diagnostic and reporting framework. It encompasses engine-level event sourcing, automated test reporting for GitHub Actions, and progress tracking for asynchronous operations such as updatable help systems. These guidelines ensure that logs are structured for both human readability and automated parsing by CI pipelines.
The scope of CI logging includes capturing engine health events, monitoring runspace initialization, and validating the integrity of source code through specialized CI modules that detect merge conflicts and environment-specific markers.
Sources: InitialSessionState.cs:2020-2050, ciModule.Tests.ps1:10-30
Engine Event Sourcing and Runspace Diagnostics
The PowerShell engine utilizes the RunspaceEventSource class, derived from EventSource, to provide structured diagnostic information during the lifecycle of a runspace. This mechanism is primarily intended for performance monitoring and troubleshooting during engine startup and configuration in CI environments.
Runspace Lifecycle Events
The system logs start and stop events for major initialization phases, allowing CI runners to identify bottlenecks or failures in specific subsystems.
Sources: InitialSessionState.cs:2020-2046
Event ID Reference
| Event ID | Method Name | Description |
|---|---|---|
| 1 / 2 | OpenRunspace | Marks the beginning and end of runspace activation. |
| 3 / 4 | LoadAssemblies | Tracks the loading of external binaries into the engine. |
| 5 / 6 | UpdateFormatTable | Diagnostic tracking for formatting data processing. |
| 7 / 8 | UpdateTypeTable | Diagnostic tracking for type metadata processing. |
| 13 / 14 | LoadVariables | Monitors the binding of initial variables. |
| 15 / 16 | LoadEnvVariables | Monitors the environment variable configuration. |
Sources: InitialSessionState.cs:2025-2045
CI Module Logging and GitHub Actions Output
The infrastructure testing suite includes specific functions designed to communicate directly with GitHub Actions. The Test-MergeConflictMarker function demonstrates the standard for CI-specific reporting, using key-value pairs to set output variables for subsequent workflow steps.
Automated Reporting Format
When running in a CI environment, scripts must generate outputs in a format compatible with GitHub Actions environment files. This includes tracking file counts and found errors.
| Output Parameter | Format | Purpose |
|---|---|---|
files-checked | files-checked=N | Reports total number of files scanned by the CI task. |
conflicts-found | conflicts-found=N | Reports the number of failures (e.g., merge markers found). |
Sources: ciModule.Tests.ps1:40-55
Conflict Detection Logic
The CI pipeline uses dynamic string generation (e.g., '<' * 7) to avoid triggering its own conflict detection logic during log scanning. This pattern is mandatory for logging infrastructure to prevent false positives.
Sources: ciModule.Tests.ps1:5-15
Updatable Help System Logging
Cmdlets like Update-Help and Save-Help implement specialized logging and progress reporting to handle network-heavy operations in CI pipelines. These logs are used to verify that help content is correctly retrieved, validated against XSD schemas, and installed.
Progress and Message Logging
Logging for help operations is abstracted through the UpdatableHelpCommandBase and UpdatableHelpSystem. Messages are logged via the PSEtwLog and MshLog providers.
Operational Errors
Significant failures during CI help updates (e.g., culture mismatches or network failures) are logged with a severity of "Error" and include the specific command context from MyInvocation.
Sources: UpdatableHelpCommandBase.cs:435-445
Exception and Health Logging Guidelines
The PowerShell project categorizes CI-relevant health events into two primary categories: operational exceptions and configuration failures.
Health Event Logging
The MshLog class is utilized during engine startup to record configuration failures. If a runspace fails to open due to invalid initial state, the system logs a EVENT_ID_CONFIGURATION_FAILURE.
- Severity: Warning or Error depending on whether
ThrowOnRunspaceOpenErroris enabled. - Context Capture: Includes the
ExecutionContextand the current command processor metadata.
Sources: InitialSessionState.cs:1220-1240
Diagnostic Task Execution
CI logs should also track the background task execution initialized by the EarlyStartup class. This includes tracking expensive CPU-bound tasks such as:
- AMSI content scanning warmup.
- Compiler local tuple type initialization.
- Type accelerator table population.
Sources: InitialSessionState.cs:30-65
Conclusion
Adhering to these CI logging guidelines ensures that PowerShell's automated pipelines remain robust and diagnosable. By utilizing structured event sourcing (RunspaceEventSource), adhering to GitHub Actions reporting formats, and leveraging ETW for deep diagnostics, developers can efficiently monitor engine behavior and codebase health across diverse CI environments.
Sources: InitialSessionState.cs:2020-2050, ciModule.Tests.ps1:190-210