~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

68

.B numa_hit

69

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

70

-that node and succeeded there.

71

-

72

+is memory successfully allocated on this node as intended.

73

+.LP

74

.B numa_miss

75

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

76

-on another node due to low memory.

77

-

78

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

79

+.I numa_miss

80

+has a

81

+.I numa_foreign

82

+on another node.

83

+.LP

84

.B numa_foreign

85

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

86

-but ended up on this node. Each

87

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

88

.I numa_foreign

89

-event has a

90

+has a

91

.I numa_miss

92

on another node.

93

-

94

+.LP

95

.B interleave_hit

96

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

97

-specific node and succeeded there.

98

-

99

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

100

+.LP

101

.B local_node

102

-is incremented when a process running on the node allocated

103

-memory on the same node.

104

-

105

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

106

+.LP

107

.B other_node

108

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

109

-.SH SEE ALSO

110

-.I numactl(8)

111

-.I set_mempolicy(2)

112

-.I numa(3)

113

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

114

+.LP

115

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

116

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

117

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

118

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

119

+.SH "OPTIONS"

120

+.LP

121

+.TP

122

+\fB\-c\fR

123

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

124

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

125

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

126

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

127

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

128

+NUMA nodes.

129

+.TP

130

+\fB\-m\fR

131

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

132

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

133

+in /proc/meminfo.

134

+.TP

135

+\fB\-n\fR

136

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

137

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

138

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

139

+original \fBnumastat\fP behavior.

140

+.TP

141

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

142

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

143

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

144

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

145

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

146

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

147

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

148

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

149

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

150

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

151

+\fBnumastat -p qemu\fP

152

+.TP

153

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

154

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

155

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

156

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

157

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

158

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

159

+\-s2\fP).

160

+.TP

161

+\fB\-v\fR

162

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

163

+multiple processes will display detailed information for each process.

164

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

165

+the total lines are shown.

166

+.TP

167

+\fB\-V\fR

168

+Display \fBnumastat\fP version information and exit.

169

+.TP

170

+\fB\-z\fR

171

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

172

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

173

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

174

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

175

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

176

.SH NOTES

177

-numastat output is only available on NUMA systems.

178

-

179

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

180

-and tries to format the output accordingly.

181

-.SH EXAMPLES

182

-.I watch -n1 numastat

183

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

184

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

185

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

186

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

187

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

188

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

189

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

190

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

191

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

192

+to selectively reduce the amount of displayed information.

193

+.SH "ENVIRONMENT VARIABLES"

194

+.LP

195

+.TP

196

+NUMASTAT_WIDTH

197

+.SH "FILES"

198

+.LP

199

+\fI/proc/*/numa_maps\fP

200

+.br

201

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

202

+.br

203

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

204

+.SH "EXAMPLES"

205

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

206

+.br

207

+.I numastat \-czs libvirt kvm qemu

208

+.br

209

+.I watch \-n1 numastat

210

.br

211

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

212

-.SH FILES

213

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

214

-.SH BUGS

215

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

216

-could be improved.

217

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

218

+.SH "AUTHORS"

219

+.LP

220

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

221

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

222

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

223

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

224

+memory allocation.

225

+.SH "SEE ALSO"

226

+.LP

227

+.BR numactl (8),

228

+.BR set_mempolicy( 2),

229

+.BR numa (3)