Copyright Xerox Corporation 1979Inter-Office MemorandumToCommunication ProtocolsDateJune 14, 1976FromEd TaftLocationPalo AltoSubjectEvent Report ProtocolOrganizationPARC/CSLXEROXFiled on: EventReport.pressThe Event Report Protocol (ERP) is a means by which events occurring in our distributed systemsmay be collected and recorded for later analysis. The immediate application for this protocol is thecollection of hardware error reports from Altos so as to facilitate maintenance, but the protocol isnot limited to this function.The principal objective considered in the design of the protocol is that the act of generating an eventreport be as simple and straightforward to implement as possible. This objective is achieved at theexpense of making the processing of received reports somewhat more difficult than it mightotherwise be.This memo covers three topics: specification of a general Event Report Protocol, specialization ofthis protocol to deal specifically with Alto hardware errors, and description of the initialimplementation of an event report recipient process on Maxc.The General ProtocolThe reporting of an event is accomplished by means of an exchange of Pups between a generatorprocess and a recipient process. The recipient process resides at a well-advertised port (inter-networkaddress), whereas the generator process may transmit reports via an arbitrary port. The means bywhich a generator discovers the address of an appropriate recipient is not specified by this protocol.The generator initiates an event report by transmitting an Event Report Pup. Upon successfulreceipt of an Event Report Pup, the recipient returns an Event Report Reply Pup with matching PupIdentifier. The generator process is expected to retransmit the Event Report Pup (with the samePup ID) after a reasonable timeout if no Reply is received, and if feasible to take cognizance of anyother information available (such as receipt of an Error Pup).The generator is expected to choose Pup IDs in a manner that will facilitate correct processing bythe recipient. In particular, if duplicate suppression or maintenance of chronological sequence isimportant, then Pups should be sequence-numbered or time-stamped. The general protocol doesnot specify the choice of Pup IDs.Similarly, the interpretation of the Event Report Pup's contents is strictly a matter of conventionbetween the generator and recipient processes. We expect, for example, that Alto hardware errorreports will be directed to a different recipient (i.e., a different port) than, say, Bravo usage statistics,and we therefore do not require that the information be formatted or interpreted in a standard way.(Of course, one will probably want to use as a model the specific protocol to be presented in thenext section.) &pX]g~qi cr]pX-r7Bp \r]p-r7Bp Vr]p-r 7Bp`Os K9p Eo@ C@% Be5/ @ =%B .4 <W A 2" MU G C85 P 9a   `?/d &Event Report Protocol2It is assumed that an event may be reported in a single Event Report Pup, and therefore thatseparate Event Report Pups describe independent events. The consequence of this property is thatevent reports may be generated spontaneously, without any need for the generator process tomaintain state information between occurrences of events. The recipient will of course need toperform some processing, both to differentiate between reports arising from multiple sources and tofilter out duplicates and maintain correct sequence (where required). However, we anticipate that inmost applications, such processing will not be done in real time (immediately upon receipt ofreports) but rather will be deferred until the data is reduced or analyzed, at which time the analysisprogram can perform the necessary processing.The Pup type assignments for the ERP are:Event Report240 (octal)Event Report Reply241 (octal)Alto Error ReportsIn this section, we specify the manner in which Alto hardware errors are reported using the ERP.All Event Report Pups are directed to a server process residing at socket 30 on Maxc (i.e., at inter-network address 3#200#30). Since this server may move and we may eventually design a generalprotocol for dynamically discovering the addresses of widely-used services, report generatorprograms should be written in such a way that the recipient address is easy to change.The Pup ID is set to the sending Alto's calendar clock (the one returned by DayTime) so as toidentify the date and time of the report. This convention constrains an Alto to send Event ReportPups no more frequently than once every second (the grain of the calendar clock); otherwise,succeeding reports will appear to the recipient to be duplicates of the first. For Alto hardwareerrors (which will probably be generated by Swat), this does not seem an unreasonable assumption.The format of the Pup contents will be specified by Bob Sproull, who is implementing the Altosoftware responsible for reporting hardware errors.Maxc Recipient ImplementationThe ERP recipients are implemented as part of Pupsrv, the system background program thatcontrols Pup server processes such as Telnet and FTP. Pupsrv performs no logical processing onreceived event reports, but rather merely appends them to a file for later analysis.The association between ERP recipient sockets and files is established by a file Pupsrv.Run,which Pupsrv reads when it is started. This file contains one or more entries of the form:ERP socket-number, filenameFor example,ERP 30, AltoErrors.LogFor each Event Report Pup received on one of the declared sockets, the event is appended to thehighest-numbered existing version of the file associated with that socket (a new file is created ifnecessary). The file is kept open only while information is being appended, so it is possible for ananalysis program to rename the file when it is about to process the data contained within it, therebyforcing a new log file to be created next time an event report is received. To reduce overhead,Pupsrv does not write out event reports immediately upon their receipt, but rather buffers them forup to 30 minutes or until its internal buffers overflow.The event report log file consists of entries written as a sequence of 8-bit bytes. The format of eachentry is: fpG b= `#> _X ] Q \ C ZF Y3* W{A% U- S)P,u $@pNu$@p J=t GXp` DsB# B] Ai$8 ?V <;" ;z/3 9I 8p5, 6F 4T 23 .t +2p-+ ) S ((T %C:* #Q    ! *J P  H K O 8+  8 'F!   [>/]=Event Report Protocol3Length of entry, in bytes (including itself) (2 bytes)Pup source address (6 bytes)Pup ID (4 bytes)Pup contents (however many bytes it contained)Alto programmers interested in making use of the Maxc ERP server should be aware that itsoperation is relatively expensive. One should take care not to inundate it by sending too-frequentevent reports. For example, an event report generated by every keystroke (or even every Bravocommand, for example) would be totally unreasonable, whereas a summary generated by the "Quit"command would be perfectly acceptable. If the events of interest occur very frequently or involvegathering and transferring large volumes of information, it is better to buffer the data locally andlater transfer it all at once using FTP. fpGb6`_]. Z9 Y%K W9% V R TG SE Q( O>/JV TIMESROMAN  TIMESROMAN  TIMESROMANLOGO TIMESROMAN  TIMESROMAN  j/`eventreport.bravoTaftSeptember 3, 1979 5:37 PM