Executive Summary:
| Windows PowerShell lets you easily access Windows event log information, integrate event-related commands into your PowerShell scripts, and write ad hoc event commands at the PowerShell command prompt. You can access event log information from local computers by using the get-eventlog cmdlet and from remote computers by creating a system.diagnostics.eventLog object that connects to a specific computer and event log. |
One of the many benefits of Windows PowerShell is that you can use it to easily access event log information and integrate that information into the PowerShell pipeline. You can incorporate event-related commands into your PowerShell scripts and write ad hoc event commands at the PowerShell command prompt.
With PowerShell, you can access event log information from both local and remote computers. However, the process is different for the two. To access local event information, you use the get-eventlog cmdlet. To access remote information, you create a system.diagnostics.eventLog object that connects to a specific computer and event log. Let's take a look at both, starting with local access.
Local Access
As with any cmdlet, the best place to start with the get-eventlog cmdlet is its Help file. You can retrieve the file by entering the following command at the PowerShell command prompt:
help get-eventlog
The command uses the help alias to refer to the get-help cmdlet, which retrieves Help information for the specified cmdlet. Figure 1 shows the results returned by this command.
One of the parameters you might have noticed when you retrieved the Help file is the -list parameter. When you specify -list, as shown in the following command,
get-eventlog -list
the cmdlet retrieves a list of event logs implemented on the local computer, as shown in Figure 2. Notice that one of the logs listed is Windows PowerShell. For the examples in this article, we'll use that log to demonstrate various commands. However, the examples can apply to any of the logs.
After you've identified a specific event log, you can retrieve information about that log as shown in the following command:
get-eventlog -list | where
\{$_.logDisplayName
-like "*powershell*"\}
(Column widths in the printed publication force us to wrap code. So, although this command appears on several lines here, you would enter it on one line in the PowerShell window. The same holds true for the other multiline cmdlets in this article.) This time, the list returned by the get-eventlog cmdlet is sent to the next command in the pipeline, as indicated by the vertical pipe (|). The next command in the pipeline is a where-object cmdlet. The cmdlet, which is referred to by the where alias, filters the list of event logs based on the logDisplayName property. The where-object expression, enclosed in curly brackets, uses a dollar sign and underscore ($_) to reference the current value in the pipeline. This is followed by a period and the property name, which is how you retrieve the logDisplayName value. This value is then compared to a string (-like “*powershell*”), which uses asterisk wildcards to look for all event log names that contain the word “powershell.” When you run this statement, you'll receive results similar to those in Figure 3.
Based on the results shown in Figure 2 and Figure 3, you would have expected the name of the logDisplayName property to be Name. However, the actual property name is logDisplayName. If you run the following command, you'll see that property name and other information:
get-eventlog -list | where
\{$_.logDisplayName
-like "*powershell*"\} | fl *
The statement is similar to the preceding example except that the results are piped from the where-object cmdlet to a format-list cmdlet, which is represented by the fl alias. The format-list cmdlet uses an asterisk to indicate that all the property values should be listed. Now your results will be similar to those shown in Figure 4. As you can see, the name of the property is logDisplayName.
When you use get-eventlog to retrieve event information, you're actually creating a system.diagnostics.eventLog object. You can use the methods and properties available to that object after you create the object. To view a list of the object's members (i.e., methods and properties), enter the following command:
get-eventlog -list | where
\{$_.logDisplayName
-like "*powershell*"\} | gm
In this statement, the results from the where-object cmdlet are piped to a get-member cmdlet (represented by the gm alias). The get-member cmdlet retrieves a list of an object's members, as shown in Figure 5.
If you run this statement, you'll see that one of the object's properties is maximumKilobytes, which indicates the maximum size of the event log. You can access this property when you create your object in order to return the property's value, as the following statement shows:
(get-eventlog -list | where
\{$_.logDisplayName -like
"*powershell*"\}).maximumKilobytes
To access a property of an object, you must first enclose the full get-eventlog statement in parentheses so that PowerShell treats the results as a single object. Then you simply add a period after the closing parenthesis, followed by the property name. (You can also assign the object to a variable and then call the property through that variable.) When you run this statement, you'll receive results similar to those shown in Figure 6. Notice that the results are simply the property's value—in this case, 15,360KB.
You can also retrieve the events themselves. For example, to retrieve the PowerShell events on the local computer, enter the following command:
get-eventlog "windows powershell"
The command returns a list of events, including the time, type, and message, as shown in Figure 7.
In many cases, you won't want to retrieve all the events from a particular log. An easy way to retrieve a specified number of the most recent events is to use the -newest parameter, as in the following command:
get-eventlog "windows powershell" -newest 20
When you run this command, the results will include only the most recent 20 events.
If you want to be even more specific when determining which events to return, you can add a where-object cmdlet to the pipeline in order to filter the events. For example, the following statement limits the events returned to those that have occurred within the last 24 hours.
get-eventlog "windows powershell" |
where \{$_.timeWritten -gt
(get-date).addDays(-1)\}
This statement pipes the events returned by the get-eventlog cmdlet to a where-object cmdlet that limits the results to those whose timeWritten date value is greater than (-gt) the value returned by the get-date cmdlet, minus one day. The get-date cmdlet returns the current date and time. The cmdlet uses the addDays method to calculate the date and time one day earlier than the current date and time. Note that you call a method the same way you access a property—by putting the object in parentheses, following it with a period, and then adding the method name.
You might find that, after you create your statement, you want to save the results to a file, rather than simply returning them to the screen. To save your results, you pipe the information to an out-file cmdlet, which exports the data to a file. For example, the following statement exports the event data to the PowerShellLog.txt file:
get-eventlog "windows powershell" |
where \{$_.timeWritten –gt
(get-date).addDays(-1)\} | out-file
c:\archivedfiles\PowerShellLog.txt
In this case, the out-file cmdlet takes only one argument, the full path and filename of the target file. When you run this statement, the event data will be inserted into this file rather than being returned to the PowerShell window.
As mentioned above, in addition to accessing an object's properties and retrieving its events, you can call its methods. One of the methods supported is the clear method, which you use to clear the log, as in the following example:
(get-eventlog -list | where
\{$_.logDisplayName
-like "*powershell*"\}).clear()
Accessing a Remote System
Now that you've seen how to access event information on a local system, let's take a look at how to access the information on a remote system. As mentioned earlier, you must create a system.diagnostics.eventLog object, as shown in the following command:
new-object
system.diagnostics.eventLog
("windows powershell", "server05")
To create the object, you use the new-object cmdlet, followed by the name of the object. You must also provide the name of the event log (windows powershell, for our purposes) and the name of the remote computer (server05, in this example). When you run this command against one of your own servers, you'll receive results similar to those shown in Figure 8.
As you saw earlier, when you use the get-eventlog cmdlet on the local system, you're automatically creating a system.diagnostics.eventLog object, which means that you can use the object's methods and properties. You can do the same thing when you create the object manually. To view a list of the object's members, you pipe the results to the get-member cmdlet:
new-object
system.diagnostics.eventLog
("windows powershell", "server05")
| gm
The command returns results similar to what you saw in Figure 5.
When you run the command, notice that one of the properties is Entries. This property contains the actual events. To view them, enclose the object in parentheses, add a period, and then call the property, as in the following example:
(new-object
system.diagnostics.eventLog
("windows powershell",
"server05")).entries
As with the get-eventlog cmdlet, you can limit the number of events that are returned. To do this, pipe the results to a select-object cmdlet and specify the -last parameter. For example, the following statement uses the select-object cmdlet to limit the results to the last 20 entries:
(new-object
system.diagnostics.eventLog
("windows powershell",
"server05")).entries |
select -last 20
You can also pipe the list of events to a where-object cmdlet:
(new-object
system.diagnostics.eventLog
("windows powershell",
"server05")).entries | where
\{$_.timeWritten -gt
(get-date).addDays(-5)\}
In this case, the where-object expression limits the results to the last five days.
And you can send the output to a file:
(new-object
system.diagnostics.eventLog
("windows powershell",
"server05")).entries | where
\{$_.timeWritten -gt
(get-date).addDays(-5)\} | out-file
c:\archivedfiles\PowerShellLog.txt
As these examples show, once you create the system.diagnostics.eventLog object and call the entries property, you can pipe the results to additional commands in order to refine those results or take any necessary actions. And you can call an object's methods. The two previous commands call the addDays method. The following statement calls the clear method:
(new-object
system.diagnostics.eventLog
("windows powershell",
"server05")).clear()
As a system administrator, you're no doubt well aware that the event log provides a powerful tool for monitoring your system's health, and PowerShell can make the process of accessing that information as simple as writing a couple commands. From the examples shown in this article, you should have the foundation you need to create the scripts and commands necessary to support a dynamic and effective strategy for monitoring all your events.
