~ubuntu-branches/ubuntu/utopic/numactl/utopic-proposed : revision 14

1

diff -ruN numactl-2.0.8-rc5.orig/numastat.8 numactl-2.0.8-rc5.new/numastat.8

2

--- numactl-2.0.8-rc5.orig/numastat.8 2012-08-23 15:50:37.000000000 -0400

3

+++ numactl-2.0.8-rc5.new/numastat.8 2012-10-07 00:05:46.676484265 -0400

4

@@ -1,82 +1,155 @@

5

-.\" t

6

7

-.\"

8

-.\" Permission is granted to make and distribute verbatim copies of this

9

-.\" manual provided the copyright notice and this permission notice are

10

-.\" preserved on all copies.

11

-.\"

12

-.\" Permission is granted to copy and distribute modified versions of this

13

-.\" manual under the conditions for verbatim copying, provided that the

14

-.\" entire resulting derived work is distributed under the terms of a

15

-.\" permission notice identical to this one.

16

-.\"

17

-.\" Since the Linux kernel and libraries are constantly changing, this

18

-.\" manual page may be incorrect or out-of-date. The author(s) assume no

19

-.\" responsibility for errors or omissions, or for damages resulting from

20

-.\" the use of the information contained herein.

21

-.\"

22

-.\" Formatted or processed versions of this manual, if unaccompanied by

23

-.\" the source, must acknowledge the copyright and authors of this work.

24

-.TH NUMACTL 8 "Nov 2004" "SuSE Labs" "Linux Administrator's Manual"

25

-.SH NAME

26

-numastat \- Print statistics about NUMA memory allocation

27

-.SH SYNOPSIS

28

-numastat

29

-.SH DESCRIPTION

30

+.TH "numastat" "8" "1.0.0" "Bill Gray" "Administration"

31

+.SH "numastat"

32

+.LP

33

+\fBnumastat\fP \- Show per-NUMA-node memory statistics for processes and the operating system

34

+.SH "SYNTAX"

35

+.LP

36

+\fBnumastat\fP

37

+.br

38

+.LP

39

+\fBnumastat\fP [\fI\-V\fP]

40

+.br

41

+.LP

42

+\fBnumastat\fP [\fI\<PID>|<pattern>...\fP]

43

+.br

44

+.LP

45

+\fBnumastat\fP [\fI\-c\fP] [\fI\-m\fP] [\fI\-n\fP] [\fI\-p <PID>|<pattern>\fP] [\fI\-s[<node>]\fP] [\fI\-v\fP] [\fI\-z\fP] [\fI\<PID>|<pattern>...\fP]

46

+.br

47

+.SH "DESCRIPTION"

48

+.LP

49

.B numastat

50

-displays NUMA allocations statistics from the kernel memory allocator.

51

-Each process has NUMA policies that specifies on which node pages

52

-are allocated. See

53

-.I set_mempolicy(2)

54

-or

55

-.I numactl(8)

56

-on details of the available policies.

57

-The numastat counters keep track on what nodes memory is finally allocated.

58

-

59

-The counters are separated for each node. Each count event is the allocation

60

-of a page of memory.

61

-

62

+with no command options or arguments at all, displays per-node NUMA hit and

63

+miss system statistics from the kernel memory allocator. This default

64

+\fBnumastat\fP behavior is strictly compatible with the previous long-standing

65

+\fBnumastat\fP perl script, written by Andi Kleen. The default \fBnumastat\fP

66

+statistics shows per-node numbers (in units of pages of memory) in these categories:

67

+.LP .B numa_hit

68

-is the number of allocations where an allocation was intended for

69

-that node and succeeded there.

70

-

71

+is memory successfully allocated on this node as intended.

72

+.LP .B numa_miss

73

-shows how often an allocation was intended for this node, but ended up

74

-on another node due to low memory.

75

-

76

+is memory allocated on this node despite the process preferring some different node. Each

77

+.I numa_miss

78

+has a

79

+.I numa_foreign

80

+on another node.

81

+.LP .B numa_foreign

82

-is the number of allocations that were intended for another node,

83

-but ended up on this node. Each

84

+is memory intended for this node, but actually allocated on some different node. Each .I numa_foreign

85

-event has a

86

+has a .I numa_miss on another node.

87

-

88

+.LP .B interleave_hit

89

-is the number of interleave policy allocations that were intended for a

90

-specific node and succeeded there.

91

-

92

+is interleaved memory successfully allocated on this node as intended.

93

+.LP .B local_node

94

-is incremented when a process running on the node allocated

95

-memory on the same node.

96

-

97

+is memory allocated on this node while a process was running on it.

98

+.LP .B other_node

99

-is incremented when a process running on another node allocated memory on that node.

100

-.SH SEE ALSO

101

-.I numactl(8)

102

-.I set_mempolicy(2)

103

-.I numa(3)

104

+is memory allocated on this node while a process was running on some other node.

105

+.LP

106

+Any supplied options or arguments with the \fBnumastat\fP command will

107

+significantly change both the content and the format of the display. Specified

108

+options will cause display units to change to megabytes of memory, and will

109

+change other specific behaviors of \fBnumastat\fP as described below.

110

+.SH "OPTIONS"

111

+.LP

112

+.TP

113

+\fB\-c\fR

114

+Minimize table display width by dynamically shrinking column widths based on

115

+data contents. With this option, amounts of memory will be rounded to the

116

+nearest megabyte (rather than the usual display with two decimal places).

117

+Column width and inter-column spacing will be somewhat unpredictable with this

118

+option, but the more dense display will be very useful on systems with many

119

+NUMA nodes.

120

+.TP

121

+\fB\-m\fR

122

+Show the meminfo-like system-wide memory usage information. This option

123

+produces a per-node breakdown of memory usage information similar to that found

124

+in /proc/meminfo.

125

+.TP

126

+\fB\-n\fR

127

+Show the original \fBnumastat\fP statistics info. This will show the same

128

+information as the default \fBnumastat\fP behavior but the units will be megabytes of

129

+memory, and there will be other formatting and layout changes versus the

130

+original \fBnumastat\fP behavior.

131

+.TP

132

+\fB\-p\fR <\fBPID\fP> or <\fBpattern\fP>

133

+Show per-node memory allocation information for the specified PID or pattern.

134

+If the \-p argument is only digits, it is assumed to be a numerical PID. If

135

+the argument characters are not only digits, it is assumed to be a text

136

+fragment pattern to search for in process command lines. For example,

137

+\fBnumastat -p qemu\fP will attempt to find and show information for processes

138

+with "qemu" in the command line. Any command line arguments remaining after

139

+\fBnumastat\fP option flag processing is completed, are assumed to be

140

+additional <\fBPID\fP> or <\fBpattern\fP> process specifiers. In this sense,

141

+the \fB\-p\fP option flag is optional: \fBnumastat qemu\fP is equivalent to

142

+\fBnumastat -p qemu\fP

143

+.TP

144

+\fB\-s[<node>]\fR

145

+Sort the table data in descending order before displaying it, so the biggest

146

+memory consumers are listed first. With no specified <node>, the table will be

147

+sorted by the total column. If the optional <node> argument is supplied, the

148

+data will be sorted by the <node> column. Note that <node> must follow the

149

+\fB\-s\fP immediately with no intermediate white space (e.g., \fBnumastat

150

+\-s2\fP).

151

+.TP

152

+\fB\-v\fR

153

+Make some reports more verbose. In particular, process information for

154

+multiple processes will display detailed information for each process.

155

+Normally when per-node information for multiple processes is displayed, only

156

+the total lines are shown.

157

+.TP

158

+\fB\-V\fR

159

+Display \fBnumastat\fP version information and exit.

160

+.TP

161

+\fB\-z\fR

162

+Skip display of table rows and columns of only zero valuess. This can be used

163

+to greatly reduce the amount of uninteresting zero data on systems with many

164

+NUMA nodes. Note that when rows or columns of zeros are still displayed with

165

+this option, that probably means there is at least one value in the row or

166

+column that is actually non-zero, but rounded to zero for display. .SH NOTES

167

-numastat output is only available on NUMA systems.

168

-

169

-numastat assumes the output terminal has a width of 80 characters

170

-and tries to format the output accordingly.

171

-.SH EXAMPLES

172

-.I watch -n1 numastat

173

+\fBnumastat\fP attempts to fold each table display so it will be conveniently

174

+readable on the output terminal. Normally a terminal width of 80 characters is

175

+assumed. When the \fBresize\fP command is available, \fBnumastat\fP attempts

176

+to dynamically determine and fine tune the output tty width from \fBresize\fP

177

+output. If \fBnumastat\fP output is not to a tty, very long output lines can

178

+be produced, depending on how many NUMA nodes are present. In all cases,

179

+output width can be explicitly specified via the \fBNUMASTAT_WIDTH\fP

180

+environment variable. For example, \fBNUMASTAT_WIDTH=100 numastat\fP. On

181

+systems with many NUMA nodes, \fBnumastat \-c \-z ....\fP can be very helpful

182

+to selectively reduce the amount of displayed information.

183

+.SH "ENVIRONMENT VARIABLES"

184

+.LP

185

+.TP

186

+NUMASTAT_WIDTH

187

+.SH "FILES"

188

+.LP

189

+\fI/proc/*/numa_maps\fP

190

+.br

191

+\fI/sys/devices/system/node/node*/meminfo\fP

192

+.br

193

+\fI/sys/devices/system/node/node*/numastat\fP

194

+.SH "EXAMPLES"

195

+.I numastat \-c \-z \-m \-n

196

+.br

197

+.I numastat \-czs libvirt kvm qemu

198

+.br

199

+.I watch \-n1 numastat .br

200

-.I watch -n1 --differences=accumulative numastat

201

-.SH FILES

202

-/sys/devices/system/node/node*/numastat

203

-.SH BUGS

204

-The output formatting on machines with a large number of nodes

205

-could be improved.

206

+.I watch \-n1 \-\-differences=cumulative numastat

207

+.SH "AUTHORS"

208

+.LP

209

+The original \fBnumastat\fP perl script was written circa 2003 by Andi Kleen

210

+<andi.kleen@intel.com>. The current \fBnumastat\fP program was written in 2012

211

+by Bill Gray <bgray@redhat.com> to be compatible by default with the original,

212

+and to add options to display per-node system memory usage and per-node process

213

+memory allocation.

214

+.SH "SEE ALSO"

215

+.LP

216

+.BR numactl (8),

217

+.BR set_mempolicy( 2),

218

+.BR numa (3)