Menu
Extensibility Solutions
  • Plug-Ins
  • Tools
  • Filters
  • Scripts
    • Developer Documentation
  • OmniEngine Plugin API
  • OmniPeek Plugin API
  • OmniScript Reference
  • Peek COM API Reference
  • Decoder Language Reference
  • ProtoSpecs XML Guidelines
  • Peek Reporting Framework
  • Automation Primer
  • Plug-in Primer

    • Peek Reporting Framework

    Overview

    Omnipeek has the ability to save statistics as HTML or XML reports, enabling you to view network information with a web browser. In addition, you may choose to save statistics as either tab- or comma-delimited text, suitable for importing into a spreadsheet program for further processing. Use the "Save Report" command in the File menu to save statistics for any capture window. Use the "Statistics Output" command in the Monitor menu to access a dialog in which you can enable this feature to automatically output statistics information, for either capture windows or global statistics, at regular intervals.

    Omnipeek allows for a great deal of report customization. You can modify the behavior of the built-in reports by modifying the file "ReportPrograms.xml". This file is located in the Reports\Control subfolder of the installation folder (e.g., C:\Program Files\LiveAction\AiroPeek\1033\Reports\Control). You can also add reports by adding files into the Reports\Control subdirectory.

    ReportPrograms Format

    When the program is launched, each file in the Reports\Control folder is processed to build the list of possible reports. These files are written using eXtensible Markup Language (XML). Each file contains one or more Reports. Each Report has a name (which is the name that appears in the program); output type (HTML, XML, or Text); an optional description (which appears in the Save Report dialog); and a list of commands. The possible commands are Copy, which copies files; Process, which actually produces the statistics files; and ShellExecute, which is used to execute programs or files. A description of each of these commands follows.

    ReportPrograms Commands

    Copy [Source=<\path>] [Overwrite=<true|false>]
    Copies a file. The source path to the file is implicitly the \Reports folder within the program installation folder (e.g.,
    C:\Program Files\LiveAction\Omnipeek\1033\Reports\). The destination path is the folder specified by the user in the Statistics Output or Save Report dialogs. Using the "Source" attribute, you can specify an optional source path suffix. For example, all the built- in reports store their files in \Reports\Auxiliary, and use the copy command as follows: <Copy Source="\Auxiliary"> This copies files from the Auxiliary folder into the destination folder the user has specified. By default, files which already exist in the destination folder are not overwritten when copying. This can be overridden using the "Overwrite" attribute, as follows: <Copy Overwrite="true">. In this case, the copy operation will overwrite files in the destination folder.
    Process [Source=<\path>] [Delimiter=<delimiter>]
    Outputs statistics to files. The optional attributes are different depending on the output type (XML, HTML, or Text). For HTML output, the "Source" attribute works just as with the Copy command, as an optional source path suffix for the HTML template files. For example, the built-in HTML reports store their template files in the \Reports\Templates folder, so the Process command looks like this: <Process Source="\Templates">. Process does not have any optional attribute for the XML output type. For the Text output type, the "Delimiter" attribute specifies the field delimiter, while the "Extension" attribute specifies the file extension to be given to the output files. For example, for command-delimited output, you would use the following: <Process Delimiter="," Extension="csv" />. If no extension is supplied, the default is "txt".
    ShellExecute
    Executes a program or file. Note that this only occurs when doing Save Report. ShellExecute commands are ignored when reports are generated with Statistics Output.

    ReportPrograms Document Type Definition:

    <!DOCTYPE ReportPrograms [
        <!ELEMENT ReportPrograms (Report*)>
        <!ATTLIST ReportPrograms Version CDATA #REQUIRED>
        <!ELEMENT Report (Description?, Commands)>
        <!ATTLIST Report Name CDATA #REQUIRED>
        <!ATTLIST Report Output (HTML | Text | XML) #REQUIRED>
        <!ELEMENT Description (#PCDATA)>
        <!ELEMENT Commands ((Copy | Process | ShellExecute)*)>
        <!ELEMENT Copy (File*)>
        <!ATTLIST Copy Source CDATA #IMPLIED>
        <!ATTLIST Copy Overwrite ( true | false ) "false">
        <!ELEMENT Process (File*)>
        <!ATTLIST Process Source CDATA #IMPLIED>
        <!ATTLIST Process Delimiter CDATA #IMPLIED>
        <!ELEMENT ShellExecute (File)>
        <!ELEMENT File (#PCDATA)>
    ]>

    XML Templates

    XML Reports are generated into a single file. The \Reports\Auxiliary folder contains a set of XSL stylesheets which are meant to be used in conjunction with the XML output file. These stylesheets control the look of the XML output when opened in a web browser. By modifying the stylesheets, you have complete control of the appearance of the XML reports generated by the program.

    HTML Templates

    When producing HTML reports, the program will process HTML files in each template file and replace special keywords with packet statistics values and write the resulting files to the output folder. This method allows you to have almost complete control over the HTML that is produced. For example, you can customize the format and appearance of the tables that are produced, include your own text, graphics, and links, and you can keep separate files for each statistics table, or combine them into a single HTML document. Every piece of information in the node, protocol, and summary statistics windows can be accessed.

    HTML Template Keywords

    LiveAction, Inc. has provided a set of template files that you can use without modification, or as a starting point for customizing your own statistics tables.

    Global Keywords

    <%STATS_TIME%>
    The date and time that the files last updated.
    <%NODE_STATS_TOTAL_PACKETS%>
    The total number of packets sent and received by nodes on the network.
    <%NODE_STATS_TOTAL_BYTES%>
    The total number of bytes sent and received by nodes on the network.
    <%NODE_STATS_PHYSICAL_COUNT%>
    The total number of physical addresses that have sent or received packets on the network.
    <%NODE_STATS_LOGICAL_COUNT%>
    The total number of logical addresses that have sent or received packets on the network.
    <%NODE_STATS_TABLE_START%> and <%NODE_STATS_TABLE_END%>
    These keywords mark the start and end of template data that will be repeatedly written for each node in the "Node Statistics" window. The template data should contain specific keywords that will be replaced for each item.
    <%PROTO_STATS_TOTAL_PACKETS%>
    The number of packets observed on the network.
    <%PROTO_STATS_TOTAL_BYTES%>
    The number of bytes observed on the network.
    <%PROTO_STATS_PROTOCOL_COUNT%>
    The number of protocols that have been observed on the network.
    <%PROTO_STATS_TABLE_START%> and <%PROTO_STATS_TABLE_END%>
    These keywords mark the start and end of template data that will be repeatedly written for each protocol in the "Protocol Statistics" window. The template data should contain specific keywords that will be replaced for each item.
    <%SUM_STATS_START_TIME%>
    The time that summary statistics began monitoring.
    <%SUM_STATS_START_DATE%>
    The date that summary statistics began monitoring.
    <%SUM_STATS_CAPTURE_DURATION%>
    The amount of time that summary statistics have been monitoring.
    <%SUM_STATS_TABLE_START%> and <%SUM_STATS_TABLE_END%>
    These keywords mark the start and end of template data that will be repeatedly written for each summary item in the "Summary Statistics" window. The template data should contain specific keywords that will be replaced for each item.

    Table Keywords

    These keywords can appear within the template data marked with the "TABLE_START" and "TABLE_END" keywords from the list of global keywords described above (the table keywords are actually prefixed by the kind of statistics table). Any text that appears between the table start and end keywords will be repeatedly searched for the table-specific keywords and written for each item in the statistics list.

    Node Statistics

    <%NODE_STATS_TABLE_COLOR%>
    A 3-byte RGB color value (in hexadecimal, including the "#" character).
    <%NODE_STATS_TABLE_NODE%>
    The name or address of the node.
    <%NODE_STATS_TABLE_SOURCE_BARWIDTH%>
    An percentage value representing the length of the bar graph. This width is calculated using the number of packets sent by the node and the total number of packets sent on the network.
    <%NODE_STATS_TABLE_SOURCE_PERCENT%>
    A percentage value representing the proportion of packets sent by the node in relation to the total number of packets sent on the network.
    <%NODE_STATS_TABLE_SOURCE_PACKETS%>
    The number of packets sent by the node.
    <%NODE_STATS_TABLE_SOURCE_BYTES%>
    The number of bytes sent by the node.
    <%NODE_STATS_TABLE_DEST_BARWIDTH%>
    An percentage value representing the length of the bar graph. This width is calculated using the number of packets received by the node and the total number of packets received on the network.
    <%NODE_STATS_TABLE_DEST_PERCENT%>
    A percentage value representing the proportion of packets received by the node in relation to the total number of packets received on the network.
    <%NODE_STATS_TABLE_DEST_PACKETS%>
    The number of packets received by the node.
    <%NODE_STATS_TABLE_DEST_BYTES%>
    The number of bytes received by the node.

    Protocol Statistics

    <%PROTO_STATS_TABLE_COLOR%>
    A 3-byte RGB color value (in hexadecimal, including the "#" character).
    <%PROTO_STATS_TABLE_PROTOCOL%>
    The name or hexadecimal representation of the protocol.
    <%PROTO_STATS_TABLE_BARWIDTH%>
    An percentage value representing the length of the bar graph.
    <%PROTO_STATS_TABLE_PERCENT%>
    A percentage value representing the proportion of packets of the protocol type in relation to the total number of packets observed on the network.
    <%PROTO_STATS_TABLE_PACKETS%>
    The number of packets attributed to the protocol.
    <%PROTO_STATS_TABLE_BYTES%>
    The number of bytes attributed to the protocol.

    Summary Statistics

    <%SUM_STATS_TABLE_NAME%>
    The name of the summary entry.
    <%SUM_STATS_TABLE_GROUP%>
    The name of the group to which the summary entry belongs.
    <%SUM_STATS_TABLE_PACKETS%>
    The number of packets seen for this summary entry.
    <%SUM_STATS_TABLE_BYTES%>
    The number of bytes seen for this summary entry.
    <%SUM_STATS_TABLE_P_PER_SECOND%>
    Average packets per second for this entry.
    <%SUM_STATS_TABLE_B_PER_SECOND%>
    Average bytes per second for this entry.
    <%SUM_STATS_TABLE_PERCENTAGE_OF_PACKETS%>
    Percentage of total packets seen for this entry.
    <%SUM_STATS_TABLE_PERCENTAGE_OF_BYTES%>
    Percentage of total bytes seen for this entry.