1 06/26/86 summarize_sys_log, ssl
2
3 Syntax as a command: ssl log_selector -control control_path
4 -control_args
5
6
7 Function: summarizes activity in a system log. The specified range of
8 messages in the log are matched against the selection and printing
9 criteria in the control file and written or summarized to the specified
10 I/O switches. This command requires that a set of I/O switches used
11 to write log messages and summaries be attached before the command is
12 executed and detached afterwards. Control arguments determine what
13 range of messages are processed, and how those messages are formatted
14 in the output.
15
16
17 Arguments:
18 log_selector
19 is the pathname of a log to be summarized The pathname must specify
20 the first segment in the log. This argument is incompatible with
21 any of the log selection control arguments.
22
23
24 Control arguments for log section:
25 -admin
26 specifies that the admin log is to be summarized. The admin
27 commands log is called "admin_log", and is located in the
28 >sc1>as_logs directory. This argument is incompatible with any of
29 the other log selection control arguments, or an explicit log
30 pathname.
31 -answering_service, -as
32 specifies that the answering service log is to be summarized. The
33 Answering Service log family is called "log", and is located in the
34 >sc1>as_logs directory. This argument is incompatible with any of
35 the other log selection control arguments, or an explicit log
36 pathname.
37
38
39 -dm_system, -dms
40 specifies that the data management system log for the process's
41 current AIM authorization is to be summarized. The data management
42 log is called "dm_system_log", and its location depends on the AIM
43 access class of the log. This argument is incompatible with any of
44 the other log selection control arguments, or an explicit log
45 pathname. Reading the log requires access to the dm_admin_ gate.
46 -dsa_sys_log, -dsasl
47 specifies that the DSA system log is to be examined. The location
48 of this log is specified in the DSA NIT. This is a ring 1 log, and
49 the user must have access to dsa_log_admin_gate_ to read it. This
50 argument is incompatible with any of the other log selection control
51 arguments, or an explicit log pathname.
52 -dsa_sys_aep_log, -dsasal
53 specifies that the DSA system AEP log is to be examined. The
54 location of this log is specified in the DSA NIT. This is a ring 1
55 log, and the user must have access to dsa_log_admin_gate_ to read
56 it. This argument is incompatible with any of the other log
57 selection control arguments, or an explicit log pathname.
58
59
60 -mc_log LOG_NAME, -mcl LOG_NAME
61 specifies that the message coordinator daemon log named LOG_NAME
62 is to be summaried. All message coordinator logs are located in the
63 >sc1>as_logs directory; their names depend on the daemon to which
64 they belong. This argument is incompatible with any of the other
65 log selection control arguments, or an explicit log pathname.
66
67
68 -pathname LOG_PATH, -pn LOG_PATH
69 specifies the pathname of the log to be summarized. the pathname
70 must specify the first segment in the log. This argument is
71 incompatible with any of the other log selection control arguments,
72 or an explicit log pathname.
73 -syserr
74 specifies that the syserr log is to be summarized. The syserr log
75 is named "syserr_log". The first segment in the family is
76 >sl1>syserr_log; there may be a history segment in >sl1, and older
77 history segments are in the directory >sc1>syserr_log. This
78 argument is incompatible with any of the other log selection control
79 arguments, or an explicit log pathname.
80
81
82 Control arguments for control:
83 -control CONTROL_PATH
84 specifies the pathname of the selection control file to be used in
85 summarizing the log messages. See "Control File Syntax" and "List
86 of Selection Operators", below for details of the syntax. This
87 argument must be specified.
88 -for TIME, -for NUMBER
89 specifies a number of messages to process, or a time interval
90 relative to the starting time specified by -from in which the
91 messages must be contained. The number of messages is the actual
92 number of messages processed, not the number of messages examined in
93 the log. This is incompatible with -to and -last.
94
95
96 -from TIME, -fm TIME, -from NUMBER, -fm NUMBER
97 specifies that the first message processed is the first message at
98 or after the specified time or sequence number; if -reverse is
99 specified, the first message is the one at or before the specified
100 value. If no -from value is specified, the default is the first
101 message in the log, or the last if -reverse is specified. This is
102 incompatible with -last.
103 -last NUMBER, -lt NUMBER, -last TIME, -lt TIME
104 specifies that only the last NUMBER messages, or the messages since
105 TIME, are to be processed. If a NUMBER is specified, it specifies
106 the actual number of messages to be processed, not the number of
107 messages examined in the log. This is incompatible with -from and
108 -for.
109
110
111 -to TIME, -to NUMBER
112 specifies the last message to be processed, either by message time
113 or sequence number. If not specified, the default is all the
114 remaining messages in the log. This is incompatible with -for.
115
116
117 Control arguments for message expansion:
118 -interpret, -int
119 specifies that the binary data in expanded messages is to be
120 displayed as interpreted text, by calling the appropriate
121 expand_XXX_msg_ program for the data class of the message. If the
122 -octal control argument is also specified, the binary data is
123 displayed both in interpreted form and as octal data. This is the
124 default.
125 -octal, -oc
126 specifies that the binary data in expanded messages is to be
127 displayed in octal, rather than, or in addition to, the interpreted
128 representation. If both octal and interpreted representations are
129 desired, both the -octal and -interpret control arguments must be
130 supplied.
131
132
133 Control arguments for message format:
134 -continuation_indent N, -ci N
135 specifies that all messages are to be formatted for printing with
136 continuation lines prefixed by N spaces, or, if the keyword
137 "standard" or "std" is used in place of a number, with the
138 continuation lines indented sufficiently to line up under the first
139 character of the text of the message. The value of N must be
140 between zero and fifty. By default, continuation lines are indented
141 to the "standard" indentation.
142
143
144 -date_format FORMAT_STRING, -dfmt FORMAT_STRING
145 specifies a date/time format string see time_format.gi.info or the
146 Multics Programmer's Reference Manual Order No. AG91 to be used
147 when formatting the date when successive messages are printed with
148 different dates. The date string is printed on a line entirely by
149 itself, preceded by a blank line. If the date format string is
150 blank, no date separators will be printed; this should be used if a
151 -time_format string is specified that includes the date as well.
152 The default date string is "^9999yc-^my-^dm ^da ^za", which prints
153 as for example "1984-10-31 Wed est".
154
155 By specifying null strings for date, time, and number formats, the
156 log can be printed and saved, so that it can be compared to another
157 log script later, without spurious mis-compares because the times
158 and sequence numbers do not match.
159
160
161 -duplicates, -dup
162 inhibits the printing of "=" messages for messages whose text is the
163 same as the previous message printed. All messages are printed
164 exactly as they appear in the log.
165 -indent N, -ind N
166 specifies that all messages are to be formatted for printing
167 prefixed with N spaces. The value of N must be between zero and
168 fifty. The indentation is printed before any data associated with
169 the message, including the message prefix. By default, there is no
170 indentation.
171
172
173 -line_length N, -ll N
174 specifies the line length used when formatting message text and data
175 for printing. The value N must be between 25 and 500. By
176 default, it is the line length associated with the user_output I/O
177 switch, or, if none as for an absentee, it is 132 for line
178 printer output.
179 -prefix STRING, -pfx STRING
180 specifies that all messages are to be formatted with the specified
181 string as a prefix. This prefix appears after the indentation if
182 any was specified. The prefix must explicitly include trailing
183 spaces, if any are desired to separate the prefix from the message
184 text. By default, there is no prefix.
185 -no_duplicates, -ndup
186 prints "==" for messages whose text is the same as the previous
187 message printed. This is the default.
188
189
190 -number_format IOA_STRING, -nfmt IOA_STRING
191 specifies an ioa_ string to be used when printing the sequence
192 number for the message. If the string is null, no sequence number
193 is printed with the message. The default is "^7d". See the
194 Multics Subroutines and I/O Modules manual Order No. AG93 for a
195 description of ioa_control strings.
196 -time_format FORMAT_STRING, -tfmt FORMAT_STRING
197 specifies a date/time format string see time_format.gi.info or the
198 Multics Programmer's Reference Manual Order No. AG91 to be used
199 when formatting the message time portion of the message. If the
200 string is null, no time is printed with the messages. The default
201 time format is "iso_time", which prints as for example "23:21:59".
202
203
204 Miscellaneous control arguments:
205 -procedure NAME, -proc NAME
206 specifies that entrypoints in the procedure called NAME are to be
207 used instead of entrypoints in log_read_ to read the log. This is
208 used to read logs protected by inner-ring subsystems, where the
209 inner-ring subsystem provides a replacement log-reading procedure.
210 See "Access Required," below.
211
212
213 Notes: The summarize_sys_log command produces multiple copies of
214 printable files, each containing different abstracts of the log being
215 scanned. There are two basic abstracting techniques: writing lines
216 selected by character string matching into the file, and writing the
217 total number of occurrences of specified types of lines.
218
219 There are two possible methods for specifying the starting point of an
220 invocation of the sys_log_scan_report command. The recommended method
221 is to use a value segment to record the times, as follows:
222
223 vs first_entry clock calendar_clock vg last_entry +1usec
224 vs last_entry clock calendar_clock
225 ssl LOG_PATH -from vg first_entry -to last_entry
226
227
228 Notes on output: Rather than writing directly into files, the command
229 writes its output through user-specified I/O switches. No I/O switch
230 attachment or detachment is done by the program. It is the
231 responsibility of the caller to ensure that all switches named in the
232 control segment are attached and opened with the io_call command.
233 Usually, these are attached to storage system segments through the
234 vfile_ I/O module.
235
236
237 Notes on control file syntax: The control file names the output
238 switches and selection operations used by the command. The general
239 format of a control line in the file is:
240
241 SWITCHNAME,SEVERITY,OPCODE,LITERAL.
242
243 switchname
244 is the name of an I/O switch to which this information will be
245 written.
246 severity
247 indicates the minimum severity message this control line applies to,
248 or a range of severities. The severity value may either be a
249 decimal integer, or ranges consisting of a pair decimal integers
250 separated by a colon "20:29".
251
252
253 opcode
254 describes the kind of selection desired. It may have any one of the
255 values listed below:
256 all
257 selects all lines.
258 any
259 selects any lines containing the string <literal>.
260 allx
261 like all, but messages with binary data have the data expanded
262 when printed.
263 anyx
264 like any, but messages with binary data have the data expanded
265 when printed.
266
267
268 bcount
269 counts all lines that begin with the string <literal> and places
270 the total on the named switch after all entries are written.
271 begin
272 selects all lines with the string <literal> as their beginning.
273 beginx
274 like begin, but messages with binary data have the data expanded
275 when printed.
276 count
277 counts all lines that contain the string <literal> and places the
278 total on the named switch after all entries are written.
279 nbegin
280 diverts any lines that begin with the string <literal> from the
281 output switch if later selected by an all, any, or begin opcode.
282
283
284 not
285 diverts any lines that contain the string <literal> from the
286 output switch if later selected by an all or begin opcode.
287
288 To be effective, the not and nbegin lines for a particular switch
289 may precede the all, any, and begin control lines. The not and
290 nbegin lines do not affect the counting of lines. If no lines
291 were written on a switch, and a count is zero, the total line is
292 omitted.
293
294 If any lines were written on a switch, a count of total lines
295 written follows the totals for count and bcount. Thus, nothing
296 is written on a switch only if all selections fail.
297
298
299 literal
300 is an operand used to select the message; its function is described
301 individually for each opcode. All characters following the comma
302 are taken literally; no quote processing is performed.
303
304
305 Access required: For all except inner-ring logs, read permission is
306 required on the log segments themselves, and status permission is
307 required on their containing directories. If an access error is
308 encountered searching for older history logs, the search is stopped at
309 that point, and no further history will be available. For the logs
310 selected by control arguments, the control argument descriptions list
311 the standard history directories for the logs.
312
313 For inner-ring logs the data management system log is the only
314 standard inner-ring log, access to the logs is required, as is access
315 to the gate used by the log-reading procedure see -procedure.
316
317
318 Notes on severity values: Severity values in log messages are used to
319 indicate the importance of the message being logged, in a general way.
320 Most logs use increasing severity to indicate increasing importance,
321 but the actual meaning depends on the log. For the Answering Service
322 and Message Coordinator logs, the severities have the following
323 meanings:
324
325 0 => Message just logged
326 1 => Message logged and printed on a console
327 2 => Message logged and printed on a console with bells
328 3 => Message logged, printed, and the system crashed
329
330
331 For the syserr log, the severities have different meanings.
332
333 0 => Message logged and printed on syserr console
334 1 => Message logged, printed, and the system crashed
335 2 => Message logged, printed, and the process writing the
336 message is terminated.
337 3 => Message logged and printed, and console alarm sounded
338 4 => Message just logged, or printed if logging mechanism is
339 inoperable
340 5 => Message just logged, or discarded if it can't be logged
341
342 The severities 20 to 25 are handled just like 0 to 5, but are different
343 to indicate that the originating program was writing an access audit
344 message, rather than just an informative message.
345
346
347 Notes on inner-ring logs: Some applications create logs in an inner
348 ring that must be read using a special interface. The only standard
349 log to do this is the Data Management system log, and it is read by
350 specifying the -dm_system control argument which supplies both the
351 pathname and the procedure name dm_log_read_. If DSA is installed on
352 a system, then the -dsasl and -dsasal arguments can be used in a
353 similar fashion they will use the dsa_log_admin_gate_ procedure.
354 Other applications may provide their own special procedures for log
355 reading, in which case both the log pathname and the procedure name
356 must be supplied explicitly via the -pathname and -procedure control
357 arguments. Note that a log read using a reader procedure may enforce
358 additional access requirements as well as requiring access to the log
359 itself. In particular, the user must have access to the reader
360 procedure.