edge logging - daq electronics edge logging.pdf · 1.0 edge logging ... usblogger filename start...

EDGE LOGGING

Use of EDGE Logger Interfaces and Recorded Messages

EDGE Logging

Use of EDGE Logger Interfaces and Recorded Messages Rev #001

1

COPYRIGHT ©2014 DAQ Electronics, LLC Revised 01/06/14 - Revision #001 This documentation is provided as a component part of DAQ Electronics. All parties or individuals who are in possession of the documentation accept in full and without exception or limitation the DAQ Electronics unrestricted rights of ownership of this material. This documentation is not available by any other means except by license which is only available from DAQ Electronics. Under no circumstances may any part or the whole of this documentation be reproduced, stored in a retrieval system, transmitted, copied, modified, distributed, displayed, sold, licensed, published or derivative works created there from in any form or by any means electronic mechanical, recording, or otherwise without the written permission of DAQ Electronics being obtained in advance of the requirement. It is expressly forbidden for the holder of this documentation to use this documentation either in its entirety or in part or any graphics to provide training or tuition, assistance or knowlEDGE transfer to any other party whatsoever, or for marketing of promotional literature or material of any type whatsoever without the prior written permission of DAQ Electronics. Use of this documentation in any manner inconsistent with the user manual and related documentation is strictly prohibited. Use of the documentation is not transferable. TRADEMARKS EntroWatch, EntroStar, Callisto, CallistoView, and StarWatch are trademarks of DAQ Electronics. All other product and company names may be the property of their respective owners. PROPRIETARY INFORMATION This documentation contains confidential and proprietary information which must be maintained in confidence and used only in a manner consistent with the documentation and may not be disclosed to any third parties. DAQ Electronics, LLC Piscataway Corporate Center 262B Old New Brunswick Road Piscataway, NJ 08854 USA T + 1.732.981.0050 F + 1.732.981.0058 www.daq.net

EDGE Logging


2

TABLE OF CONTENTS 1.0 EDGE LOGGING ..................................................................................................... 3

1.1 LOGGER INTERFACES .......................................................................................... 3

1.2 CATEGORY CODES .............................................................................................. 4

1.3 CONFIGURATION CONCEPTS .................................................................................. 5 1.3.1 NVRAM LOG ............................................................................................................... 5 1.3.2 RAM LOG .................................................................................................................. 6 1.3.3 PC SERVER LOGS ......................................................................................................... 7 1.3.4 SYSLOG RFC5452 AND CEF LOGS ..................................................................................... 8 1.3.5 USB LOG ................................................................................................................... 9 1.3.6 USB FILE SYSTEM ...................................................................................................... 10 1.3.7 EVENT RECORDING TO LOGGER ..................................................................................... 11 1.3.8 PILOT LOGIC LOGGING ................................................................................................ 13

1.4 APPENDIX A: LOGGING COMMANDS......................................................................... 19

EDGE Logging


3

1.0 EDGE LOGGING

The logging capabilities of the EDGE have been expanded to include several logger interfaces and the

ability for users to define messages that record to given logs. The loggers can record system event and

debug messages as well as messages from specific applications, such as the Event Recorder and Pilot

logic.

1.1 LOGGER INTERFACES

The available logger interfaces are:

Interface User Configurable Persist Through Reboot Non-volatile Memory (NVRAM) NO YES Memory (RAM) NO YES but not power loss USB files YES NO log files are retained to USB but

logger does not remain active through reboot*

PC serial or Ethernet Servers (output to Calterm2)

YES NO*

Syslog RFC5424 or Comment Event Format Ethernet Servers (Syslog/CEF)

YES YES

*If logging is configured in Event Recorder or Pilot configuration, it will start on reboot.

EDGE Logging


4

1.2 CATEGORY CODES

All messages are assigned category codes which allow the user to filter which categories a given logger

will receive. These message categories are:

Code Literal String Purpose

0 Freeform, can be anything

1 Communications Statistics

2 Control

3 Time Report

4 Polling Status

5 Flagged Freeform, can be anything

6 Setpoint

7 Error

8 Internal Only

9 External Only

10 Critical

11 Debug

12 Informational Only

13

14 Control Error to Client

15 Control Error to RTU

16 Control Internal Error

17 Control RTU Reply Error

18 Control RTU ID Error

19 Control Timeout

20 event Event Server

21 pilot1 Pilot Logic Program 1




*not all categories are implemented at this time.

EDGE Logging


5

1.3 CONFIGURATION CONCEPTS

For a logger to start reporting, it must be defined and configured to report the desired message

categories. The NVRAM and RAM loggers are exceptions to this, as they are automatically enabled

during boot and have no user definable parameters. Messages from certain applications such as the

Event Recorder and Pilot logic require logging to be enabled in the application in order for the

application to send messages to a logger. Some loggers have the ability to persist through a reboot or

power loss, others do not. Loggers are primarily defined and configured through the Calterm console

interface. Pilot logic and Event Recorder have provisions to automatically set up certain loggers.

When a logger is defined, the user will be prompted to enter up to four accept codes that correspond

to the message category codes listed in section 1.2 above. When accept codes are entered, only

messages in these categories will be displayed by the logger. If no accept codes are entered, the user

will be prompted to enter up to 4 reject codes. Reject codes will display all message categories except

for the codes entered. If no accept or reject codes are entered, all message categories will be

displayed.

1.3.1 NVRAM LOG

The NVRAM log is stored in the battery-backed, non-volatile RAM that is preserved across power cycles.

It can only store approximately 100 log records. This logger is created automatically at boot up and

only contains critical information. This logger has no definable user options.

Console Command: Command Description: ReadNVRAM Displays all message entries in console window. Entries are not deleted

when read.

EDGE Logging


6

1.3.2 RAM LOG

The RAM log is created automatically at boot up in a RAM region that is not erased during program

loading. This means the RAM log is preserved across reboots, but is lost when power is lost. The RAM

log can contain approximately 3,000 records. Such a large log requires some special commands to

display it conveniently.

At boot up, a read marker that identifies the next record to be read is placed at the first record logged

after boot up.

Console Command: Command Description: Example: Next Display the record at the read marker ReadAll Display all records from the read marker to the most recent

record

GoToOldest Move read marker to oldest record GoToTime yyyy-mm-ddThh:mm:ss

Move read marker to record at time specified

GoBackNRecords X Move read marker back X records ReadNMostRecent X Which displays the X most recent records, regardless of the

current read marker

Remove <All | Read> Permanently remove all or just previously displayed records ResetRamLog Permanently remove all records, equivalent to Remove All

Like all commands that display records, Next and ReadAll move the read marker one message past the

last record displayed.

Records in the log prior to boot up (from a previous boot up) and previously displayed records are still

available to be read, but only if the read marker is repositioned.

EDGE Logging


7

1.3.3 PC SERVER LOGS

One or more PC servers to receive log messages can be created on unused serial or IP ports. The server

will act very much like the system console PC server defined in CallistoView, except the logging PC

server will receive and display logging messages as they are created.

Console Command: Command Description: Example: PCLogger portNumber start

Creates or reconfigures PC logger where portNumber is the name of one of the serial ports, “com1”, “com2”, “com3”, or “com4”, or an IP port number between 1 and 65535. The user is subsequently given the opportunity to enter message codes to accept or reject.

pclogger com1 start pclogger 54123 start

PCLogger portNumber stop

Disables PClogger pclogger com1 stop pclogger 54123 stop

PCLogger portNumber status

Displays current status and configuration of PClogger pclogger com1 status pclogger 54123 status

EDGE Logging


8

1.3.4 SYSLOG RFC5452 AND CEF LOGS

The Syslog RFC5452 and CEF logs are sent to a remote client over the Ethernet. They must be

configured by the shell commands:

Console Command: Command Description: Example: SyslogLogger xx.xx.xx.xx:yyyyy start

Creates or reconfigures a Syslog logger where xx.xx.xx.xx is the remote client’s IP address, and the optional yyyyy is the remote client’s port number. If :yyyyy is omitted, the default port 1470 is used.

SyslogLogger 192.168.1.100:1470 start

SyslogLogger xx.xx.xx.xx:yyyyy stop

Stops existing sysloglogger from reporting SyslogLogger 192.168.1.100:1470 stop

Sysloglogger status or Sysloglogger

Displays current status of Sysloglogger Sysloglogger status

CEFLogger xx.xx.xx.xx:yyyyy start

Creates or reconfigures a CEFlogger where xx.xx.xx.xx is the remote client’s IP address, and the optional yyyyy is the remote client’s port number. If :yyyyy is omitted, the default port 1470 is used.

CEFLogger 192.168.1.100:1470 start

CEFLogger xx.xx.xx.xx:yyyyy stop

Stops existing CEFLogger from reporting CEFLogger 192.168.1.100:1470 stop

CEFLogger status or CEFLogger

Displays current status of CEFLogger

The CEF and Syslog logger configurations are persistent and will be used at the next power up or boot

up to create a server. If logging was previously terminated by turning the server off, it will still be off

when power is restored. If a remote client goes off-line or the connection is otherwise broken during a

logging session, the server will periodically attempt to reconnect. Only one Syslog and one CEF server

can exist.

EDGE Logging


9

1.3.5 USB LOG

The USB logger will record log messages to files on a USB drive. These log files can be displayed

through the console interface or by removing the drive and using a computer to read the files. Multiple

USB loggers can be created at the same time, writing to different files on the USB drive.

The USB logger does not persist through reboot; it must be restarted after every boot. Applications

such as Pilot and Event Recorder can automatically start the USB logger according to the configuration.

The maximum supported USB drive size is 2 gigabytes. Larger drives may not work correctly.

Console Command: Command Description: Example: UsbLogger filename start Create and Start or reconfigure USBlogger USBlogger logfile.log start UsbLogger filename stop Stop USBlogger logging USBlogger logfile.log stop

When a USBlogger is created, all messages currently in the RAM log are written to the USB drive. To

prevent this from happening, use the command ResetRamLog before creating the USBlogger.

To start logging to the USB memory stick, the command UsbLogger filename start must be issued

where filename is the base name of the file on the USB stick to hold the log. The base name can have 1

to 7 characters, plus an optional period followed by a 1 to 3 character extension (standard DOS name,

except limited to 7 instead of eight characters). A path with subdirectories can be included provided

the path plus name is less than 64 characters. For example, the command usblogger \logs\logfile.log

start will start a USB logger writing to logfile.log in the \log folder of the USB drive.

The USB logger actually saves the log as a set of multiple files. The files have the names filenameA to

filenameZ, filename0 to filename9, that is, the entered file name with a one character suffix of the

letters A-Z or numbers 0-9. This gives a total of 36 possible files. For this scheme, a more readable set

of file names is produced if the entered file name ends with an underscore, e.g., log_.txt. This

example file name could generate the 36 files: log_A.txt, log_B.txt,…log_Z.txt, log_0.txt,…log_9.txt.

The size of each file is determined dynamically by dividing the available space on the USB memory

stick by the number of USB loggers times four. In other words, each logger is allocated space for four

files of reasonable size. A logger is limited to four files, however, only when the USB memory stick

becomes full. It is free to produce up to 36 files if space permits. This allows active loggers to consume

a lot of USB memory, while loggers with little activity do not take up space they are not using; but

EDGE Logging


10

when the memory stick gets full, all log file sets are truncated to a maximum of four files. This lets

loggers that start logging late or log in bursts to get space when they need.

As an example, if a memory stick has 2 GB, and there are 5 USB loggers (say loggers for the 4 pilot

programs and the event recorder), then the file size would be 2 GB / (5 * 4) or 100 MB. Each logger is

guaranteed 400 MB if it needs it, but a single logger could use up to 36 * 100 MB, which of course would

be limited to the 2 GB stick size. Once the stick is full, files will be deleted from all loggers until each

has at most 4 files. If the stick is still full after all loggers have at most four files, a logger’s oldest file

will be overwritten when that logger logs new messages. Note that the file name suffixes are used in a

circular fashion, and can be randomized, so do not indicate the time order of file creation (suffix Z

may be used before or after suffix A).

1.3.6 USB FILE SYSTEM

EDGE is configured as a USB host and can only be used with a USB flash drive. The flash drive is

organized as a single FAT file system volume, so it appears as a disk to EDGE containing one or more

directories and files. Using the FAT file system allows the memory stick to also be accessed by a

Windows PC for easy file exchange with EDGE. Names in the USB file system are restricted to eight

characters plus an optional period followed by a three-character file type.

The files on the stick may be accessed using shell command to the EDGE PC Server below.

Console Command: Command Description: Example:

UsbDir Displays the drive directory Usbdir

UsbDeleteFile filename

Deletes a file Usbdeletefile event.txt

UsbDeleteAllFiles Deletes all files usbdeleteallfiles

UsbGetFile filename Sends the file’s contents to the PC Server port (see following section)

Usbgetfile event.txt

UsbDisconnect Allows for safe removal of USB drive. Disables all loggers and flushes all pending writes to the drive.

UsbDisconnect

EDGE Logging


11

A file can be uploaded with CalTerm2 using the Up Load File item from the File pull down menu. Select

the “Size from 1st 16-bits”, “Ascii SOH (0x01) plus 2 bytes for file size” and “Checksum Byte after file”

options. The Up Load file dialog should appear with the USB file name entered in “File Name”, and the

filename on the PC file entered in “Save to File”. The “Upload Command” should contain “UsbGetFile

filename” where filename is the name of the USB file.

Files can also be uploaded for display on CalTerm2 by entering the shell command “UsbGetFile

filename”. Be aware that the display will include some added data such as a checksum that are not

actually in the file; using the Upload file menu item removes this extra data.

There are two ways to remove a USB memory stick from an EDGE. The safer way is to issue the

command: UsbDisconnect.

The second method is simply to remove the stick. There is a small chance of log file corruption, which

may make the file or possibly the entire stick unreadable. Regardless of the method of removing the

stick, logging of all USB logs is restarted automatically when that stick, or another stick is inserted.

1.3.7 EVENT RECORDING TO LOGGER

Events defined in the Event Recorder application can be recorded to any logger. The enable logging

check box must be checked for events to be written to all logger types (on General tab of Event

Recorder). If a name is not entered in the USB File name field, a USB logger is not automatically

created. The Log SOE to file checkbox on the SOE tab of the Event Recorder must be checked off for

each point that the user wishes to be logged.

EDGE Logging


12

Event recorder logging to USB drive

This guide provides instruction on configuring the Event Recorder to log events to a USB drive on the

EDGE platform.

1. Create your EDGE configuration and setup the client status and SOE points.

2. Add Event Recorder to the node configuration.

3. On the SOE tab, choose points from the “Available points” window and add them to the

“Descriptive points” window. Choose on and off state labels. Check off From SOE or From

Status depending on whether the point is a time tagged SOE point. Check off Log SOE to file to

record the point to the logger.

EDGE Logging


13

4. On the General tab, in the USB logging section, check off Enable logging. Enter a file name in

the Filename field. Note: the enable logging check box must be checked for events to be

recorded to any logger. If a name is not entered in the USB File name field, a USB logger is not

automatically created.

5. After the configuration is downloaded, and events have occurred, the EDGE will create the log

file and write to it. Use the “usbdir” command to list the files on the USB drive.

Use the “usbgetfile filename” command to view the contents of a file through the Calterm

console. The files can also be read by removing the USB drive and connecting it to a PC.

1.3.8 PILOT LOGIC LOGGING

Pilot logic now has the ability to create log entries as functions within logic operate. The user can use

this information to assist with debugging or historical event analysis. Pilot has the ability to use any of

the user configurable loggers on the EDGE. These can be setup in the Pilot configuration or by

commands in the Calterm console interface.

In order to accomplish this, the user must first define function names within their Pilot logic

application. Then create/configure a logger to accept messages from categories 21-24. These category

codes correspond with the four possible logic programs that can be run on a node. Next the Pilot

logging must be turned on, allowing Pilot to record entries to the configured loggers. Alternatively, the

user can set up Pilot logging within the Pilot logic application to automatically enable logging on boot

up.

EDGE Logging


14

Setting up the Pilot logic program to create logger entries:

Within Pilot logic, each function block (both user created and built in) can be assigned a name. When

the output of a named function changes its output state is written to the configured logger.

1. To assign a name to a function block, select the function block, right click and select Name

from the Edit submenu.

2. A dialog will appear, enter the function name and click OK.

3. A text label will appear above the function block.

EDGE Logging


15

As many functions as are needed can be named and logged. Once you have named all of the interesting

functions, there are two options for enabling the loggers. Pilot logic can be configured to automatically

start the appropriate logger. Alternatively, the logger(s) can be started through the console interface.

To setup the logger in Pilot logic:

1. In the “Logic Project” tree on the left side of the pilot window, double click on Main

Program under the Programs branch.

2. The Program Properties dialog will appear. Choose the Execution tab.

EDGE Logging


16

3. From this dialog, choose the Logger options to be automatically started. These options

must be set individually for each Pilot program that is in the configuration.

Enable USB Logging at startup Automatically starts the USB logger on startup.

Pilot log entries are written to files named

Pilot_X.log where X is consecutive letters.

Enable Syslog logging Automatically starts logging to a syslog client at

the specified IP address. The default port of

1470 is used.

Enable PC server logging at startup Automatically starts logging to the specified

EDGE serial port or through the Ethernet

interface at the configured port number. This

option is designed to work with Calterm2.

Enable CEF logging Automatically starts logging to a CEF client at

the specified IP address. The default port of

1470 is used.

4. When the appropriate logger(s) have been configured, save and download the

configuration. When the EDGE boots the configured logger(s) will automatically start.

EDGE Logging


17

The alternate method for enabling Pilot loggers is to use console commands.

There are a number of commands specific to Pilot to accomplish this:

Console Command Description Parameters Parameter description PLOGUSB [On/Off] Controls USB logging [On/Off] On – turns on USB logging

Off – turns off USB logging PLOGSYSLOG [IP Address] [On/Off]

Controls Syslog external servers

[IP Address] [On/Off]

On – turns on external logging Off – turns off external logging IP Address – xx.xx.xx.xx:yyyy ex: 10.10.64.42:1470

PLOGCEFLOG [IP Address] [On/Off]

Controls Syslog external servers

[IP Address] [On/Off]

On – turns on external logging Off – turns off external logging IP Address – xx.xx.xx.xx:yyyy ex: 10.10.64.42:1470

PLOGPCSERVER [Com/Port] [On/Off]

Controls PC Server logging

[Com/Port] [On/Off]

Com/Port – specifies a com port or TCP port number for PC Server over Ethernet. Ex: com1, com2, com3, com4, 2000 On – turns on pc server Off – tuns off pc server

PLOGOFF Turns off all configured logging

None None

PLOGRATE [time] Allows Pilot to run logging in a particular execution rate

[Time] [Time] 1 – 10x the execution rate 2 – 100x the execution rate 3 – 1000x the execution rate

PLOGPROGRAM [Number] [On/Off]

Allows a program logging to be turned on or off

[Number] [On/Off]

- [Number] – program number running on logic first program starting at 1. Refers to the list in CallistoView.

- [On/Off] – turns on off logging for the specified number

PLOGALL Turns on all programs to log

None N/A

PLOGSTATUS Displays which logging functionality is on

None N/A

EDGE Logging


18

Setting up the Pilot loggers through Calterm console:

1. In the Pilot program name to functions of interest. Save and download the configuration.

2. Enter the command to start and enable to appropriate logger

PC Server logging use PLOGPCSERVER Depending on the option used, a serial or IP PC server

logger will be created and filtered to category codes

21-24. Pilot PC server logging will be enabled for all

four programs.

CEF logging use PLOGCEFLOG A CEF logger will be created and filtered to category

codes 21-24. Pilot PC server logging will be enabled for

all four programs.

Syslog logging use PLOGSYSLOG A SYSLOG logger will be created and filtered to

category codes 21-24. Pilot PC server logging will be

enabled for all four programs.

USB logging use PLOGUSB A SYSLOG logger will be created and filtered to

category codes 21-24. Pilot PC server logging will be

enabled for all four programs. The logger will use

pilot_X.log for the filename.

For example:

Once the configuration with named function blocks has been downloaded, open Calterm to

access the console. Enter the command plogceflog 10.10.65.123:1470 on to create a CEFlogger

that will report to a client on 10.10.65.123:1470.

Each time the EDGE is rebooted the command must be issued for logging to continue.

PLOGALL, PLOGOFF and PLOGPROGRAM commands can be used to enable pilot reporting

without affecting the configured loggers. The status of pilot logger reporting can be seen using

PLOGSTATUS command.

EDGE Logging


19

1.4 APPENDIX A: LOGGING COMMANDS

Log Type ID Example Action

PCLogger Com1, com2, com3, com4 or IP port number between 1 and 65535

PCLogger PCLogger com1 PCLogger com1 status PCLogger 54123 start PCLogger com2 stop

Show status of all PC Loggers Show status of logger on com1 Show status of logger on com1 Start PC Server on IP port 54123 Stop PC Server logging on com2

USBLogger File name including path

USBLogger USBLogger \dir\mf.txt USBLogger m1 status USBLogger log_.txt start USBLogger log_.txt stop

Show status of all USB Loggers Show status of logger for file \dir\mf.txt Show status of USB logger for file m1 Start USB logging to file log_.txt Stop USB logging to file log_.txt

SyslogLogger IP address including port

SyslogLogger SyslogLogger 10.10.65.13:1470 SyslogLogger 10.10.65.13 status SyslogLogger 10.10.65.13 start SyslogLogger 10.10.65.13 stop

Show status of all Syslog loggers Show status of Syslog logger Show status of Syslog logger Start Syslog logger Stop Syslog logger (see note below)

CEFLogger IP address including port

CEFLogger CEFLogger 10.10.65.13:1470 CEFLogger 10.10.65.13 status CEFLogger 10.10.65.13 start CEFLogger 10.10.65.13 stop

Show status of all CEF loggers Show status of CEF logger Show status of CEF logger Start CEF logger Stop CEF logger (see note below)

DAQ Electronics, LLC 262B Old New Brunswick RoadPiscataway, NJ 08854 USA

T+ 1.732.981.0050F+ 1.732.981.0058

www.daq.net

edge logging - daq electronics edge logging.pdf · 1.0 edge logging ... usblogger filename start...

Documents