Collect Logs in Microsoft Lync

When we first started the Lync Server PowerShell blog, our plan was for the blog to provide people with all the cool insider information that they couldn't get anywhere else. And that was a pretty good plan, except for one thing: we didn't actually have any cool insider information. And so we started writing Lync PowerShell haikus instead.

But that was then, and this is now. Now we actually do have some insider information that you can't get anywhere else: step-by-step instructions on how to add a Collect Logs button to Microsoft Lync 2010. Not only will we tell you how to do this, but we'll also tell you why you might want to do this. And we'll still do our daily haiku, just for good measure.

Note. You know, you're right: we do deserve a raise, don't we?

But first things first: let's talk about the Collect Logs button. By default, any time you start Microsoft Lync the application is going to look something like this:

What's wrong with that? Well, nothing, really; after all, that's how Microsoft Lync is supposed to look.

On the other hand, there is a cool (and, until now, completely undocumented) little feature that can be added to Microsoft Lync: the previously-mentioned Collect Logs button. Enable this feature, and from then on (well, unless you decide to disable the thing) Microsoft Lync will look like this

See the little Collect Logs button in the lower right-hand corner of the Lync window? Pretty cool, huh? It's like adding racing stripes and a spoiler to your copy of Lync!

Wait, check that: it's even better than adding racing stripes and a spoiler to your copy of Lync. We haven't actually tried that ourselves, but our guess is that, while adding racing stripes and a spoiler might make Lync look a little spiffier and a lot sportier, it probably won't actually change the way Lync works. That isn't true of the Collect Logs button, however. This button isn't being added just for its aesthetic value; instead, the button is being added because it adds some very cool and very useful diagnostic features to Lync. Imagine you're using Lync to make a call, and something goes wrong. (Yes, we know: it is hard to imagine anything going wrong with a piece of software. But do the best you can.) As an end user that's very frustrating but, that's also life right? After all, there's not much you can do about it.

Wait, check that: there's not much you can do about it unless you've enabled the Collect Logs button. If you 've enabled this button (or, more correctly, if an administrator has enabled this button for you), clicking the button will then bring up the following dialog box:

"Big deal," you say? Well, give us a chance to explain, and you'll see that this is a big deal. Inside the Collect Logs dialog box you can quickly and easily report the problem that you just encountered. For example, from the Select issue type dropdown you can choose any of the following common problems:

· The call did not connect

· The call ended unexpectedly (dropped)

· I observed audio or video quality issues during the call

· Others observed issues in my audio or video quality during the call

· I see an audio quality issue notification but didn't experience any issues

· Other – please explain

Depending on which issue you selected, you can then add more specific information by choosing an item from the Select issue details dropdown. For example, if you selected Others observed issues in my audio or video quality during the call, you can then choose a detailed item from the following list:

· Others heard my speech cut off or fade out

· Others heard echoing caused by my side

· Others heard noise from me

· Others said my speech volume was low

· Others heard distorted or unnatural speech from me

· Others could not hear me

· Others said my video was frozen or jerky

· Others said my video was defective or low quality

And regardless of the issue you selected, you'll always be able to provide additional details in the Describe the issue box.

But wait: there's more! Depending on the issue, and depending on how your client policy has been configured (in particular, the values of the properties DisablePoorDeviceWarrnings and DisablePoorNetworkWarnings), it's possible that you should have seen a warning message related to the problems you were having. The Did you see a notification message about poor quality? dropdown lets you indicate whether or not you saw such a message.

The last two options available to you are really cool. Include a sample voice recording of your latest call will automatically archive the final 30 seconds of audio from your last call. We didn't know this until we started working on this article, but it turns out the last 30 seconds of audio from any Lync Server call is stored in a buffer. (We should note that this is the last 30 seconds of your audio; this buffer does not include anyone else's audio. You'll only have a 30-second record of what you said during the call, not what anyone else said during the call.) The point is, if other people were complaining that your speech was low or distorted or whatever, you'll have a sample of that speech.

Finally, there's this option: Include a screenshot of your desktop (highly recommended) . If you select this, Lync will take a quick screenshot of your desktop. And that's not just so you'll have something to paste into your scrapbook and remember your Lync experience by. Instead, that screenshot can provide some useful troubleshooting clues, particularly if there happen to be some warnings or error messages currently onscreen.

And then you click OK, and your log files will be gathered up and stored in the %userprofile% \Tracing folder. For example:

See the highlighted file, the one (in this example) named MediaLog_2258E90C-3979-4915-AA3E-9D996A6C81E0-2010-12-10_099-09-58_4.0.7536.0000.cab? (That's very kind of you, but we can't take credit for the catchy file name; that gets generated automatically.) Inside that .CAB file are a whole bunch of diagnostics files that, in the case of ongoing issues, can be incredibly useful to Microsoft support personnel:

The idea here is that, if you are having repeated problems with audio/video calls, you can enable the Collect Logs button and ask your users to create a new .CAB file any time they encounter a problem. Those log files can then be gathered up and sent to someone at Microsoft who can analyze the files and, with any luck, help you solve your problem.

Note. Uh, no, don't just send them to anyone at Microsoft and, whatever you do, don't send them to those of us here at the Lync Server PowerShell blog; we wouldn't know what to do with them. Instead, wait for someone (meaning someone who knows what they're doing) to ask you to collect the logs. Most likely that same someone will then provide instructions for uploading those files somewhere.

And yes, you could just collect these files for your own use, although, at least at the moment, you won't be able to do much with some of those files. However, the information supplied by the user in the Collect Logs dialog box (e.g., the issue they were having, the user's description of the problem, etc.) can be read from the file ITS.XML. That information might be useful to you; if nothing else, it would enable you to gather statistics on who's having problems and what kind of problems they're having.

But that's up to you.

That just leaves us with one problem: how exactly do we get the Collect Logs button to appear on Lync in the first place? As it turns out, we do this by adding a new option to the appropriate client policies. At one time, there were plans to include an EnableDiagnosticsLogsCollection parameter as part of the New-CsClientPolicy and Set-CsClientPolicy cmdlets. For whatever reason that parameter didn't make it into the released product. But that's OK; you can add this option, and enable log collection, by running a set of Lync Server PowerShell commands similar to these:

$policy = Get-CsClientPolicy –Identity global

$logButton = New-CsClientPolicyEntry -Name EnableDiagnosticsLogsCollection -Value 1

$policy.PolicyEntry.Add($logButton)

Set-CsClientPolicy -Instance $policy

In the first command, we're simply retrieving an instance of the global client policy. In command 2, we then use the New-CsClientPolicyEntry cmdlet to create a new option for this policy, and to assign a value to that option. Our new option is named EnableDiagnosticsLogsCollection and is given the value 1. Can you name this option anything you want? You bet – as long as you don't care whether it actually works or not. But if you want the Collect Logs button to appear then you absolutely must give the option the name EnableDiagnosticsLogsCollection – period. The Value 1 causes the Collect Logs button to appear in the Lync window; a Value of 0 will make the button disappear from the Lync window.

Note. Another way to make the button disappear is to remove EnableDiagnosticsLogsCollection from the client policy. For example, this command removes all the custom policy entries that have been added to the global client policy:

Set-CsClientPolicy –Identity global –PolicyEntry $Null

For more information (and for an example of how to remove a single policy entry from a client policy), see the help topic for New-CsClientPolicyEntry

After we've created the new policy entry option in memory, we next use this line of code to add the entry to our retrieved instance of the global client policy:

$policy.PolicyEntry.Add($logButton)

And once we've done that, we can then call Set-CsClientPolicy to add the new entry to the global client policy. At that point, anyone managed by the global client policy will see the Collect Logs button in their Lync window.

Note. Well, after they've logged off of Lync and then logged back on. Policy changes like this won't suddenly make the Collect Logs button appear in a copy of Lync that's already up and running.

And there you have it: cool insider information you'll only find in the Lync Server PowerShell blog. No wonder we're considered the place to turn to when you want to know how to add a Collect Logs button to Microsoft Lync!