LHC Logging DB User Documentation -...

LHC Project Document No.

LHC-UNICOS

CERN Div./Group or Supplier/Contractor Document No.

BE/ICS

EDMS Document No.

1726744

Date: 2016-10-20

the

Large Hadron Collider project

CERN CH-1211 Geneva 23 Switzerland

USER DOCUMENTATION

UNICOS LHC LOGGING DB

Abstract

This document describes the unLHCLoggingDB component:

General description

User interface & Libraries

Common use cases and procedures

Errors and warnings explained

Prepared by:

Riku-Pekka Silvola (BE/ICS/SDS)

Checked by:

Approved by:

LHC Project Document No. 1726744

LHC-UNICOS

of 37

History of Changes

Rev. No. Date Pages Description of Changes

1.0 20-Oct-2016 37 First version


LHC-UNICOS

of 37

Table of Contents

1. Introduction ............................................................................................ 5

1.1 Purpose of This Document ........................................................................ 5

1.2 Definitions, Acronyms and Abbreviations .................................................... 5

2. DESCRIPTION .......................................................................................... 5

3. IMPORT FILE FORMAT ............................................................................. 6

3.1 TEXT IMPORT FILES ................................................................................. 6

3.2 XML IMPORT FILES .................................................................................. 7

4. USER INTERFACE ..................................................................................... 8

4.1 SETUP .................................................................................................... 8

4.2 LOGGING CONFIGURATION ....................................................................... 9

4.2.1 MANAGE CONFIGURATIONS ................................................................................. 9 4.2.2 GENERATE IMPORT FILES ................................................................................... 11 4.2.3 IMPORT LOGGING CONFIGURATION .................................................................... 13 4.2.4 DATA CONSISTENCY CHECK ............................................................................... 14 4.2.5 DELETE LOGGING CONFIGURATION .................................................................... 16

4.3 DIAGNOSTICS ....................................................................................... 17 4.3.1 SIGNAL OVERVIEW ............................................................................................ 17 4.3.2 TRANSFER HISTORY .......................................................................................... 18 4.3.3 TRANSFER JOB MONITORING .............................................................................. 19

4.4 SYSTEM INTEGRITY ............................................................................... 21

4.4.1 CONFIGURATION ............................................................................................... 21 4.4.2 DIAGNOSTICS .................................................................................................. 23

5. Common Use Cases and Procedures ...................................................... 24

5.1 HOW TO MODIFY LOGGING CONFIGURATION ............................................ 24 5.1.1 REGISTERING NEW SIGNALS FOR LOGGING ......................................................... 25 5.1.2 UNREGISTERING SIGNALS FROM LOGGING .......................................................... 25 5.1.3 DELETING HIERARCHIES .................................................................................... 25 5.1.4 RENAMING SIGNALS .......................................................................................... 26 5.1.5 RECONNECTING SIGNALS .................................................................................. 27

5.2 INTRODUCING AND MODIFYING THE USER FUNCTION ............................... 27

5.3 HOW TO CHECK IF LOGGING CONFIGURATION IS UP TO DATE ................... 27

5.4 HOW TO REQUEST A RETRANSFER ........................................................... 28

6. Understanding errors and warnings ...................................................... 29

6.1 SYSTEM INTEGRITY ............................................................................... 29 6.1.1 TRANSFER JOBS ................................................................................................ 29 6.1.2 TEST DATA POINTS ........................................................................................... 29 6.1.3 DATA CONSISTENCY .......................................................................................... 30 6.1.4 FULL CONSISTENCY ........................................................................................... 31

6.2 WARNINGS ........................................................................................... 32 6.2.1 REPLACED CHARACTERS .................................................................................... 32 6.2.2 RECONNECTED SIGNAL ...................................................................................... 32 6.2.3 RENAMED SIGNAL ............................................................................................. 32

6.3 ERRORS ............................................................................................... 32 6.3.1 INVALID CHARACTERS ....................................................................................... 32 6.3.2 SIGNAL NAME ................................................................................................... 33


LHC-UNICOS

of 37

6.3.3 HIERARCHY ...................................................................................................... 33 6.3.4 ARCHIVE .......................................................................................................... 34 6.3.5 PARSING .......................................................................................................... 34 6.3.6 DATAPOINT ...................................................................................................... 34 6.3.7 DATA CATEGORY ............................................................................................... 35

6.4 POP-UPS ............................................................................................... 35

REFERENCES & USEFUL LINKS ...................................................................... 37


LHC-UNICOS

of 37

1. Introduction

1.1 Purpose of This Document

User documentation of the UNICOS LHC LOGGING DB component.

1.2 Definitions, Acronyms and Abbreviations

WinCC OA: WinCC Open Architecture, previously PVSS

UNICOS: UNified Industrial COntrol System.

DS: UNICOS Data Server, a computer running a WinCC OA project

OWS: UNICOS Operator WorkStation, a computer running a PVSS UI.

Application: set of DS and WinCC OA projects.

DP: WinCC OA data point.

DPT: WinCC OA data point type.

DPE: WinCC OA data point element.

API: Application Programming Interface.

DB: Data Base

RDB Archive: WinCC OA value archive for high performance data storage

LDB: Central Logging Data Base of CERN

2. DESCRIPTION

The UNICOS LHC Logging DB component is a configuration and monitoring tool, which

is used to setup data transfer from RDB Archive to the central logging database (LDB).

Data is being transferred by database transfer jobs directly, so no additional API-

Manager (as in the previous logging solution) is needed.

In order to configure and monitor data transfer from RDB-Archive to LDB the LHC

Logging DB component needs to have a permanent database connection. Concretely it

has to be connected to the database schema RDB2LHC of the dedicated database

server.

The LHC Logging DB component heavily depends on CtrlRDBAccess (for database

access) and RDB Archiver (for pushing data to RDB Archive).

The LHC Logging DB component is composed of:

WinCC OA panels to set up and monitor data transfer

WinCC OA scripts used during installation and for system integrity checking

WinCC OA libraries containing shared functions used during run-time.


LHC-UNICOS

of 37

3. IMPORT FILE FORMAT

LHC Logging DB import files contain information that is necessary to register a set of

signals or data points for logging.

They include the following fields:

Name: Name of the signal in LDB, internally called VARIABLE_NAME

DPE: Name of the DP Element, internally resolved to ELEMENT_ID

Alias: Name of the DP Alias, internally resolved to ELEMENT_ID

Description: Description of the signal

Hierarchy: Hierarchy of the signal in LDB

DPE and Alias can be specified in different ways:

DPE only: Full data point element name

Alias only: Alias of the data point element

Alias+DPE: Alias of the data point + element extension

Important note:

Names must not exceed 50 characters

Hierarchies must not exceed 255 characters

Description must not exceed 259 characters

Attribute texts should not contain any special characters,

stick to ASCII encoding to avoid automatic replacements

Other metadata that is needed for logging configuration (e.g.: RDB_SOURCE, OWNER)

is automatically extracted from the WinCC OA project, so there is no need to put this

information into the import file.

3.1 TEXT IMPORT FILES

Text import files have been introduced to preserve backward compatibility to the old

LHC Logging solution, so that import files from old logging can still be used to

configure LHC Logging DB.

[_RDBArchive]

dpe= _unSystemAlarm_DS_Comm__unPlc_CFP_2865_FSSF8.alarm

alias=

name= CFP_2865_FSSF8:COMMUNICATION

description= Communication CFP_2865_FSSF8 to DS driver

hierarchy=<node name="CRYO"><node name="DIST"></node></node>

format=

dpe=ProcessInput.evStsReg02

alias=TEST_DEV_1

name=TEST_DEV_1.evStsReg02

description=SU8 COOLING PLANT

hierarchy=<node name="CRYO"><node name="DIST"></node></node>

format=

LHC-UNICOS

of 37

Since there is only one RDB Archive the archive tag [_RDBArchive] has no meaning

any more, but it still has to be present in the file. Also the attribute “format” is being

ignored but it still has to be specified without any value. If an attribute is not being

used, it still has to be present with an empty value.

Important note:

Text import file format is deprecated in favor of XML import file format

It will not receive any new features

Support for it will be eventually fully removed

3.2 XML IMPORT FILES

XML import files contain the same information as text import files, but the information

is structured in a different way. One advantage of the XML import files is that all

information of a signal can be displayed in a single line. It is also possible to add xml

comments () to the file or to comment out specific signals, that need to be

ignored during import.

<?xml version="1.0" encoding="ISO 8859-1" ?>

<configFile version="1" application="unLHCLoggingDB">

<configData group="default">

<signal name="" dpe="" alias="" description="" hierarchy="" />

<signal name="" dpe="" alias="" description="" hierarchy="" />

…

…

</configData>

</configFile>

When using XML import files the representation of hierarchies is different. The name of

each node is being displayed using the delimiter “/”.

E.g.: hierarchy="CRYO/DIST"


LHC-UNICOS

of 37

4. USER INTERFACE

The LHC Logging DB user interface contains panels to setup, configure and monitor

data transfer to LDB. From the UNICOS main panel LHC Logging DB can be accessed via (1.) UNICOS buttonConfigurationLHCLoggingDB as shown in below figure.

Note that the menu entry for LHC Logging DB might not be the first one on the menu.

Figure 1: LHC Logging DB menu

4.1 SETUP

Setting up LHC Logging is a complex operation that requires actions from three

departments. Please contact [email protected] well in advance as the steps

to be followed will take at the very least a few days.

Before a project can be used it has to be ensured that:

A schema has been created for the project in RDB

RDB Archiving is installed an properly set up

unLHCLoggingDB is installed and properly set up

Data Categories for the project have been created

Logging Users for the project has been created and configured

Data Category Mappings have been created

For more details see Procedure to letup RDB Archiving and LHC Logging DB.

mailto:[email protected]

https://wikis.web.cern.ch/wikis/display/EN/WinCC+OA+Oracle+Archiving+for+SAS


LHC-UNICOS

of 37

4.2 LOGGING CONFIGURATION

The LHC Logging DB component provides a set of panels and tools for logging

configuration. The following chapters will explain how and when to use them.

4.2.1 MANAGE CONFIGURATIONS

The concept of configurations has been introduced to define the content of an import

file on a higher level of abstraction. It allows to specify certain rules, which can later

be used to generate import files in a reproducible way.

Figure 2: Manage configurations

A project can have multiple configurations (e.g.: one production configuration and

some test configurations or many production configurations, where each configuration

represents a different application within the project)

If there is no configuration entry, click button (1. On the figure) to create one.


LHC-UNICOS

of 37

A configuration contains the following settings:

2. Configuration: A unique name to identify the configuration (no spaces). The

name of an already existing configuration cannot be modified.

3. Import file: Name of the import file that belongs to this configuration.

It is necessary to manually add the .xml extension if it is an xml file.

4. Usage: To indicate the purpose of the configuration: ‘production’ or ‘test’.

Test configurations will not be automatically checked for consistency.

5. Manually maintained: Used to disable the use of a user function. A manually

maintained configuration must be maintained by hand and cannot be

automatically generated with a user function.

6. File format: Format of the import files that are being created by the user

function. (‘text’ or in ‘xml’)

7. User function: If users want to use the import file generator, they need to

specify the name of the “user function”, which forms the ‘name’ and ‘hierarchy’

from full data point element name. The existence of this function can be

checked using the check button (8.) to the left of the form field. More details

on the definition of the user function can be seen below.

9. Data retrieval: To specify if internal data points, that is data points starting

with an underscore, should be included or not

10. Reduction: Include devices, system alarm and other data points. Other

data points include any and all data points that are not devices or system

alarms.

11. Naming: Specify data points as ALIAS+Extension or force DPE usage.

12. Filter patterns: To only include DPEs which fit into specific pattern

Note: If the built-in import file generator is used, a user-function with the following

signature needs to be provided and the containing library needs to be included in the

project’s configuration file (sections [ui] and [ctrl])

/**

@param sFullDpeName input, Full data point element name

@param sName output, Signal name

@param sDescription output, Description

@param sHierarchy output, Activity/Location/Appl./Nature/Domain

@param sDpAlias output, DP Alias

@param sDpeExtension output, element extension

*/

public void THE_NAME_OF_THE_USER_FUNCTION (

string sFullDpeName,

string &sName,

string &sDescription,

string &sHierarchy,

string &sDpAlias,

string &sDpeExtension)

{

...

}


LHC-UNICOS

of 37

Note: Set sHierarchy to “ERROR” if the function cannot retrieve the output

information. Set it to “IGNORE” if a certain type of signals should be explicitly ignored

(e.g. where description matches SPARE or RESERVE)

Note: If the built-in import file generator is not used because the user can provide the

import files in a different way, a manually maintained configuration should still be

created for each import file. Configurations help to keep track of the import files and

they also allow to make use of some nice features concerning consistency checking.


LHC-UNICOS

of 37

4.2.2 GENERATE IMPORT FILES

Note: Generating an import file will overwrite the existing import file specified. Always

make a backup before generation.

Import files can be generated with the Generate panel, which provides following

functionality:

Generate an import file by retrieving data, marking signals for logging (all

except ignored) and saving the result as a file.

Retrieve data from RDB and display signals that match the criteria given by

the specified configuration by clicking the “Refresh” button.

o Signals with hierarchy “ERROR” will be highlighted in red, which is

useful for debugging the user function.

o Signals with hierarchy “IGNORE” will be highlighted in grey, which

indicates that they will be not included in the import file.

o The info-column will provide useful information about invalid characters

and character replacements being in column ‘description’. This column I

not visible on the screenshot below, but can be seen by scrolling to the

right in the panel.

Mark signals for logging: ‘Mark all’, ‘Mark visible’ or ‘Mark from DB’ buttons will

select the signals to be included in the import file. They will not select signals

that are ignored.

Save will create an import file containing all marked signals overwriting the

existing file. Please be sure to always make a backup.

Figure 3: Generate Import File


LHC-UNICOS

of 37

The labels ‘Marked’ , ‘Ignored’, ‘Infos’ and ‘Errors’ provide useful metrics about the

state of the import file, that is going to be created.

Note: You may right click on any row and choose enable columns for full DPE name,

alias and DPE extension, which can help when debugging errors.

4.2.3 IMPORT LOGGING CONFIGURATION

The import panel is used to append and modify signals to the central logging

configuration in the database. Operators need to authenticate with a dedicated

username and password to be allowed to change the logging configuration.

New signals are stored in import files, which are held by configurations. After choosing

a configuration for import, the name of its import file is shown in the text box above.

Before an import file can be appended to the central configuration on DB it needs to

be checked for errors. The check reports on name clashes, duplicated entries,

forbidden characters, and data points that do not exist on the project or that have

mismatching aliases and data point elements specified.

Please see chapter 5.2 for conflict types and their resolutions.

Figure 4: Import Logging Configuration

Note: Invalid characters in attribute Description will be replaced according to a

substitution list. If a character is not present in the list or in the whitelist, it will be


LHC-UNICOS

of 37

completely removed. For the substitution table see 6.2.1 REPLACED CHARACTERS. For

the whitelist see 6.3.1 Invalid Characters.

Note: When appending signals that are already registered for logging their metadata

(DPE, description, and data category) will be updated on the central logging

configuration but the changes will not be propagated to LDB. When appending a

signals having different hierarchies, the old hierarchies will remain and must be

deleted manually.

4.2.4 DATA CONSISTENCY CHECK

The data consistency check panel was designed to compare logging configuration in

DB with logging configuration in one or many import files.

Figure 5: Data Consistency Check

By default all production configurations will be marked for checking, but the user can

also mark test configurations to simulate changes that would result from importing

certain files.

If checkbox ‘Generate files’ is enabled, temporary import files will be generated for all

marked configurations and to be used for the comparison. This option only makes

sense, if the configuration is using a user function to generate the file. If the check

box is not checked, only the signals that are specified in the import file will be checked

for consistency.


LHC-UNICOS

of 37

Hint: Make sure that the library containing the user function for import file generation

has been added to the projects config file in sections [ui] and [ctrl] otherwise option

‘Generate files’ will not work.

Note: The panel is only used to trigger the integrity check and display the result in the

table. The actual check is being executed in the system integrity control manager

(usually manager number 41)


LHC-UNICOS

of 37

4.2.5 DELETE LOGGING CONFIGURATION

In some cases it is necessary to delete signals or hierarchies from the logging

configuration on the database of a specific project. Deletion of signals or hierarchies

will not be propagated to LDB.

Note: Deletion of signals or hierarchies only marks them deprecated. To delete or

obsolete signals or hierarchies in LDB, you must contact [email protected].

When does deletion of signals or hierarchies make sense?

Delete signals and hierarchies, if the new configuration contains fewer signals

than the previous one to preserve data consistency.

Delete signals and hierarchies, if the new configuration contains renamed

signals and there is no need to keep continuous history

Delete only hierarchies, if there are multiple hierarchies for the same signal

(note that this will not be propagated to hierarchies on LDB).

Figure 6: Delete Logging Configuration



LHC-UNICOS

of 37

4.3 DIAGNOSTICS

4.3.1 SIGNAL OVERVIEW

The signal overview panel provides information about all signals, which are registered

for logging in a certain database schema. This panel is accessible from the Import

panel by clicking the View Signals… button.

By default the database schema of the current project will be selected, but since

multiple schemas share the same database it is also possible to view signals from

other systems or to connect to another database and view the schemas and signals

registered there.

Figure 7: Signal Overview

Columns shown by default:

Signal Name: Name of the signal in LDB

Data Category: Category that was chosen before import

Logging Required: Indicates, if signal should be logged

Registered for Logging: Indicates, if signal has been picked up by transfer job

Transfer Group: Id of the dedicated transfer job

Records Logged: Number of records transferred to logging during last 5 min.

The number of records that can be considered normal depends on the signals

frequency.

Time Logged: Time stamp of last value transferred to logging

Additional columns and options can be opened by right click on a signal in the table.


LHC-UNICOS

of 37

4.3.2 TRANSFER HISTORY

The transfer history panel provides a historical listing of data transfers to LDB for a

specific signal. The user can specify the time range, but beware of specifying a too

long range, because queries’ load on the database can be very heavy and can take a

considerably long time.

Table columns:

Time Created: Timestamp when data chunk was processed by the transfer job

First Checked: Timestamp of first value in the chunk

Last Checked: Timestamp of last value in the chunk

Last Logged: Timestamp of last value transferred to LDB

Records Checked: Number of records found between timestamps

Records Logged: Number of records transferred to logging

Figure 8: Transfer History

Note: The number of records checked and records logged can be different depending

on the timestamp of the Last Checked and Last Logged. Any discrepancies when the

load on the transfer jobs is normal and there are no system integrity manager

indicates a problem.


LHC-UNICOS

of 37

4.3.3 TRANSFER JOB MONITORING

The transfer job monitoring panel shows the current status of all transfer jobs.

Figure 9: Transfer Job Monitoring

Job Name: Name of the transfer job (trailing number is transfer group)

Job Enabled: Indicates whether the job is enabled

Job State: Current operation stage of the job. Most commonly SCHEDULED or

RUNNING. See next page for a table of possible states and their descriptions.

Last Start: Timestamp of the last job execution

Run Duration: How long did last job execution take. This depends on load and

amount of data that was transferred.

Next Run: Timestamp of the next job execution

Job Load: Ratio between run duration and job run interval. If load gets too big

the job doesn’t have time to finish before the next run should be started. It is

important to balance loads between jobs as equally as possible.

When selecting a certain transfer job in the table, details will be displayed below:

The left text box shows information about the actual work the transfer job is

doing. Possible entries are ‘collect data’, ‘log data’, ‘register variables’ or

‘register hierarchies’.

The right graphic shows historical load information of the selected job.

o Query time: How long did it take to query value changes

o Transfer time: How long did it take to transfer values to LDB

o Row count: How many values have been transferred to LDB


LHC-UNICOS

of 37

Table 1: Job States

Job State Description

DISABLED The job is disabled.

SCHEDULED The job is scheduled to be executed.

RUNNING The job is currently running.

COMPLETED The job has completed, and is not scheduled to run again.

STOPPED The job was scheduled to run once and was stopped while it was running.

BROKEN The job is broken.

FAILED The job was scheduled to run once and failed.

RETRY

SCHEDULED

The job has failed at least once and a retry has been scheduled to be

executed.

SUCCEEDED The job was scheduled to run once and completed successfully.


LHC-UNICOS

of 37

4.4 SYSTEM INTEGRITY

4.4.1 CONFIGURATION

System integrity checking for LHC Logging DB was designed to answer two questions:

Does the data transfer from RDB-Archive to LDB work properly?

Is the logging configuration still up to date?

Figure 10: System Integrity Configuration

There are five different integrity checks available to answer these questions:

Transfer Jobs: Checks, if transfer jobs are enabled and are being executed

within given time span. Threshold for delay is specified by setting ‘Max. age

jobs’

Test Datapoints: Creates a test signal to check the full logging chain.

(Increments value, stores it to RDB archive and transfers to logging)

Data Consistency: Checks, if every registered signal has an existing data point

with an archive config and checks if RDB_SOURCE matches ARCHIVE_GROUP.


LHC-UNICOS

of 37

Full Consistency: (optional) Regenerates temporary config files and compares

them with logging configuration in DB. Triggers an error if differences are

found. If built-in import file generator is not used, the check will use existing

import files for comparison. This check is only executed once a day and the

time can be specified using the setting ‘Start full check at’. The number here is

the time of day, as in 8h indicates 8 am, whereas 15h would indicate 3 pm.

The check can be started any time by clicking the button ‘Start Now’

The interval for running system integrity checks can be modified by changing the

setting ‘Run checks every ___ [s]’.

If a system integrity check fails an alarm will be triggered and shown in the system

integrity alert screen.

If the reason for the alarm is a mismatching logging configuration (‘Data Consistency’

or ‘Full Consistency’ check failed), the problem can be fixed by the operator by

updating the logging configuration in DB (e.g. generate and re-import config files).

If the reason for the alarm is a problem on database (‘Transfer Jobs’ or ‘Transfer

History’ check failed) it can only be treated by the LHCLoggingDB admin or acc-

logging-support.

Checks can be added to the list of ‘Activated LHCLoggingDB integrity classes’ by

selecting them from the list of ‘Available LHCLoggingDB integrity classes’ and then

adding them via the ‘arrow down’ button.

Checks can be removed from the list of ‘Activated LHCLoggingDB integrity classes’ by

selecting them from the list of ‘Activated LHCLoggingDB integrity’ classes and then

removing them via the ‘arrow up’ button.

Already added checks can be disabled by untagging the check box ‘Enabled’. Disabled

checks will not be executed and the alarm will be masked.

Note: System integrity checking for LHC Logging DB will be done by a dedicated

control manager. Usually this manager has the number 41.

Note: To be able to use system integrity checking for LHC Logging DB first set up

system integrity checking for RDB. Otherwise checks involving test data points will not

work.

Important note: When database load is very high it can happen that system integrity

alarms for database transfers jobs of LHC Logging DB flip to error state. Try to

increase settings ‘Max. age jobs’ and ‘Max age history’ to make checks less sensitive

to load peaks on database. Note that these tests are there for a reason, and should be

low enough to catch problems in the process. Certain applications can be quite

susceptible to this as they are both writing to and reading from LDB. For example PIC

can only accept maximum five minutes delay from value change to its availability in

LDB.


LHC-UNICOS

of 37

4.4.2 DIAGNOSTICS

The system integrity diagnostics panel shows the current status of all added system

integrity checks for LHC Logging DB.

Figure 11: System Integrity Diagnostics

To keep track of created test signals a list of test data points including the current

value and timestamp of the last value change is also shown in the second table.

Using the button ‘Data Consistency’ the operator can open the data consistency check

panel and run a consistency check for the specified system.

Hint: This panel can be opened from the main

UNICOS menu via (1.) UNICOS button

ManagementDiagnosticSystem integrity as

shown in figure to the right.

Note: The menu entry for System integrity

might not be in the same position in the

Management sub menu as in the figure.


LHC-UNICOS

of 37

5. Common Use Cases and Procedures

5.1 HOW TO SETUP LHC LOGGING DB

Setting up LHC Logging is a complex operation that require actions from three

departments. Please contact [email protected] well in advance as the steps

to be followed will take at the very least a few days.

Before a project can be used make sure that:

A schema has been created for the project in RDB

RDB Archiving is installed an properly set up

unLHCLoggingDB is installed and properly set up

Data Categories for the project have been created

Logging Users for the project have been created and configured

Data Category Mappings have been created

For more details see Procedure to setup RDB Archiving and LHC Logging DB.

5.1.1 GETTING USERNAME AND PASSWORD FOR IMPORT

To be allowed to modify the LHC Logging DB configuration you need to authenticate

with a dedicated username and password.

If you cannot find a suitable username in the list of proposed users or if you don’t

know the password, ask [email protected] for help (don’t forget to provide

the name of your project, machine and database schema).

5.1.2 SETTING UP SYSTEM INTEGRITY

Five steps to enable system integrity checking:

1. Make sure that system integrity checking for RDB Archiving is set-up and

running properly.

2. Go to ConfigurationLHCLoggingDBSystem Integrity and add desired

integrity classes. (select and add them via clicking on arrow down)

3. Go to ConfigurationApplicationAlarmsAdd class: LHCLoggingDB and add

alarm classes so that alarms are visible in the system status panel.

4. Double click the System Status box in the top right corner of the main UNICOS

panel and check if LHC Logging DB alarm classes are being displayed

5. After enabling system integrity for LHC Logging DB it can take up to 20

minutes until all checks turn green.





LHC-UNICOS

of 37

5.2 HOW TO MODIFY LOGGING CONFIGURATION

To modify the logging configuration use the panels at ConfigurationLHC Logging DB.

5.2.1 REGISTERING NEW SIGNALS FOR LOGGING

1. Go to ConfigurationLHC Logging DBImport

2. Authenticate with the dedicated username and password using “Auth…” button

in the top right corner of the panel.

3. Select (double click) the desired configuration from the list for import

4. Click Check to verify the import file

5. Resolve conflicts and go to previous step until check reports no errors

6. Choose an appropriate Data Category (usually there is only one)

7. Click Append to add the configuration to the database

5.2.2 UNREGISTERING SIGNALS FROM LOGGING

1. Go to ConfigurationLHC Logging DBDelete

2. Authenticate with the dedicated username and password

3. Reload the panel content by using button in lower left part of the panel.

4. Select the signals you want to unregister from logging

5. Click on DeleteSignals+Hierarchies

6. Wait until signals are deleted and list is being reloaded. This time will depend

on the amount of signals and hierarchies behind deleted, and on the database

load.

5.2.3 DELETING HIERARCHIES

If a new import file contains different hierarchies than the old one, you need to delete

old hierarchies before importing the new file, otherwise the logging configuration on

DB will contain multiple hierarchies for a signal.

Note: Duplicated hierarchies are reported by the data consistency panel and they will

also cause the system integrity check for “Full Consistency” fail.

Steps to delete hierarchies from logging configuration:

1. Go to ConfigurationLHC Logging DBDelete

2. Select the signals whose hierarchies you want to delete

3. Click on DeleteHierarchies only

Note: Deletion of hierarchies using the delete panel will not be propagated to

LDB, if you also want to delete hierarchies visible on TIMBER, send a request

to [email protected]



LHC-UNICOS

of 37

5.2.4 RENAMING SIGNALS

When checking import files, renamed signals will be found and reported in the status

table of the import panel. The user must take further actions to resolve the conflicts.

5.2.4.1 RESOLVE BY DELETE AND RE-IMPORT

One solution for resolving conflicts caused by renamed signals is delete and re-import:

1. Remove old Signal_1 (select signals right click resolve conflict delete

signals)

2. Re-Import import file containing new Signal_2

Since deletion of signals will not be propagated to LDB we will end up having both

Signal_1 and Signal_2 on LDB but new values will only be stored into Signal_2.

Note: If you don’t need to have one signal with continuous history this solution will do.

Note: If you try to re-import without deleting first the import will fail.

5.2.4.2 RESOLVE BY SIGNAL RENAMING

Figure 12: Resolve conflicts by renaming signals

Another solution is to rename the affected signal on LDB side.

(Select renamed signals right click resolve conflict rename renamed signals)


LHC-UNICOS

of 37

5.2.5 RECONNECTING SIGNALS

Usually each registered signal has an assigned DPE: Signal_1 DPE_1

Sometimes other DPEs need to be assigned to the signal: Signal_1 DPE_2

When checking import files, reconnected signals will be found and reported.

How to treat reconnected signals:

1. Update import file (so that it contains reconnected signals)

2. Check and append the new import file to logging.

Note: You can check the consistency between import files and central logging

configuration in DB with the data consistency check panel.

5.3 INTRODUCING AND MODIFYING THE USER FUNCTION

The user function is used to filter and select data point elements, and to define the

signals and hierarchies. Should the application need custom hierarchy and signal

definitions that are different from the generic user function, a custom user function

can be used instead.

How to add a custom user function:

1. Add the library to the project.

2. Include it in any [ctrl] section of the project config LoadCtrlLibs = “libraryWithTheUserFunction.ctl

3. Restart UI and System Integrity manager (manager number 41)

How to modify a custom user function:

1. After modifying the function, restart UI and System Integrity manager

(Manager number 41)

5.4 HOW TO CHECK IF LOGGING CONFIGURATION IS UP TO DATE

Go to ConfigurationLHC Logging DBData Consistency and click on the check

button. If the check result does not contain any errors the logging configuration on DB

is in sync with your import files.

If you are using user function to generate the import file you can also check the option

“Generate files”. Then new import files will be generated from your current devices

and they will be used for comparison. These files are temporary and will not overwrite

your configuration.

Hint: When using the option “Generate files” the consistency check might take much

longer (a couple of minutes).


LHC-UNICOS

of 37

5.5 HOW TO REQUEST A RETRANSFER

Data retransfers are very special and complex operations that require actions from

three departments. They should be avoided whenever possible.

If there is no way to avoid a data retransfer it can be requested via:

[email protected]

The retransfer request should contain the following information:

List of signals to be retransferred, if single signals can be specified

Name of the DB schema, if all signals of a schema need to be retransferred

Time range of the retransfer (start time and end time)



LHC-UNICOS

of 37

6. Understanding errors and warnings

6.1 SYSTEM INTEGRITY

For more details see LHC Logging DB Problem Management.

6.1.1 TRANSFER JOBS

70 – Query Error

Error value 70 is a generic error that results when a query to either RDB or

LoggingDB fails, at any given point in the function call chain.

Possible reasons:

a. Import file used is not consistent with what is generated automatically by

the user function

If you have modified the user function, restart the UI and system

consistency manager (manager number 41)

Regenerate and import the new file

b. User function not in system integrity manager’s memory

Check that library containing function is included in the project’s

configuration’s [ctrl] section

Restart the system integrity manger (manager number 41)

c. RDB database connection lost or misconfigured

Check and fix RDB configuration

d. LHC Logging database connection lost or misconfigured

Check and fix LHC Logging database connection

20 – Transfer jobs delayed

Error value 20 indicates a delay in the Database to Database transfer jobs. Contact

the SCADA expert for assistance by sending an email to

[email protected] with subject line “SCADA SERVICE – LHCLoggingDB”

Possible reason:

a. Database is under heavy load and transfers are taking longer than expected

Increase the transfer job max age

10 – Transfer jobs stopped

Error value 10 indicates a stop in the Database to Database transfer jobs. Contact

the SCADA expert for assistance by sending an email to


Possible reason:

a. Transfer jobs are stopped or corrupted

Check that transfer jobs are running and have no errors

6.1.2 TEST DATA POINTS

70 – Query Error



Possible reasons:


the user function

https://wikis.web.cern.ch/wikis/display/EN/LHC+Logging+DB+Problem+Management




LHC-UNICOS

of 37


consistency manager (Manager number 41)



Check that library containing function is included in the project

configurations [ctrl] section

Restart the system integrity manger (Manager number 41)





40 – Registration error

Error value 40 is raised when registration of test data points was not successful.

Contact your Application Responsible for assistance.

Possible reasons:

a. Test data point elements do not exist

Create missing test data points

b. Test data point configuration is corrupted

Fix test data point configuration

Restart the system integrity manager (Manager number 41)

30 – Transfer error

Error value 30 indicates an error in the Database to Database transfer jobs.

Contact the SCADA expert for assistance by sending an email to


Possible reason:

a. Transfer jobs are corrupted

Check on RDB2LHC that transfer jobs are running and have no

errors

b. Database connection is not working

Check on RDB2LHC that the connection to LDB is valid and

restart transfer jobs

6.1.3 DATA CONSISTENCY

70 – Query Error



Possible reasons:


the user function









LHC-UNICOS

of 37






10 – Signals with missing DPEs

Error value 10 indicates that the current logging configuration contains signals

without data point elements. Contact your Application Responsible for assistance.

Possible reasons:

a. Application responsible has modified devices and didn’t update the LHC

Logging DB configuration

Update the LHC Logging DB configuration

5 – Signals with inconsistent archive group

Error value 5 indicates that the current logging configuration contains signals with

inconsistent archive groups. Contact your Application Responsible for assistance.

Possible reasons:

a. Application responsible has modified devices and didn’t update the LHC



6.1.4 FULL CONSISTENCY

70 – Query Error



Possible reasons:


the user function












10 – Inconsistent logging configuration

Error value 10 indicates that the current logging configuration is inconsistent.

Contact your Application Responsible for assistance.

Possible reasons:

b. Application responsible has modified devices and didn’t update the LHC




LHC-UNICOS

of 37

6.2 WARNINGS

6.2.1 REPLACED CHARACTERS

Invalid characters replaced in 'Description': (x,y,z)

Checking automatically replaces a set of invalid characters in description. This is to

support legacy configurations containing non ASCII characters. Characters which

are replaced are shown below.

Note: If a character is not present in the above list or on the whitelist, it will be

completely removed. For the whitelist see 6.3.1 Invalid Characters.

6.2.2 RECONNECTED SIGNAL

Name 'XXXX' using Dpe 'YYYY' will be connected to Alias 'ZZZZ' Dpe

'WWWW'

Signal XXXX used to be connected to data point element YYYY but the imported file

connects it to alias ZZZZ data point element WWWW. Data point elements might

have been deleted and recreated, or the signal could be legitimately been

reassigned. Please check with the responsible if this is expected. See 5.2.5

Reconnecting Signals for more details.

Note: if the application is not using RDB API, continuous trends cannot be provided

after reconnection.

6.2.3 RENAMED SIGNAL

Old Name: 'XXXX' new Name: 'YYYY' using Alias: 'ZZZZ' Dpe: 'WWWW'

Alias ZZZZ with data point element WWWW used to be connected to signal with

name XXXX. The imported file renames the signal to ZZZZ. Make sure this is

intended. See 5.2.4 Renaming Signals for more details.

6.3 ERRORS

6.3.1 INVALID CHARACTERS

Name, description and hierarchy must all consist of a whitelisted subset of ASCII

characters. The accepted characters are A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q,

R, S, T, U, V, W, X, Y, Z, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x,

y, z, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, _, -, +, =, ., :, ;, /, , (, ), [, ] and comma (,).

& and ¼ 1/4 ë e Ô O

% percent ¾ 3/4 È E ù u

-> to à a É E û u

> upper â a Ê E ü u

< lower å a Ë E Ù U

@ at À A ï i Û U

© c Â A î i Ü U

\\ / Ä A ì i æ ae

* x Å A Ï I Æ AE

÷ / Ã A Î I ç c

{ ( é e ô o Ç C

} ) è e ö o µ u

½ 1/2 ê e ò o ß b


LHC-UNICOS

of 37

Alias 'XXXX' Dpe 'YYYY' Attribute 'Name': Forbidden character 'z' found.

The name attribute of the signal with alias XXXX and DPE YYYY contains forbidden

character z. All characters in the name must be in the above whitelist.

Alias 'XXXX' Dpe 'YYYY' Attribute 'Description': Forbidden character 'z'

found.

The description attribute of the signal with alias XXXX and DPE YYYY contains

forbidden character z. All characters in the description must be in the above

whitelist.

Alias 'XXXX' Dpe 'YYYY' Attribute 'Hierarchy': Forbidden character 'z'

found.

The hierarchy attribute of the signal with alias XXXX and DPE YYYY contains

forbidden character z. All characters in the hierarchy must be in the above

whitelist.

6.3.2 SIGNAL NAME

Name 'XXXX' is too long

Signal name must be less than 51 characters long. This is a limitation on the LDB

and cannot be exceeded. Please make the name shorter.

Name 'XXXX' defined more than once

The name ‘XXXX’ has been used multiple times. Signal names must be unique.

Please make sure no two signals definition specify the same name.

6.3.3 HIERARCHY

DPEs with Hierarchy 'ERROR' detected

a. If import file is manually managed, there are signals where the hierarchy is

specified as ERROR. Please check and either correct the hierarchies, or

remove these signals.

b. If user function is used to generate import files, the user function is not

able to parse hierarchy from the full DPE name. Check the hierarchy parsing

function in the UserLib.

DPEs with Hierarchy 'IGNORE' detected

a. If import file is manually managed, there exists signals where the hierarchy

is specified as IGNORE. Please check and either correct the hierarchies, or

remove these signals.

b. If user function is used to generate import files, the user function is finding

data point elements that match the pattern to be ignored, commonly SPARE

and RESERVE. These data point elements will be ignored in consistency

checks. If there should be no ignored data point elements, check the

parsing function in UserLib.


LHC-UNICOS

of 37

6.3.4 ARCHIVE

Alias 'XXXX' Dpe 'YYYY' not found in RDB-Archive. Check archive config

and archive manager.

Check that the DPE has an archive config for RDB Archiver (99) and that RDB

Archive manager (99) is configured, running and connected.

6.3.5 PARSING

Line=XX Column=YY

The XML import file contains syntax error on line XX column YY. Please check that

the xml file is valid and fix any errors.

Root node does not exist

The XML import file is missing the root node. See chapter 3.2 XML Import Files for

correct format.

Next node does not exist

The XML import file failed to find the root node. See chapter 3.2 XML Import Files

for correct format.

Wrong config file format

The import file is not for unLHCLoggingDB or is different version than expected.

Check that attributes application and version are correctly defined in the root node.

See chapter 3.2 XML Import Files for correct format.

While reading child nodes

Error encountered when parsing either config nodes or signals. Either the XML is

badly formed, you have no configData in your import file, or you have no signals in

one of your configData nodes file. See chapter 3.2 XML Import Files for correct

format.

Alias 'XXXX' Dpe 'XXXX.YYYY' has no attribute: 'Name'

All signals must have the attribute name specified. Please check your import file

for signal with data point element XXXX.YYYY or alias XXXX

Alias 'XXXX' Dpe 'XXXX.YYYY' has no attribute: 'Hierarchy'

All signals must have the attribute hierarchy specified. Please check your import

file for signal with data point element XXXX.YYYY or alias XXXX

Cannot open config file XXXX

The parser was not able to open the specified file. Make sure the file exists and

that you have read rights to the file.

6.3.6 DATAPOINT

Element Y, neither Dpe nor Alias specified

DP Consistency check was called without data point element or alias specified.

Please contact [email protected].

Dpe 'XXXX' does not exist

The specified data point does not exist. It might have been deleted or could have

never existed. The import file must be updated and signal using this data point de-

registered if existing.

Alias 'XXXX' does not exist

The specified alias does not exist. It might have been deleted or could have never

existed. The import file must be updated and signal using this alias de-registered if

existing.



LHC-UNICOS

of 37

Alias 'XXXX' belongs to DP 'YYYY', please specify the Dpe

Aliases used for signals must point to data point elements, not data points. Please

specify the exact data point element.

Wrong Alias or Dpe. Alias 'XXXX' resolved to DP 'YYYY' but Dpe is 'ZZZZ'

The alias points to a different DP than the specified DPE is an element of. Please

check and correct the import file.

Alias: 'XXXX' and Dpe: 'YYYY' do not match

The alias and DPE attributes point to different elements. Both must point to the

same element. Please check and correct the import file.

6.3.7 DATA CATEGORY

Getting data categories from database

Error getting data categories from RDB2LHC database. Make sure the

unLHCLoggingDB database connection has been configured (UNICOS MenuConfigurationLHC Logging DBSettings) and active.

Alias 'XXXX' Dpe 'YYYY' data category 'ZZZZ' does not exist

The specified data category does not exist. Please check that you have spelled the

category correctly. If the category is new, contact [email protected]

and request for the category to be created.

6.4 POP-UPS

Error during full consistency check or during manual check of data

consistency

Possible solutions:

a. Import file is malformed or empty. If no signals were selected, an empty

file will result in this error. File is considered empty, even if it contains the

[_RDBArchive] tag.

Regenerate import file to get the latest state

b. Library containing the user function is not included in project config file

section [ctrl].

Add line LoadCtrlLibs = “libraryWithTheUserFunction.ctl"

Restart the UI and the System Integrity manager (Manager

number 41)

c. User function has been introduced or modified but UI or System Integrity

manager have not been restarted

Restart the UI and the System Integrity manager (Manager

number 41)

Create a configuration for config file generation!

This error is raised when opening the Generate panel with no configuration

present.

Possible solution:

a. No configuration exists

Create a configuration in Manage Configurations panel

Database schema 'XXXX' is not registered in database



LHC-UNICOS

of 37

This error is raised when opening the delete panel and the RDB schema XXXX has

not been declared in the RDB2LHC database. Contact the SCADA expert for

assistance by sending an email to [email protected] with subject line

“SCADA SERVICE – LHCLoggingDB”

Possible solutions:

a. Schema XXXX not in RDB

Connect to correct schema

b. Schema XXXX not accessible from RDB2LHC

Contact IT

Database schema 'XXXX' of this system is not registered in database

'YYYY'

This error is raised when opening the LHC Logging DB Signal Overview panel and

the RDB schema XXXX is not registered in the YYYY database.



Possible solutions:

a. Schema XXXX not in RDB

Connect to correct schema

b. Database YYYY is not the correct database with RDB2LHC

Connect to the correct database for RDB2LHC

c. Database YYYY is the correct one and schema XXXX not accessible from it

Contact IT

Loading database settings failed

This error is raised when no LHC Logging DB connection has been configured.



Possible solutions:

a. No connection exists

Configure the connection, activate and apply.

DB Error - unLHCLoggingDBSql_queryDataWithParameterMapping: See log

file for details

This error is raised when opening the Delete panel and no LHC Logging DB

connection has been configured. Contact the SCADA expert for assistance by

sending an email to [email protected] with subject line “SCADA SERVICE

– LHCLoggingDB”

Possible solutions:

a. No connection exists

Configure the connection, activate and apply.






LHC-UNICOS

of 37

REFERENCES & USEFUL LINKS

1. UNICOS

2. LHC Logging DB

3. Logging Configuration

4. Procedure to setup RDB Archiving and LHC Logging DB

5. LHC Logging DB Problem Management

6. System Integrity

http://unicos.web.cern.ch/

https://unicos.web.cern.ch/lhc-logging-db

https://wikis/display/CALS/PVSS+Logging+Configuration


https://wikis.web.cern.ch/wikis/display/EN/LHC+Logging+DB+Problem+Management

http://unicos.web.cern.ch/system-integrity

LHC Logging DB User Documentation -...

Documents

Transcript of LHC Logging DB User Documentation -...