Skip to content

Commit

Permalink
Update logging information for macOS
Browse files Browse the repository at this point in the history
  • Loading branch information
@sdwheeler
sdwheeler committed Aug 29, 2024
1 parent 64ce74c commit 92864d4
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**, **ZShell**, 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**, **ZShell**, 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 92864d4

Please sign in to comment.