New-CsDiagnosticConfiguration

 

Topic Last Modified: 2012-03-23

Creates new diagnostic configuration settings. Diagnostic configuration settings are used to determine whether traffic to or from a given domain or Uniform Resource Identifier (URI) is recorded in your Microsoft Lync Server 2010 log files.

Syntax

New-CsDiagnosticConfiguration -Identity <XdsIdentity> [-Confirm [<SwitchParameter>]] [-Enabled <$true | $false>] [-Filter <Filter>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-WhatIf [<SwitchParameter>]]

Detailed Description

If you enable logging for Lync Server 2010 then, by default, traffic traveling to or from any domain or URI is included in those log files. This ensures that as much information as possible is recorded in the log files.

However, this can occasionally result in too much information. For example, if you are experiencing connectivity problems with a particular domain, you might want to limit logging to traffic between your network and that domain; that makes it easier for you to identify the relevant records and, in turn, might make it easier for you to diagnose and correct the problem.

Diagnostic configuration settings make it possible for you to specify the domains or URIs that will be recorded in the log files; for example, you can log only the traffic to or from specified domains. Lync Server enables you to create diagnostic configuration settings at the site scope. In turn, this enables you to apply different settings to, say, the Redmond site than you do on your other sites.

Note that you cannot create diagnostic configuration settings at the global scope; that’s because the global scope already hosts these settings. Likewise, you cannot create a new settings collection at the site scope if the specified site already contains diagnostic configuration settings. For example, your command will fail if you try to create a new collection for the Redmond site and that site already hosts diagnostic configuration settings.

Who can run this cmdlet: By default, members of the following groups are authorized to run the New-CsDiagnosticConfiguration cmdlet locally: RTCUniversalServerAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:

Get-CsAdminRole | Where-Object {$_.Cmdlets –match "New-CsDiagnosticConfiguration"}

Parameters

Parameter Required Type Description

Identity

Required

Xds Identity

Unique identifier for the diagnostics configuration settings to be created. Because new settings can only be created at the site scope you must use syntax similar to this: -Identity "site:Redmond".

Filter

Optional

PS List Modifier

Collection of domains and URIs whose traffic will be logged if diagnostic filtering is enabled. The Filter property consists of three separate items:

Fqdn – Collection of domains to be included in the filter. (More technically, this is the host portion of a SIP address.) For example a fully qualified domain name (FQDN) might look like this: fabrikam.com. Alternatively, you can use wildcards to represent multiple domains: *.fabrikam.com. You can include more than one domain in a single filter.

Uri – Collection of URIs to be included in the filter. (The Uri is the user@host portion of a SIP address.) A Uri can consist of any of the following patterns: user@fabrikam.com; user@*; *@fabrikam.com. You can include multiple URIs in a single filter.

Enabled – Indicates whether or not the filter should be activated.

LoggingShare

Optional

String

Shared folder where the diagnostic logs can be uploaded.

Force

Optional

Switch Parameter

Suppresses the display of any non-fatal error message that might arise when running the command.

InMemory

Optional

Switch Parameter

Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet’s matching Set- cmdlet.

WhatIf

Optional

Switch Parameter

Describes what would happen if you executed the command without actually executing the command.

Confirm

Optional

Switch Parameter

Prompts you for confirmation before executing the command.

Input Types

None. New-CsDiagnosticConfiguration does not accept pipelined input.

Return Types

New-CsDiagnosticConfiguration creates new instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Diagnostics.DiagnosticFilterSettings.

Example

-------------------------- Example 1 ------------------------

New-CsDiagnosticConfiguration -Identity site:Redmond

The preceding command creates a new collection of diagnostic configuration settings for the Redmond site.

-------------------------- Example 2 ------------------------

$x = New-CsDiagnosticsFilter -Fqdn fabrikam.com -Uri "sip:user@fabrikam.com" -Enabled $False 

New-CsDiagnosticConfiguration -Identity site:Redmond -Filter $x

The commands shown in Example 2 create a new diagnostics filter and then assign that filter to a new collection of diagnostic settings. To carry out this task, the first command calls New-CsDiagnosticsFilter to create an in-memory-only diagnostics filter; this command adds the FQDN fabrikam.com and the URI sip:user@fabrikam.com to the filter. The command also sets the Enabled property to True ($True) in order to activate the filter. The resulting virtual filter is then stored in the variable $x.

In command 2, New-CsDiagnosticConfiguration is used to create a new diagnostic configuration settings collection for the Redmond site. These new settings will use the diagnostic filter stored in the variable $x.

-------------------------- Example 3 ------------------------

$x = New-CsDiagnosticConfiguration -Identity site:Redmond -InMemory
$x.LoggingShare = "\\atl-fs-001\logs"
Set-CsDiagnosticConfiguration -Instance $x

The commands shown in Example 3 demonstrate how you can create diagnostic configuration settings that initially exist only in memory. To do this, the first command calls New-CsDiagnosticConfiguration along with two parameters: Identity (which specifies the Identity for the settings) and InMemory, which indicates that the new settings should be created in memory only. The resulting object is stored in the variable $x.

After the virtual settings have been created, the second command is used to configure the LoggingShare property to the UNC path \\atl-fs-001\logs. The final command is then used to transform the virtual diagnostic configuration settings into an actual collection of settings applied to the Redmond site. Note that this final command is mandatory. If you do not call Set-CsDiagnosticConfiguration, no settings will be applied to the Redmond site, and the virtual settings will disappear as soon as you end your Windows PowerShell session or delete the variable $x.