What is Start-Transcript?

As per MSDN, The Start-Transcript cmdlet creates a record of all or part of a PowerShell session to a text file. The transcript includes all commands that the user types and all output that appears on the console. Starting in Windows PowerShell 5.0, Start-Transcript includes the hostname in the generated filename of all transcripts.

When & Where to use?

As system admin/DevOps, we are doing much automation inside the servers and it’s mandatory to capture all the details (maybe error or success ran) in the log to make an analysis if required. In simple, if you running PowerShell scripts automatically you need a way to log any errors or warnings that occur. Usually, we will create your own log function (the same I did for my previous automation, please refer to my implemented method), but there is an easier way which I found during my team discussion and thought to share with all of you. This is especially useful when your enterprise’s logging is centralized.

The Start-Transcript cmdlet writes everything that happens during a session to a log file. These are the commands that you enter in a PowerShell session and all output that normally appears in the console.

Example 1: Without any parameters (inside our script)

To start the transcript you can simply use the cmdlet Start-Transcript and Stop-Transcript to stoping it. You can place whatever script needs to be executed in between the Start and Stop Transcript.

Without any parameters, the transcript will be saved in the user’s documents folder. The filename will automatically be generated and consists of the device name, random characters followed by a timestamp. The default path is great when you are only using PowerShell on your own machine.

Output: 

The Transcript log will contain all the information that you see in the console as well, including a very detailed header with information of the host that you have used:

Example 2: With Parameters (-path & -Append)

The default path is great when you are only using PowerShell on your own machine. But most of the time you want to centralize the log files. There are two options for this, we can use the -Path parameter or the -OutputDirectory parameter for this.

# Append the transcript to an Error.log file.
Start-Transcript -Path c:\automationLog\Error.log -Append

For -Path parameter, we will need to specify the full path, including the file name. This is helpful when you want to have a single log file for a script and append all the transcripts into a single file. In the above example, we used the -Append parameter, by default it will overwrite any existing content in the file. To overcome this we need to use -Append or -NoClobber parameters to append in the same file.

# Use -NoClobber or -Append to prevent overwriting of existing files
Start-Transcript -Path c:\automationLog\Error.log -NoClobber

Example 3: With -OutputDirectory Parameters

You can also use the -OutputDirectory parameter to store the log file in a custom location, and this cmdlet allows to create of a unique filename.

Output: 

For this example, I had executed the script repeatedly and for each execution, the log file is created uniquely with appending of some random AlphaNumeric values as shown in the below snapshot (3of74bj, 5yrpf4R,..)

Points to remember:

Files that are created by the Start-Transcript cmdlet include random characters in names to prevent potential overwrites or duplication when two or more transcripts are started simultaneously.

The Start-Transcript cmdlet creates a record of all or part of a Windows PowerShell session in a text file. The transcript includes all commands that the user types and all output that appears on the console.

Each transcript starts with a fully detailed header with a lot of information. When using this for logging of automated scripts that run automatically this information is large and not much use. So from PowerShell 6 and higher, we have many parameters to make cut off this (like -UseMinimalHeader).