﻿<?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>CollectOverMetrics.ps1</command:name>
      <maml:description>
        <maml:para _locID="CommandShortDescription">Gather statistics on database moves and mounts.  Generates CSV files of the raw data for each database operation.  Optionally generates a summary report in HTML.</maml:para>
      </maml:description>
      <maml:copyright>
        <maml:para _locID="Copyright">Copyright (c) 2012 Microsoft Corporation. All rights reserved.</maml:para>
      </maml:copyright>
      <command:verb>CollectOverMetrics.ps1</command:verb>
      <command:noun></command:noun>
      <dev:version />
    </command:details>
    <maml:description>
      <maml:para _locID="CommandLongDescription">CollectOverMetrics reads from the event logs of servers in a DatabaseAvailabilityGroup to gather information on database mounts, moves, and failovers (collectively known as "operations") over some time period.  For each operation, it will record the identity of the database, the time that the operation began and ended, the servers that the database was mounted on at the start and finish, the reason for the operation, whether the operation was succesful, and details of the error if it failed.  It writes all of these details to CSV files, which can be opened by Excel, with one operation per row.  It writes a separate CSV file for each DatabaseAvailabilityGroup that it is reporting on.</maml:para>
      <maml:para></maml:para>
      <maml:para>When the "-GenerateHtmlReport" flag is used, the script takes all the information that it has recorded, collects them into groups by the operation type, and formats an HTML file that reports on some statistics for each of these groups.  It will report the total number of operations in each group, the number of operations that failed, and statistics on the time taken within each group.  The report also has a breakdown of the kinds of errors that caused operations to fail.</maml:para>
      <maml:para></maml:para>
      <maml:para>The results reported by the script can be restricted to some subset by using the "-Database" or "-ReportFilter" options.  Only the operations that match these filters will be included in the summary HTML report.</maml:para>
      <maml:para></maml:para>
      <maml:para>When "-SummariseCsvFiles" is used, the script reads the data from CSV files already generated by the script.  It uses this data to generate a summary report like the one that it generates for the "-GenerateHtmlReport" option.</maml:para>
      <maml:para></maml:para>
      <maml:para>The HTML report is written as a set of tables.  The first summarises all of the moves, mounts, and failovers by grouping them into categories:</maml:para>
      <maml:para></maml:para>
      <maml:para>-- "Action Type" can be Move, Mount, Dismount, or Remount.  Moves are any time that the database changes its active server, whether by controlled moves or by failovers.  Mount, Dismount, and Remount are times that the database changes its mounted status, but does not move to another machine.</maml:para>
      <maml:para>-- "Action Trigger" can be Admin or Automatic.  Automatic actions are ones that are made by the service; for example, a failover when a server goes offline.  Admin actions are any actions that were started by using Exchange cmdlets or the Exchange Management Console.</maml:para>
      <maml:para>-- "Action Reason" gives some sub-categories of the "Action Trigger"</maml:para>
      <maml:para></maml:para>
      <maml:para>It then gives: the total number of operations in that category; the number of operations that failed (a failover when there was no healthy copy, for example); the number of operations that took more or less than 30 seconds; and the number of operations that ended with a lossy mount.  The columns after that give details on how long various stages of the operations took:</maml:para>
      <maml:para></maml:para>
      <maml:para>-- DurationOutage is the total amount of time that the operation took.</maml:para>
      <maml:para>-- DurationMount and DurationDismount is the amount of time that each of these specific stages of the operation took.  Long times here could indicate excess load on the databases or disk performance problems (see also the ReplayedLogs field).</maml:para>
      <maml:para>-- DurationBcs is the time taken to choose which copy to activate</maml:para>
      <maml:para>-- DurationAcll is the time taken to attempt to copy any last data from the original source.  Long times here could indicate networking performance problems (see also the AcllCopiedLogs field).</maml:para>
      <maml:para>-- DurationOther collects all the remaining time spent in the operation that wasn't part of one of the other categories.</maml:para>
      <maml:para>-- AcllCopiedLogs is the number of log-files copied while attempting to activate a copy.  Large values here would explain large DurationAcll times.</maml:para>
      <maml:para>-- ReplayedLogs and AcllFinalReplayQueue is the number of log-files replayed by the copy as it mounted.  Large values here would explain long mount times. </maml:para>
      <maml:para>-- LostLogs, LostBytes is the amount of data lost by operations that ended with a lossy mount.  This data may be recovered by the Transport Dumpster, these figures only consider the data that was not available at the point the copy mounted.</maml:para>
      <maml:para></maml:para>
      <maml:para>For each of these fields, the script will determine the average, maximum, and minimum values in the data.  It will also calculate the quartile points and the 90th percentile.</maml:para>
      <maml:para></maml:para>
      <maml:para>Following this are two tables about the errors that the operations failed with.  The script attempts to remove specific names or times from the error messages so it can group them into error categories.  The first table does this for all failed operations; the second table is specific to database failovers where there was no healthy copies to activate.  That table takes the error message reported for each copy and does the same analysis.  This table has the most common reasons that individual copies were rejected as failover candidates.</maml:para>
      <maml:para></maml:para>
      <maml:para>The final table has the individual details on each of the operations that took more than 30 seconds to complete.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <command:name>CollectOverMetrics.ps1</command:name>
        <command:parameter required="true" position="named">
          <maml:name>DatabaseAvailabilityGroup</maml:name>
          <command:parameterValue>Object</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>EndTime</maml:name>
          <command:parameterValue>DateTime</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>StartTime</maml:name>
          <command:parameterValue>DateTime</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>GenerateHtmlReport</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>RawOutput</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>IncludeExtendedEvents</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>ReportPath</maml:name>
          <command:parameterValue>String</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>MergeCsvFiles</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>Database</maml:name>
          <command:parameterValue>Object</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>ReportFilter</maml:name>
          <command:parameterValue>ScriptBlock</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>ShowHtmlReport</maml:name>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <command:name>CollectOverMetrics.ps1</command:name>
        <command:parameter required="true" position="named">
          <maml:name>SummariseCsvFiles</maml:name>
          <command:parameterValue>String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>ReportPath</maml:name>
          <command:parameterValue>String</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>MergeCsvFiles</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>Database</maml:name>
          <command:parameterValue>Object</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>ReportFilter</maml:name>
          <command:parameterValue>ScriptBlock</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named">
          <maml:name>ShowHtmlReport</maml:name>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
  <command:parameters>
      <command:parameter required="true" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>DatabaseAvailabilityGroup</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_Dag">The identity of the Database Availability Group (aka DAG) for which to generate the report.  The value can be any object that can be passed to Get-DatabaseAvailabilityGroup; for example the name of the DAG, a DAG object, the DAG's Guid.  Wildcard strings are acceptable, the script will report on each matching DAG.</maml:para>
        </maml:description>
        <command:parameterValue>Object</command:parameterValue>
        <dev:type>
          <maml:name>Object</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>EndTime</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_EndTime">Time period to report on.  The script will only gather the events in this period, which means that it may capture partial operation records (just the end of an operation at the start of the period, vice-versa at the end). If neither value is specified, the script defaults to the past 24 hours. If only one value is specified (either StartTime or EndTime), the period will be 24 hours either beginning or ending at the specified time.</maml:para>
        </maml:description>
        <command:parameterValue>DateTime</command:parameterValue>
        <dev:type>
          <maml:name>DateTime</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>StartTime</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_StartTime">See the description of the -EndTime parameter</maml:para>
        </maml:description>
        <command:parameterValue>DateTime</command:parameterValue>
        <dev:type>
          <maml:name>DateTime</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>GenerateHtmlReport</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_GenerateHtmlReport">If set, the script will generate an HTML file that summarises all the data that it has collected.</maml:para>
        </maml:description>
        <command:parameterValue>SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>RawOutput</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_RawOutput">If set, the script will write the resuts that would have gone to CSV files directly to the output stream, as would happen with Write-Output.  This can then be piped on to other commands.</maml:para>
        </maml:description>
        <command:parameterValue>SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>IncludeExtendedEvents</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_IncludeExtendedEvents">If set, the script will collect the events giving diagnostic details of times spent mounting databases.  This can be a very time-consuming stage if the Application event log on the servers is very large.</maml:para>
        </maml:description>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="true" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>SummariseCsvFiles</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_SummariseCsvFiles">Takes a list of CSV files generated by the script and uses them as the source data to generate a summary HTML report.  The report is the same one that is generated with the -GenerateHtmlReport option.  The files can be generated across multiple database availability groups at many different times, or even with overlapping times, and the script will merge all of their data together.</maml:para>
        </maml:description>
        <command:parameterValue>String[]</command:parameterValue>
        <dev:type>
          <maml:name>String[]</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>ReportPath</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_ReportPath">Path for the location to generate the report files.</maml:para>
        </maml:description>
        <command:parameterValue>String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>MergeCsvFiles</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_MergeCsvFiles">If set, the script will take all of the CSV files containing data on each operation and merge them into a single CSV file.</maml:para>
        </maml:description>
        <command:parameterValue>SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue />
      </command:parameter>
      <command:parameter required="false" variableLength="" globbing="" pipelineInput="false" position="named">
        <maml:name>ReportFilter</maml:name>
        <maml:description>
          <maml:para _locID="Param_Description_ReportFilter">Define a filter that is applied to the operations, which have the fields as they appear in the CSV files.  The script block should be of the same format that is used by a 'where' operation, with each element set to '$_' and returning a boolean.  For example:</maml:para>
<maml:para></maml:para>
<maml:para>{ $_.DatabaseName -notlike "Mailbox Database*" }</maml:para>
<maml:para></maml:para>
<maml:para>will filter out all the operations against default databases, and:</maml:para>
<maml:para></maml:para>
<maml:para>{ $_.Result -eq "Success" }</maml:para>
<maml:para></maml:para>
<maml:para>will filter out all the failed operations.</maml:para>
        </maml:description>
        <command:parameterValue>ScriptBlock</command:parameterValue>
        <dev:type>
          <maml:name>ScriptBlock</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; CollectOverMetrics -DatabaseAvailabilityGroup ProdDag123</dev:code>
        <dev:remarks>
            <maml:para>Generate a report of all the operations on the database availability group "ProdDag123" for the last 24 hours.  If the command was run at 1PM on May 1, 2010, the report's name would be FailoverReport.ProdDag123.2010_05_01_13_00_00.csv.</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; CollectOverMetrics -DatabaseAvailabilityGroup ProdDag*</dev:code>
        <dev:remarks>
            <maml:para>For each of the database availability groups matching the wildcard "ProdDag*", generate a report for the last 24 hours.  Each matching database availability group is reported in a separate CSV file.</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; CollectOverMetrics -DatabaseAvailabilityGroup ProdDag123 -StartTime "1 Apr 2010 9PM"
C:\PS&gt; CollectOverMetrics -DatabaseAvailabilityGroup ProdDag123 -EndTime "2 Apr 2010 9PM"</dev:code>
        <dev:remarks>
            <maml:para>Each of these variations generates a report for the 24 hour period between 9PM on 1 April 2010 and 9PM on 2 April 2010.</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 4 --------------------------</maml:title>
        <maml:introduction />
        <dev:code>C:\PS&gt; CollectOverMetrics -DatabaseAvailabilityGroup * -StartTime (Get-Date).AddDays(-7) -EndTime (Get-Date) -GenerateHtmlReport</dev:code>
        <dev:remarks>
            <maml:para>Generate a report of all operations over the last week for each database availability group in the organisation.  It then takes all of the operations in these reports and combines them into a summary report formatted as an HTML file.  If the command was run at 1PM on May 1, 2010, the summary report will be named FailoverSummary.2010_05_01_13_00_00.html.
</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 5 --------------------------</maml:title>
        <maml:introduction />
        <dev:code>C:\PS&gt; CollectOverMetrics -SummariseCsvFiles (dir *.csv)</dev:code>
        <dev:remarks>
            <maml:para>Read the contents of all the CSV files and use that data to build the summary report HTML.
</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 6 --------------------------</maml:title>
        <maml:introduction />
        <dev:code>C:\PS&gt; CollectOverMetrics -SummariseCsvFiles (dir *.csv) -Database MailboxDatabase123,MailboxDatabase456
C:\PS&gt; CollectOverMetrics -SummariseCsvFiles (dir *.csv) -ReportFilter { $_.DatabaseName -notlike "Mailbox Database*" }
C:\PS&gt; CollectOverMetrics -SummariseCsvFiles (dir *.csv) -ReportFilter { ($_.ActiveOnStart -like "ServerXYZ.*") -and ($_.ActiveOnEnd -notlike "ServerXYZ.*") }</dev:code>
        <dev:remarks>
            <maml:para>These examples demonstrate ways that the summary HTML report may be filtered.  The first uses the '-Database' option, which takes a list of database names.  The summary report then only has data about those databases.  The next two examples use the '-ReportFilter' option; the second filters out all of the default databases, the second would have all of the operations where a database started on a particular server and ended somewhere else.</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>