Create Custom CLS Logging Scenarios with Ease

[NextHop_Team]

First published on TECHNET on Jan 11, 2017

I am continually needing to create custom scenarios for logging components in CLS Logging (Centralized Logging Service).  Typically, this is because either the "Canned" Scenarios don't have the combination of components that I need, or they don't have the Flags or Levels that I need.   So, I put together a script so that I can create custom scenarios quickly and easily.  Since I like to share and I know others run into the same dilemma, I am writing this post for you.

If you need to find a list of scenarios and which components, levels and flags are in each, see my blog on Listing CLS Scenarios in HTML

Now, you might be familiar with the TechNet Cmdlet articles that show what you need or Richard Schwendiman's Article on the subject.  I am not trying to take away from any of these.  In fact, Richard's article is great and explains things in more detail than I will do here.  There isn't any reason to reinvent the wheel.

My main purpose for this article and script is to give you the ability to create a custom scenario quickly and get to logging your problem fast.

This script should help you create a custom scenario by putting some logic and validation into it.  It validates that the components that you chose are valid components and found in the default.xml used by the CLS Logging service and also verifies that you don't already have a scenario with this name.  Here are examples of this logic:

Invalid Component:

As you can see, these have some misspellings in the component names and that it gives you the option of listing the components so that you can easily correct this.

Scenario Already Exists:

Not only does it show you that this Scenario name already exists, it lists the components in the scenario just in case it has everything you need.  It also gives you the syntax to remove the scenario in the event you need to create it again with new parameters.

By Default, the script will create the scenario setting the Level to Verbose and the Flags to All.  This may create larger log output files, but are sometimes necessary to get the data you need.  It also, by default, creates the scenario in the Global scope.  I have a Scope parameter you can pass if you need to create a scenario that is Site specific.

Something else that will come in handy is the ability to run the script with the -ListComponents parameter switch that will list all of the available components for logging.  This way, you can go down the list (Like you used to do in the Lync Server Logging Tool) to find the names of the components you need for your scenario.

.\Create-CsClsCustomScenario.ps1 -ListComponents

So, lets jump into creating a custom scenario.  One scenario that isn't in the "Canned" scenarios is PersistentChat.  So, we will use that as an example.  There are 4 PChat Components: ChatCommon, ChatEndpoint, ChatServer, ChatWebService .  To create this scenario you would use the following syntax:

.\Create-CsClsCustomScenario.ps1 -Scenario Custom_Pchat -Components ChatCommon,ChatEndpoint,ChatServer,ChatWebService

One thing I want to point out is the scenario name.  You can call it whatever you want, but I like to start all of my custom scenarios with Custom_ .  I do this so that I can tell the difference between the "Canned" and the Custom scenarios.

The above syntax will create the following output:

You will notice the Yellow line.  I put this here to save on confusion.  It is said that you need to open a new PowerShell window to use the new scenario.  I have found this to be true unless I wait a period of time.  I believe this is due to replication and/or the CLS Agent awareness of the new scenario.  Regardless, if you want to use the scenario immediately, please open a new PowerShell session.

So that is the way to create a custom scenario with this script.

There are a couple other parameters that are optional in the event that you need to create the scenario in a scope other than global and/or if your default.xml file isn't in the typical locations. (C:\Program Files\Common Files\Skype for Business Server 2015\Tracing [it also checks the similar path for Microsoft Lync Server 2013]).  If you installed Lync or Skype server on a different drive or other location, you will have to use the -DefaultComponentFile parameter.  You would see something similar to this:

To Correct this, you would use the syntax similar to this:

.\Create-CsClsCustomScenario.ps1 -Scenario Custom_Pchat -Components ChatCommon,ChatEndpoint,ChatServer,ChatWebService -DefaultComponentFile "D:\Program Files\Common Files\Skype for Business Server 2015\Tracing\default.xml"

To use the -Scope parameter, you simply add the Topology Site name.  In my lab, it is MainSite .  I don't recommend using the scope parameter unless you need to.  Most scenarios run best under the Global scope.  Here is the syntax for Scope:

.\Create-CsClsCustomScenario.ps1 -Scenario Custom_Pchat -Components ChatCommon,ChatEndpoint,ChatServer,ChatWebService -Scope MainSite

Once you create a custom scenario, check out my blog on gathering logs easily

I really hope this script helps you.  Enjoy.

DOWNLOAD

To download this script, visit the TechNet Gallery

REQUIREMENTS

1. Windows PowerShell 3.0
2. Must be run from a Front End server
   1. This is needed because the CLS .Net assemblies have to be available and are only available on front end servers (From what I have found)
3. Lync/Skype on premesis administator with RTCUniversalServerAdmins, CsServerAdministrator, or CsAdministrator rights.
   1. This is required by the Lync/Skype Cmdlets to create CLS Scenarios without throwing access errors.
4. PowerShell opened in "Run as Administrator" mode
   1. This is required by the script Cmdlets to gather the correct information without throwing access errors.