Modifies an existing diagnostic filter configuration settings collection. Diagnostic filter configuration settings are used to determine whether traffic to or from a given domain or Uniform Resource Identifier (URI) is recorded in your Microsoft Communications Server 2010 log files.
Syntax
Set-CsDiagnosticFilterConfiguration [-Identity <XdsIdentity>] [-Confirm [<SwitchParameter>]] [-Enabled <$true | $false>] [-Filter <Filter>] [-Force <SwitchParameter>] [-WhatIf [<SwitchParameter>]] |
Set-CsDiagnosticFilterConfiguration [-Confirm [<SwitchParameter>]] [-Enabled <$true | $false>] [-Filter <Filter>] [-Force <SwitchParameter>] [-Instance <PSObject>] [-WhatIf [<SwitchParameter>]] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Optional |
Xds Identity |
Unique identifier for the diagnostics filter configuration settings to be modified. To modify settings configured at the site scope, use syntax similar to this: -Identity "site:Redmond". To modify settings configured at the service scope, use syntax similar to this: -Identity "service:Redmond-EdgeServer-1". To modify the global settings, use this syntax: -Identity global. If this parameter is not specified, then Set-CsDiagnosticFilterConfiguration will automatically modify the global settings. |
|
Instance |
Optional |
DiagnosticFilterSettings object |
Allows you to pass a reference to an object to the cmdlet rather than set individual parameter values. |
|
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. (Technically, the host portion of a SIP address.) For example an FQDN (fully qualified domain name) 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. (Technically, 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 employed. If diagnostic filtering is enabled, this property will be ignored and traffic from all domains and URIs will be logged. |
|
Enabled |
Optional |
Boolean |
When set to True ($True), diagnostic filtering is enabled and only traffic from the domains or URIs listed in the Filter property is logged. When set to False (the default value), traffic from all domains and URIs is logged. |
|
Force |
Optional |
Switch Parameter |
Suppresses the display of any non-fatal error message that might arise when running the command. |
|
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. |
Detailed Description
If you enable logging for Communications 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 specific 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 filter configuration settings make it possible for you to specify the domains or URIs that will be recorded in the log files; if diagnostic filtering is enabled, then the only traffic to or from the specified domains will be logged. Communications Server enables you to create diagnostic filter settings at the site scope or the service scope (for either the Edge Server or the Registrar service). In turn, this enables you to apply filtering to, say, the Redmond site while leaving filtering disabled on your other sites.
After diagnostic filtering has been applied to a site or service, you can use the Set-CsDiagnosticFilterConfiguration cmdlet to enable or disable filtering. You can also use this cmdlet to add or remove filters from a given collection.
Return Types
Set-CsDiagnosticFilterConfiguration does not return a value or object. Instead, the cmdlet configures instances of the Microsoft.Rtc.Management.WriteableConfig.Settings.Diagnostics.DiagnosticFilterSettings object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
Set-CsDiagnosticFilterConfiguration -Identity site:Redmond -Enabled $False |
|
The command shown in Example 1 disables the diagnostics filter configuration collection for the Redmond site (-Identity site:Redmond). This task is carried out by setting the Enabled property to False ($False).
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
Get-CsDiagnosticFilterConfiguration -Filter "service:*" | Set-CsDiagnosticFilterConfiguration -Enabled $False |
|
The preceding command disables all the diagnostic filter configuration collections that have been assigned to the service scope. To do this, Get-CsDiagnosticFilterConfiguration and the Filter parameter are used to return all the collections assigned at the service scope. The filter value "service:*" ensures that only collections that have an Identity that begins with the characters "service:" will be returned. The filtered collection is then piped to Set-CsDiagnosticFilterConfiguration, which takes each item in the collection and sets the Enabled property to False ($False).
-------------------------- Example 3 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsDiagnosticsFilter -Fqdn fabrikam.com -Uri user@fabrikam.com -Enabled $True Set-CsDiagnosticFilterConfiguration -Identity global -Filter $x |
|
The commands shown in Example 3 use New-CsDiagnosticsFilter to create a new diagnostics filter, and then assign that filter to the global collection of diagnostics filter settings. To carry out this task, the first command calls New-CsDiagnosticsFilter to create an in-memory-only diagnostics filter; this filter adds the FQDN fabrikam.com and the URI 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, Set-DiagnosticFilterConfiguration is used to assign the new filter to the global collection of diagnostic filter settings. In this case, any existing values in the Filter property will be replaced by the newly-created filter stored in $x.
-------------------------- Example 4 ------------------------
| Copy Code |
|
|---|---|
$x = (Get-CsDiagnosticFilterConfiguration -Identity global).Filter
$x.Fqdn.Add("fabrikam.com")
Set-CsDiagnosticFilterConfiguration -Identity global -Filter $x
|
|
Example 4 shows how you can add a new FQDN filter to the global diagnostic filter configuration settings. To do this, the first command in the example uses Get-CsDiagnosticFilterConfiguration to retrieve the value of the Filter property for the global collection. This is done by enclosing the command Get-CsDiagnosticFilterConfiguration –Identity global in parentheses, which causes Windows PowerShell to run that command before it does anything else. After the global collection is returned, the value of the Filter property is extracted and stored in a variable named $x.
In the second command, the Add method is used to add a new FQDN (fabrikam.com) to the filter. When that’s done, the final command in the example uses Set-CsDiagnosticFilterConfiguration to write the modified Filter (the one that now includes the FQDN fabrikam.com) to the global collection. The net result is that fabrikam.com will be added to any FQDNs already included in the Filter property.
-------------------------- Example 5 ------------------------
| Copy Code |
|
|---|---|
$x = (Get-CsDiagnosticFilterConfiguration -Identity global).Filter
$x.Fqdn.Remove("fabrikam.com")
Set-CsDiagnosticFilterConfiguration -Identity global -Filter $x
|
|
The commands shown in Example 5 remove an FQDN (fabrikam.com) from the global diagnostic filter configuration settings. The first command in the example uses Get-CsDiagnosticFilterConfiguration to retrieve the current value of the Filter property for the global collection; this value is stored in a variable named $x. After the current Filter value has been retrieved, the Remove method is used to remove the FQDN fabrikam.com. After the FQDN has been removed, Set-CsDiagnosticFilterConfiguration is used in order to write the modified filter (stored in the variable $x) to the global collection.
-------------------------- Example 6 ------------------------
| Copy Code |
|
|---|---|
Set-CsDiagnosticFilterConfiguration -Identity global -Filter $Null |
|
In Example 6, all the items found in the global collection’s Filter property are removed. This is done by setting the Filter property to a null value ($Null).