Skip to content

Commit

Permalink
Update logging information for macOS (#11367)
Browse files Browse the repository at this point in the history 
* Update logging information for macOS

* Apply suggestions from code review

Co-authored-by: Mike F. Robbins <[email protected]>

---------

Co-authored-by: Mike F. Robbins <[email protected]>
  • Loading branch information
@sdwheeler @mikefrobbins
sdwheeler and mikefrobbins authored Aug 30, 2024
1 parent 64ce74c commit 94edd0e
Show file tree
Hide file tree
Showing 3 changed files with 123 additions and 189 deletions.
104 changes: 41 additions & 63 deletions reference/7.2/Microsoft.PowerShell.Core/About/about_Logging_Non-Windows.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: PowerShell logs internal operations from the engine, providers, and cmdlets.
Locale: en-US
ms.date: 01/03/2024
ms.date: 08/29/2024
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logging_non-windows?view=powershell-7.2&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about Logging Non-Windows
Expand All @@ -10,6 +10,7 @@ title: about Logging Non-Windows
# about_Logging_Non-Windows

## Short description

PowerShell logs internal operations from the engine, providers, and cmdlets.

## Long description
Expand Down Expand Up @@ -279,52 +280,20 @@ log file named `powershell.log`.
## Viewing PowerShell log data on macOS

PowerShell logs to Apple's unified logging system, a feature of macOS that
allows for the collection and storage of system and application logs in a single
centralized location.

Apple's unified logging system stores log messages in binary format. Use the
Console app or log tool to query the unified logging system for PowerShell
entries.

### Viewing PowerShell log data in the Console application on macOS

The **Console** application on macOS is a utility that provides a graphical user
interface for viewing log data. The **Console** application is included with
macOS by default and can be accessed by opening the **Utilities** folder in the
**Applications** folder.

Use the following steps to view PowerShell log data in the Console application
on macOS:

1. Search for the **Console** application and launch it.
1. Select the Machine name under **Devices**.
1. In the **Search** field, enter `pwsh` for the PowerShell main binary and
press <kbd>return</kbd>.
1. Change the search filter from `Any` to `Process`.
1. Click **Start**.
1. Run `pwsh` to generate PowerShell information to log.

The process ID for a running instance of PowerShell is stored in the `$PID`
variable. Use the following steps to filter on a specific process instance of
PowerShell in the **Console** application.

1. Run an instance of `pwsh`.
1. Run `$PID` in the instance of PowerShell started in the previous step to
determine its process ID.
1. Enter the process ID for `pwsh` in the **Search** field and press
<kbd>return</kbd>.
1. Change the search filter from `Any` to `PID`.
1. Click **Start**.
1. Generate PowerShell information to log from the instance of PowerShell
started in the first step.
allows for the collection and storage of system and application logs in a
single centralized location.

For more information, see [view log messages in Console on Mac][08].
Apple's unified logging system stores log messages in binary format. You must
use the `log` tool to query the unified logging system for PowerShell log
events. The PowerShell log events don't appear in the **Console** application
on macOS. Console app is designed for the older _syslog-based_ logging that
predates the unified logging system.

### Viewing PowerShell log data from the command line on macOS

To view PowerShell log data from a command line on macOS, use the `log` command
in the **Terminal** or other shell host application. These commands can be run
from **PowerShell**, **Z shell** (**Zsh**), or **Bash**.
from **PowerShell**, **Z Shell**, or **Bash**.

In the following example, the `log` command is used to show the log data on your
system as it's occurring in realtime. The **process** parameter filters the log
Expand All @@ -333,9 +302,38 @@ running, the **process** parameter also accepts a process ID as its value. The
**level** parameter shows messages at the specified level and below.

```powershell
log stream --process pwsh --level info
log stream --predicate "subsystem == 'com.microsoft.powershell'" --level info
```

The `log show` command can be used to export log items. The `log show` command
provides options for exporting the last `N` items, items since a given time, or
items within a given time span.

For example, the following command exports items since
`9am on April 5, 2022`:

```powershell
log show --start "2022-04-05 09:00:00" --predicate "subsystem == 'com.microsoft.powershell'"
```

For more information, run `log show --help` to view the help for the `log show`
command.

You can also output the log data in JSON format, which allows you to convert
the event data to PowerShell objects. The following example outputs the events
in JSON format. The `ConvertFrom-Json` cmdlet is used to convert the JSON data
to PowerShell objects are get stored in the `$logRecord` variable.

```powershell
log show --predicate "subsystem == 'com.microsoft.powershell'" --style json |
ConvertFrom-Json | Set-Variable logRecord
```

You may also want to consider saving the logs to a more secure location such as
[Security Information and Event Management (SIEM)][08] aggregator. Using
Microsoft Defender for Cloud Apps, you can set up SIEM in Azure. For more
information, see [Generic SIEM integration][01].

### Modes and levels of PowerShell log data on macOS

By default, the PowerShell subsystem logs info level messages to memory (mode)
Expand All @@ -357,25 +355,6 @@ PowerShell subsystem:
sudo log config --subsystem com.microsoft.powershell --reset
```

The `log show` command can be used to export log items. The `log show` command
provides options for exporting the last `N` items, items since a given time, or
items within a given time span.

For example, the following command exports items since
`9am on April 5 of 2022`:

```powershell
log show --info --start "2022-04-05 09:00:00" --process pwsh
```

For more information, run `log show --help` to view the help for the `log show`
command.

You may also want to consider saving the logs to a more secure location such as
[Security Information and Event Management (SIEM)][09] aggregator. Using
Microsoft Defender for Cloud Apps, you can set up SIEM in Azure. For more
information, see [Generic SIEM integration][01].

## See also

- For Linux **syslog** and **rsyslog.conf** information, refer to the Linux
Expand All @@ -393,5 +372,4 @@ information, see [Generic SIEM integration][01].
[05]: about_PowerShell_Config.md#modulelogging
[06]: about_PowerShell_Config.md#protectedeventlogging
[07]: https://developer.apple.com/documentation/os/logging
[08]: https://support.apple.com/guide/console/log-messages-cnsl1012/mac
[09]: https://wikipedia.org/wiki/Security_information_and_event_management
[08]: https://wikipedia.org/wiki/Security_information_and_event_management
104 changes: 41 additions & 63 deletions reference/7.4/Microsoft.PowerShell.Core/About/about_Logging_Non-Windows.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: PowerShell logs internal operations from the engine, providers, and cmdlets.
Locale: en-US
ms.date: 01/03/2024
ms.date: 08/29/2024
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logging_non-windows?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about Logging Non-Windows
Expand All @@ -10,6 +10,7 @@ title: about Logging Non-Windows
# about_Logging_Non-Windows

## Short description

PowerShell logs internal operations from the engine, providers, and cmdlets.

## Long description
Expand Down Expand Up @@ -279,52 +280,20 @@ log file named `powershell.log`.
## Viewing PowerShell log data on macOS

PowerShell logs to Apple's unified logging system, a feature of macOS that
allows for the collection and storage of system and application logs in a single
centralized location.

Apple's unified logging system stores log messages in binary format. Use the
Console app or log tool to query the unified logging system for PowerShell
entries.

### Viewing PowerShell log data in the Console application on macOS

The **Console** application on macOS is a utility that provides a graphical user
interface for viewing log data. The **Console** application is included with
macOS by default and can be accessed by opening the **Utilities** folder in the
**Applications** folder.

Use the following steps to view PowerShell log data in the Console application
on macOS:

1. Search for the **Console** application and launch it.
1. Select the Machine name under **Devices**.
1. In the **Search** field, enter `pwsh` for the PowerShell main binary and
press <kbd>return</kbd>.
1. Change the search filter from `Any` to `Process`.
1. Click **Start**.
1. Run `pwsh` to generate PowerShell information to log.

The process ID for a running instance of PowerShell is stored in the `$PID`
variable. Use the following steps to filter on a specific process instance of
PowerShell in the **Console** application.

1. Run an instance of `pwsh`.
1. Run `$PID` in the instance of PowerShell started in the previous step to
determine its process ID.
1. Enter the process ID for `pwsh` in the **Search** field and press
<kbd>return</kbd>.
1. Change the search filter from `Any` to `PID`.
1. Click **Start**.
1. Generate PowerShell information to log from the instance of PowerShell
started in the first step.
allows for the collection and storage of system and application logs in a
single centralized location.

For more information, see [view log messages in Console on Mac][08].
Apple's unified logging system stores log messages in binary format. You must
use the `log` tool to query the unified logging system for PowerShell log
events. The PowerShell log events don't appear in the **Console** application
on macOS. Console app is designed for the older _syslog-based_ logging that
predates the unified logging system.

### Viewing PowerShell log data from the command line on macOS

To view PowerShell log data from a command line on macOS, use the `log` command
in the **Terminal** or other shell host application. These commands can be run
from **PowerShell**, **Z shell** (**Zsh**), or **Bash**.
from **PowerShell**, **Z Shell**, or **Bash**.

In the following example, the `log` command is used to show the log data on your
system as it's occurring in realtime. The **process** parameter filters the log
Expand All @@ -333,9 +302,38 @@ running, the **process** parameter also accepts a process ID as its value. The
**level** parameter shows messages at the specified level and below.

```powershell
log stream --process pwsh --level info
log stream --predicate "subsystem == 'com.microsoft.powershell'" --level info
```

The `log show` command can be used to export log items. The `log show` command
provides options for exporting the last `N` items, items since a given time, or
items within a given time span.

For example, the following command exports items since
`9am on April 5, 2022`:

```powershell
log show --start "2022-04-05 09:00:00" --predicate "subsystem == 'com.microsoft.powershell'"
```

For more information, run `log show --help` to view the help for the `log show`
command.

You can also output the log data in JSON format, which allows you to convert
the event data to PowerShell objects. The following example outputs the events
in JSON format. The `ConvertFrom-Json` cmdlet is used to convert the JSON data
to PowerShell objects are get stored in the `$logRecord` variable.

```powershell
log show --predicate "subsystem == 'com.microsoft.powershell'" --style json |
ConvertFrom-Json | Set-Variable logRecord
```

You may also want to consider saving the logs to a more secure location such as
[Security Information and Event Management (SIEM)][08] aggregator. Using
Microsoft Defender for Cloud Apps, you can set up SIEM in Azure. For more
information, see [Generic SIEM integration][01].

### Modes and levels of PowerShell log data on macOS

By default, the PowerShell subsystem logs info level messages to memory (mode)
Expand All @@ -357,25 +355,6 @@ PowerShell subsystem:
sudo log config --subsystem com.microsoft.powershell --reset
```

The `log show` command can be used to export log items. The `log show` command
provides options for exporting the last `N` items, items since a given time, or
items within a given time span.

For example, the following command exports items since
`9am on April 5 of 2022`:

```powershell
log show --info --start "2022-04-05 09:00:00" --process pwsh
```

For more information, run `log show --help` to view the help for the `log show`
command.

You may also want to consider saving the logs to a more secure location such as
[Security Information and Event Management (SIEM)][09] aggregator. Using
Microsoft Defender for Cloud Apps, you can set up SIEM in Azure. For more
information, see [Generic SIEM integration][01].

## See also

- For Linux **syslog** and **rsyslog.conf** information, refer to the Linux
Expand All @@ -393,5 +372,4 @@ information, see [Generic SIEM integration][01].
[05]: about_PowerShell_Config.md#modulelogging
[06]: about_PowerShell_Config.md#protectedeventlogging
[07]: https://developer.apple.com/documentation/os/logging
[08]: https://support.apple.com/guide/console/log-messages-cnsl1012/mac
[09]: https://wikipedia.org/wiki/Security_information_and_event_management
[08]: https://wikipedia.org/wiki/Security_information_and_event_management
Loading

0 comments on commit 94edd0e

Please sign in to comment.