﻿<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<helpItems schema="maml">
	<_locDefinition>
		<_locDefault _loc="locNone" />
		<_locTag _loc="locData">maml:para</_locTag>
		<_locTag _loc="locData">maml:title</_locTag>
	</_locDefinition>
	<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
		<command:details>
			<command:name>CollectReplicationMetrics.ps1</command:name>
			<maml:description>
				<maml:para _locID="CommandShortDescription">Collect database replication performance-counter statistics from mailbox servers. </maml:para>
			</maml:description>
			<maml:copyright>
				<maml:para _locID="Copyright">Copyright (c) Microsoft.  All rights reserved.</maml:para>
			</maml:copyright>
			<command:verb></command:verb>
			<command:noun></command:noun>
			<dev:version></dev:version>
		</command:details>
		<maml:description>
			<maml:para _locID="CommandLongDescription">CollectReplicationMetrics collects data from performance counters related to database replication.  The script gathers counter data from multiple mailbox servers, writes each server's data into a CSV file, and can then report various statistics across all of this data, such as the amount of time that each copy was failed or suspended, the average copy or replay queue length, or the amount of time that copies were outside of their failover criteria.</maml:para>
			<maml:para></maml:para>
			<maml:para>The servers can either be specified individually or entire database availability groups.  The script can either be run to first collect the data and then generate the report, or can be run to just gather the data or just report on data that has already been collected.  The frequency at which data should be sampled and the total duration to gather data can each be specified.</maml:para>
			<maml:para></maml:para>
			<maml:para>The data collected from each server is written to a file named "CounterData.&lt;server name&gt;.&lt;time stamp&gt;.csv".  The summary report will be written to a file named "HaReplPerfReport.&lt;database availability group name&gt;.&lt;time stamp&gt;.csv", or "HaReplPerfReport.&lt;time stamp&gt;.csv" if the script was not run with the -DagName parameter.</maml:para>
			<maml:para></maml:para>
			<maml:para>The script starts PowerShell jobs to collect the data from each server.  These jobs run for the full duration that data is getting collected, and when a large number of servers have been specified, this can use a considerable amount of memory.  The final stage, where the data is processed into a summary, can also be quite time consuming for large amounts of data.  It is possible to run the collection stage on one machine, then copy the data elsewhere for processing.</maml:para>
			<maml:para></maml:para>
			<maml:para></maml:para>
		</maml:description>
		<command:syntax>
			<command:syntaxItem>
				<command:name>CollectReplicationMetrics.ps1</command:name>
				<command:parameter required="True" position="named">
					<maml:name>DagName</maml:name>
					<command:parameterValue required="true">Object</command:parameterValue>
				</command:parameter>
				<command:parameter required="True" position="named">
					<maml:name>ReportPath</maml:name>
					<command:parameterValue required="true">String</command:parameterValue>
				</command:parameter>
				<command:parameter required="True" position="named">
					<maml:name>Duration</maml:name>
					<command:parameterValue required="true">TimeSpan</command:parameterValue>
				</command:parameter>
				<command:parameter required="True" position="named">
					<maml:name>Frequency</maml:name>
					<command:parameterValue required="true">TimeSpan</command:parameterValue>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>Mode</maml:name>
					<command:parameterValue required="true">String</command:parameterValue>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>MoveFilesToArchive</maml:name>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>LoadExchangeSnapin</maml:name>
				</command:parameter>
			</command:syntaxItem>  
			<command:syntaxItem>
				<command:name>CollectReplicationMetrics.ps1</command:name>
				<command:parameter required="True" position="named">
					<maml:name>Servers</maml:name>
					<command:parameterValue required="true">Object</command:parameterValue>
				</command:parameter>
				<command:parameter required="True" position="named">
					<maml:name>ReportPath</maml:name>
					<command:parameterValue required="true">String</command:parameterValue>
				</command:parameter>
				<command:parameter required="True" position="named">
					<maml:name>Duration</maml:name>
					<command:parameterValue required="true">TimeSpan</command:parameterValue>
				</command:parameter>
				<command:parameter required="True" position="named">
					<maml:name>Frequency</maml:name>
					<command:parameterValue required="true">TimeSpan</command:parameterValue>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>Mode</maml:name>
					<command:parameterValue required="true">String</command:parameterValue>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>MoveFilesToArchive</maml:name>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>LoadExchangeSnapin</maml:name>
				</command:parameter>
			</command:syntaxItem>  
			<command:syntaxItem>
				<command:name>CollectReplicationMetrics.ps1</command:name>
				<command:parameter required="True" position="named">
					<maml:name>SummariseFiles</maml:name>
					<command:parameterValue required="true">String[]</command:parameterValue>
				</command:parameter>
				<command:parameter required="True" position="named">
					<maml:name>ReportPath</maml:name>
					<command:parameterValue required="true">String</command:parameterValue>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>Mode</maml:name>
					<command:parameterValue required="true">String</command:parameterValue>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>MoveFilesToArchive</maml:name>
				</command:parameter>
				<command:parameter required="False" position="named">
					<maml:name>LoadExchangeSnapin</maml:name>
				</command:parameter>
			</command:syntaxItem>  
		</command:syntax>
		<command:parameters>
			<command:parameter required="True" position="named">
				<maml:name>DagName</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_DagName">Identity of the database availability group from which to collect statistics.  Every server in the group will be used.  Can be any value that would be accepted by Get-DatabaseAvailabilityGroup, including wildcards or GUIDs.</maml:para>
				</maml:description>
				<command:parameterValue required="true">Object</command:parameterValue>
				<dev:type>
					<maml:name>System.Object</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
			<command:parameter required="True" position="named">
				<maml:name>Servers</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_Servers">Identity of the servers from which to collect statistics.  Can be any value that would be accepted by Get-MailboxServer, including wildcards or GUIDs.</maml:para>
				</maml:description>
				<command:parameterValue required="true">Object</command:parameterValue>
				<dev:type>
					<maml:name>System.Object</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
			<command:parameter required="True" position="named">
				<maml:name>SummariseFiles</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_SummariseFiles">A list of CSV files to use to generate a summary report.  These files will typically be ones named "CounterData.&lt;CounterData&gt;*" generated by CollectReplicationMetrics.</maml:para>
				</maml:description>
				<command:parameterValue required="true">String[]</command:parameterValue>
				<dev:type>
					<maml:name>string[]</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
			<command:parameter required="True" position="named">
				<maml:name>ReportPath</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_ReportPath">Location to write the reports and sets of data.</maml:para>
				</maml:description>
				<command:parameterValue required="true">String</command:parameterValue>
				<dev:type>
					<maml:name>string</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
			<command:parameter required="True" position="named">
				<maml:name>Duration</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_Duration">The total time to spend collecting data.  Typical values would be one to three hours; longer durations should only be used with long intervals between each sample, or as a series of shorter jobs run by scheduled tasks</maml:para>
					</maml:description>
				<command:parameterValue required="true">TimeSpan</command:parameterValue>
				<dev:type>
					<maml:name>System.TimeSpan</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
			<command:parameter required="True" position="named">
				<maml:name>Frequency</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_Frequency">The frequency at which each sample is taken.  Typical values would be 30 seconds, one minute, or five minutes; under normal circumstances, intervals that are shorter than these will not show significant changes between each sample.</maml:para>
				</maml:description>
				<command:parameterValue required="true">TimeSpan</command:parameterValue>
				<dev:type>
					<maml:name>System.TimeSpan</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
			<command:parameter required="False" position="named">
				<maml:name>Mode</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_Mode">Specifies the processing stages that the script will execute.  Accepts any of "CollectAndReport", "CollectOnly", or "ProcessOnly", with the default being "CollectAndReport".</maml:para>
					<maml:para></maml:para>
					<maml:para>"CollectAndReport" means that the script should both collect the data from the servers and then process them to produce the summary report.</maml:para>
					<maml:para></maml:para>
					<maml:para>"CollectOnly" means that the script should just collect the data and not produce the report.</maml:para>
					<maml:para></maml:para>
					<maml:para>"ProcessOnly" means that the script should import data from some set of CSV files and process them to produce the summary report.  The -SummariseFiles option gives the script the list of files to process.</maml:para>
				</maml:description>
				<command:parameterValue required="true">String</command:parameterValue>
				<dev:type>
					<maml:name>string</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue>CollectAndReport</dev:defaultValue>
			</command:parameter>
			<command:parameter required="False" position="named">
				<maml:name>MoveFilesToArchive</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_MoveFilesToArchive">Specifies that the script should move the files to a compressed folder after processing.</maml:para>
				</maml:description>
				<command:parameterValue required="true">SwitchParameter</command:parameterValue>
				<dev:type>
					<maml:name>switch</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
			<command:parameter required="False" position="named">
				<maml:name>LoadExchangeSnapin</maml:name>
				<maml:description>
					<maml:para _locID="Param_Description_LoadExchangeSnapin">Has the script load the Exchange PowerShell commands; useful when the script needs to run from outside the Exchange Management Shell, such as in a scheduled task.</maml:para>
				</maml:description>
				<command:parameterValue required="true">SwitchParameter</command:parameterValue>
				<dev:type>
					<maml:name>switch</maml:name>
					<maml:uri />
				</dev:type>
				<dev:defaultValue />
			</command:parameter>
		</command:parameters>
		<command:examples>
			<command:example>
				<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
				<maml:introduction />
				<dev:code>C:\PS&gt; CollectReplicationMetrics.ps1 -DagName Group123 -Duration "01:00:00" -Frequency "00:01:00" -ReportPath .</dev:code>
				<dev:remarks>
					<maml:para>Gather one hour's worth of data from all the servers in the database availability group "Group123", sampled at one minute intervals, and then generate a summary report.  Place all the files in the current directory.</maml:para>
					<maml:para></maml:para>
				</dev:remarks>
				<command:commandLines>
					<command:commandLine>
						<command:commandText></command:commandText>
					</command:commandLine>
				</command:commandLines>
			</command:example>
			
			<command:example>
				<maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title>
				<maml:introduction />
				<dev:code>C:\PS&gt; CollectReplicationMetrics.ps1 -Servers ServerABC -Duration "00:15:00" -Frequency "00:00:15" -Mode CollectOnly -ReportPath .</dev:code>
				<dev:remarks>
					<maml:para>Gather 15 minutes worth of data from the server "ServerABC", sampled at 15 second intervals, but do not generate a summary report.</maml:para>
					<maml:para></maml:para>
				</dev:remarks>
				<command:commandLines>
					<command:commandLine>
						<command:commandText></command:commandText>
					</command:commandLine>
				</command:commandLines>
			</command:example>
			
			<command:example>
				<maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title>
				<maml:introduction />
				<dev:code>C:\PS&gt; CollectReplicationMetrics.ps1 -SummariseFiles (dir CounterData*) -Mode ProcessOnly -ReportPath .</dev:code>
				<dev:remarks>
					<maml:para>Read the data from all the files matching "CounterData*" and then generate a summary report.</maml:para>
					<maml:para></maml:para>
				</dev:remarks>
				<command:commandLines>
					<command:commandLine>
						<command:commandText></command:commandText>
					</command:commandLine>
				</command:commandLines>
			</command:example>
		</command:examples>
	</command:command>
</helpItems>
