diff --git a/README.md b/README.md index ccf8e66a..d14120e9 100644 --- a/README.md +++ b/README.md @@ -24,35 +24,32 @@ Perfmon Metrics is a set of metric files and scripts used to perform performance #### JSON Format Explanation -"Name": The string name of the metric being defined +* `MetricName`: The string name of the metric being defined. -"Level": Integer value representing the relationship of this metric in a hierarchy of metrics. This field can be used along with "ParentCategory" to define a tree structure of metrics. Root level metrics have a level of 1 +* `Level`: Integer value representing the relationship of this metric in a hierarchy of metrics. This field can be used along with "ParentCategory" to define a tree structure of metrics. Root level metrics have a level of 1. -"BriefDescription": The description of the metric is measuring, long description will be in the documents section of this github +* `BriefDescription`: The description of what the metric is measuring. Long descriptions will be in the documents section of this GitHub. -"UnitOfMeasure": the unit of measure for a metric, can be time, frequency, number of samples, percent +* `UnitOfMeasure`: The unit of measure for a metric, can be time, frequency, number of samples, percent. -"Events": List of events and their alias which is used in the formula +* `Events`: List of events and their alias which is used in the formula. -{ -"Name": The name of the event from the JSON event list in the event list folder. May change per platform + * `Name`: The name of the event from the JSON event list in the event list folder. May change per platform. -"Alias": The alias used for the event in the formula -}, + * `Alias`: The alias used for the event in the formula. +* `Constants`: List of constants required for the given metric with the same fields as those defined for the event list: Name and Alias. -"Constants": List of constants required for the given metric with the same fields as those defined for the event list: Name and Alias. +* `Formula`: String providing the arithmetic to be performed to form the metric value based on the provided aliases. -"Formula": String providing the arithmetic to be performed to form the metric value based on the provided aliases. +* `Category`: Useful tagging for the metric. Intended to be used for parsing when creating a subset of metrics list. Some categories will be general, IO, TMA, microservices -"Category": Useful tagging for the metric. Intended to be used for parsing when creating a subset of metrics list. Some categories will be general, IO, TMA, microservices +* `Threshold`: When the threshold evaluates as true then it indicates that this metric is meaningful for the current analysis. ` X` requires that the value of the node should hold true the relationship with X. `P` requires that the nodes parent needs to pass the threshold for this to be true. `;` separator, `&` and, `|` or `$issueXX` is a unique tag that associates together multiple nodes from different categories of the tree. For example, Bad_Speculation is tightly coupled with Branch_Resteers (from the Frontend_Bound Category). `~overlap` indicates a weight of a specific node overlaps with its siblings. I.e. their costs are not mutually exclusive. For example, value of Branch_Resteers may overlap with ICache_Misses. +Example: `> 0.2 & P` means the current node's values is above 20% and the Parent node is highlighted. -"Threshold": When the threshold evaluates as true then it indicates that this metric is meaningful for the current analysis. ' X' requires that the value of the node should hold true the relationship with X. 'P' requires that the nodes parent needs to pass the threshold for this to be true. ';' separator, '&' and, '|' or '$issueXX' is a unique tag that associates together multiple nodes from different categories of the tree. For example, Bad_Speculation is tightly coupled with Branch_Resteers (from the Frontend_Bound Category). '~overlap' indicates a weight of a specific node overlaps with its siblings. I.e. their costs are not mutually exclusive. For example, value of Branch_Resteers may overlap with ICache_Misses. -Example: "> 0.2 & P" means the current node's values is above 20% and the Parent node is highlighted. +* `ResolutionLevels`: List of resolution levels that tools can choose to compute for the given metric. For example, if the list contains `THREAD`, then the metric can be computed at a per thread level. The metric is not valid when data is aggregated at a level not present in the resolution level list. If the list contains `THREAD, CORE, SOCKET, SYSTEM` then this indicates that a tool can choose to compute this metric at the thread level, or aggregate counts across core or socket or system level to report a broader metric resolution. -"ResolutionLevels": List of resolution levels that tools can choose to compute for the given metric. For example, if the list contains "THREAD", then the metric can be computed at a per thread level. The metric is not valid when data is aggregated at a level not present in the resolution level list. If the list contains "THREAD, CORE, SOCKET, SYSTEM" then this indicates that a tool can choose to compute this metric at the thread level, or aggregate counts across core or socket or system level to report a broader metric resolution. - -"MetricGroup": Grouping for perf, further explanation added on perf script release +* `MetricGroup`: Grouping for perf, further explanation added on perf script release. #### JSON Constant Explanation @@ -210,13 +207,13 @@ workload or tool preference. ### MSRIndex Additional MSRs may be required for programming certain events. This field gives the address of such MSRS. -Potential values are: +Examples include: * 0x3F6: MSR_PEBS_LD_LAT - used to configure the Load Latency Performance Monitoring Facility * 0x1A6/0x1A7: MSR_OFFCORE_RSP_X - used to configure the offcore response events ### MSRValue -When an MSRIndex is used (indicated by the MSRIndex column), this field will contain the value that needs to be loaded into the -register whose address is given in MSRIndex column. For example, in the case of the load latency events, MSRValue defines the +When an MSRIndex is used (indicated by MSRIndex), this field will contain the value that needs to be loaded into the +register whose address is given in MSRIndex. For example, in the case of the load latency events, MSRValue defines the latency threshold value to write into the MSR defined in MSRIndex (0x3F6). ### CollectPEBSRecord