Auditing the PI Server
November 2009
OSIsoft, LLC
International Offices
777 Davis St., Suite 250
San Leandro, CA 94577 USA
OSIsoft Australia
Additional Offices
Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
Sales Outlets/Distributors
Middle East/North Africa
Republic of South Africa
Russia/Central Asia
South America/Caribbean
Southeast Asia
South Korea Taiwan
Perth, Australia
OSIsoft Germany GmbH
Altenstadt, Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
Calgary, Canada
OSIsoft, LLC Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda.
Sao Paulo, Brazil
Contact and Support:
Main phone:
Fax:
Support phone:
(01) 510-297-5800
(01) 510-357-8136
(01) 510-297-5828
Web site:
Support web site:
http://www.osisoft.com
http://techsupport.osisoft.com
Support email:
techsupport@osisoft.com
Copyright: © 1998-2009 OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical,
photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, IT
Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI
ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of
OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as
provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 11-Nov-09
Table of Contents
Chapter 1 The PI Audit Database ................................................................................................. 1
Principles of Operation ....................................................................................................... 1
Maintenance Procedures for the PI Audit Database .......................................................... 1
Audit Database File Contents ............................................................................................ 7
Example Audit Records ...................................................................................................... 8
Reference ......................................................................................................................... 13
Appendix A Configuring Audit Logging .................................................................................... 19
Enabling Audit Logging .................................................................................................... 19
Content of Audit Log Messages for Archive and Snapshot Changes ..............................20
Content of Audit Log Messages for PI Batch Database/SDK Object Changes ...............20
Appendix B Technical Support and Resources ....................................................................... 21
Auditing the PI Server
iii
Chapter 1
The PI Audit Database
The PI Audit Database records the data that is added, edited, or removed from specific PI
Server database files, as well as other events or changes to configuration that occur in the PI
Server. The PI Audit Database satisfies FDA Title 21 CFR Part 11 auditing requirements.
In addition to the methods described in this guide that you can use to store, export, and
review audit records, OSIsoft provides the PI AuditViewer (page 2) utility, which enables you
to view and manage Audit Database records. PI AuditViewer is available as a separate
package with its own documentation.
Principles of Operation
The PI Audit Database contains records of changes made to PI Server data. The following
changes are recorded:
•
Editing and deleting time-series data, such as values in the PI Archive.
•
Creating, deleting, and editing configuration information on time-series data. Examples
include PI point configuration data and access permissions for secure objects within the
PI Server.
The PI Audit Database consists of three distinct files. Each file represents a PI Subsystem:
•
Base Subsystem: pibasessAudit.dat
•
Archive Subsystem: piarchssAudit.dat
•
Snapshot Subsystem: pisnapssAudit.dat
All files for the online Audit Database are stored in the PI\log directory of the PI Server.
For more information on the structure of the Audit Database, see Audit Database File
Contents (page 7).
Maintenance Procedures for the PI Audit Database
This section describes the following maintenance procedures for the PI Audit Database:
•
Edit PI Server Tuning Parameters (page 2)
•
Use PI AuditViewer to Manage Audit Records (page 2)
•
Enable Auditing (page 4)
•
Disable Auditing (page 4)
Auditing the PI Server
1
The PI Audit Database
•
Specify Tuning Parameters for Audit File Shift (page 4)
•
Create New Audit Database Files (page 5)
Edit PI Server Tuning Parameters
Some Audit Database maintenance procedures require editing of PI Server tuning parameters.
To edit tuning parameters, follow these steps:
1. Click Start > Programs > PI System > PI System Management Tools.
2. On the System Management pane on the left, expand the Operation entry, and then
select Tuning Parameters.
3. Select the General tab.
4. Double-click the tuning parameter that you want to change. You see a dialog for the
tuning parameter.
5. Enter your edits onto the dialog.
6. Click Apply.
7. Click OK to close the dialog.
Note: On PI Server versions 3.4.380 and later, you need read/write access to the
PITUNING entry in the Database Security editor (Security > Database Security)
to edit tuning parameters. For earlier versions of the PI Server, read/write access
to the DBSECURITY entry is required.
Use PI AuditViewer to Manage PI Audit Records
PI AuditViewer is a Microsoft Windows-based application that allows you to view records
from the Audit Database, select them, examine them, print them, or export them to a new file.
2
Maintenance Procedures for the PI Audit Database
Note: PI AuditViewer satisfies the Title 21 CFR Part 11 FDA regulatory requirements for
generating accurate and complete copies of Audit Records in both humanreadable and electronic form suitable for inspection, review, and copy.
PI AuditViewer allows you to search for and view audit records in the PI Audit Database. It
is an essential tool for analyzing and validating a PI system for compliance with an
implementation of cGMP. It facilitates the generation of selected reports in Windows file
formats, to comply with FDA audit requests.
Because AuditViewer can change auditing status and control the execution of PI system
processes, certain restrictions are in place:
•
AuditViewer must run on the same computer as the PI Server.
•
The user must be a member of the Windows Administrator User Group.
•
For PI Server 3.4.380 and later, the user must have read access to the PIAUDIT entry in
the PI DBSecurity table and read/write access to the PITUNING entry. For earlier
versions of the PI Server, the user must log on to the PI Server as the piadmin user.
PI AuditViewer is available for download from the OSIsoft Technical Support Web site
(http://techsupport.osisoft.com/). Documentation is provided in the AuditViewer Help.
Note: Earlier versions of PI AuditViewer are not compatible with PI Server version
3.4.370 and later.
Enable Auditing
Caution: If the PI Server is installed on Microsoft Cluster Services (MSCS), do not use
PI AuditViewer to enable auditing. PI AuditViewer automatically restarts the Base,
Archive, and Snapshot Subsystems when it enables auditing, which might trigger
failover to the other cluster node. On clustered systems, use PI SMT to change
the EnableAudit tuning parameter to 0, and then restart the subsystems manually
using the cluster administration tool for your operating system: Microsoft Cluster
Administrator for Windows 2000 and 2003, or Failover Cluster Administrator
for Windows 2008.
PI Server auditing is disabled by default. To enable PI Server auditing, follow these steps:
1. Start PI AuditViewer: Click Start > All Programs > PI System > PI AuditViewer.
Auditing the PI Server
3
The PI Audit Database
2. If auditing is disabled, you see the following dialog:
Click Yes to enable auditing.
Note: When you enable auditing, PI AuditViewer changes the value of the EnableAudit
tuning parameter from 0 to -1. On PI Server versions 3.4.380 and later, you need
read/write access to the PITUNING entry in the Database Security tool in PI SMT
(Security > Database Security) to edit tuning parameters. For earlier versions of
the PI Server, you need read/write access to the DBSECURITY entry.
Disable Auditing
To disable auditing, use PI SMT to set the EnableAudit tuning parameter (page 2) to its
default value of 0. You must restart the Base, Archive, and Snapshot Subsystems for changes
to take effect.
Note: You can enable or disable auditing for individual PI Server subsystems or PI
Server databases by specifying a different value for EnableAudit. For details, see
EnableAudit Tuning Parameter (page 13).
Specify Tuning Parameters for Audit File Shift
Over time, Audit Database files can grow large, which can cause performance problems when
the files are re-opened after viewing or other maintenance operations. You can configure the
maximum size of your audit files based on audit file size, number of audit records, or both.
When an audit file reaches the maximum size setting, the PI Server automatically closes the
audit file, appends the date and time to the name of the file, and opens a new file. This is
called an audit file shift.
Use the following tuning parameters to control audit file shifts:
•
AuditMaxKBytes
•
AuditMaxRecords
Use PI SMT to edit (page 2) these parameters.
4
Maintenance Procedures for the PI Audit Database
Note: Audit file shift parameters are not available for PI Server 3.4.370 and earlier. For
these versions of the PI Server, you must periodically create new audit database
files (page 5).
AuditMaxKBytes Tuning Parameter
This parameter causes the PI Server to perform an audit file shift when the size of the audit
file in KB exceeds the parameter value. The default AuditMaxKBytes setting is 256000.
To disable audit file shifts based on file size, set AuditMaxKBytes=0.
AuditMaxRecords Tuning Parameter
This parameter causes the PI Server to perform an audit file shift when the number of audit
records exceeds the parameter value. Set AuditMaxRecords to a non-zero value that
corresponds to the number of audit records.
To disable audit file shifts based on file size, set AuditMaxRecords to its default value of 0.
Create New Audit Database Files
PI Server 3.4.375 and later automatically perform an audit file shift (page 4) based on the
values that you set for the tuning parameters AuditMaxKBytes and AuditMaxRecords. If
you are using an earlier version of PI Server, or choose not to shift audit files automatically,
use the procedures in this section to periodically remove, safely store, and create new Audit
Database files.
OSIsoft recommends that you create Audit Database files for all the Archive, Base, and
Snapshot Subsystems simultaneously, so that you can maintain complete audit records for a
specific time period.
Closing Audit Database Files for Maintenance
The three Audit Database files and the records within them cannot be accessed except by the
associated PI Server subsystem. To access these files to perform maintenance activities, you
must close the database files. The Audit Database files can remain closed for limited periods,
after which they automatically are re-opened. To change this time period, change the value of
the audit file shift tuning parameter for the associated subsystem:
PI Subsystem
Tuning Parameter
Default
Snapshot
pisnapss_AuditBackupTimeout
5 minutes
Archive
piarchss_AuditBackupTimeout
60 minutes
Base
pibasess_AuditBackupTimeout
60 minutes
While an Audit Database file is closed, the associated subsystem accepts new, edited, and
deletion requests and caches them for the Audit Database. When the database file is reopened, the cache is processed and audit records are written to the Audit Database. Caching
activity is written to the Message Log.
Auditing the PI Server
5
The PI Audit Database
Several PI System features are unavailable when the Audit Database files are closed. For
example, you cannot create or edit points. To copy, delete, export, or move an Audit
Database file, you must close the file, perform the required activity, and then promptly reopen the file. The schedule for removing and creating new Audit Database files depends on
the frequency and number of audit records that are created. For example, PI AutoPointSynch
(PI APS) modifies a property of a module to indicate the latest scan, which results in two
audit records. If PI APS scans every five minutes, then hundreds of audit records are
generated every day.
Note: On PI Server 3.4.370 and later, it is not necessary to close audit files for backup.
Close Audit Database Files
To close the Audit Database files, follow these steps:
1. Open a Command Prompt window: Click Start > Run, type cmd, and then click OK.
2. Navigate to the directory PI\adm.
3. Enter the following at the command prompt:
piartool -systembackup start -subsystem piarchss
piartool -systembackup start -subsystem pisnapss
piartool -systembackup start -subsystem pibasess
Re-open Audit Database Files
To re-open Audit Database files, follow these steps:
1. Open a Command Prompt window: Click Start > Run, type cmd, and then click OK.
2. Navigate to the directory PI\adm.
3. Enter the following at the command prompt:
piartool -systembackup end -subsystem piarchss
piartool -systembackup end -subsystem pisnapss
piartool -systembackup end -subsystem pibasess
Replace Audit Database Files
To replace Audit Database files, follow these steps:
1. Close Audit Database files (page 5).
2. Copy the Audit Database files from the PI\log directory to a safe location. Because
storage of the file may be part of site validation, take care to ensure safe and accountable
storage.
For example, to copy the files to a directory named PI\MyAuditFiles, enter these
commands:
copy ..\log\pibasessAudit.dat ..\MyAuditFiles
copy ..\log\piarchssAudit.dat ..\MyAuditFiles
copy ..\log\pisnapssAudit.dat ..\MyAuditFiles
6
Audit Database File Contents
3. Delete the original Audit Database files from the PI\log directory. For example:
del ..\log\pibasessAudit.dat
del ..\log\piarchssAudit.dat
del ..\log\pisnapssAudit.dat
4. Re-open Audit Database files (page 5). The PI Server automatically creates new audit
files in the PI\log directory.
Audit Database File Contents
Each Audit Database file is comprised of a header followed by the audit records. The header
states file path and name used during creation, the creation date, and EnableAudit mask
value. An audit record is created for each of the action types: Add, Edit, and Remove. On Add
or Remove, the record contains the entire object definition. On Edit, only the changes appear.
Each database that supports auditing utilizes a general audit record format. The following are
table views of the generalized audit record.
Audit Record Definition
Field
Description
PIUser
User who made the change. Exception: In audit records from the PI Archive
subsystem, ID=0.
For PI Server 3.4.380 and later with Windows authentication, the name of the
Windows user who made the change.
PITime
Time and date of the change
Database
Database affected by the change.
Action
Change action: Add, Remove, or Edit
AuditRecordID
Unique ID assigned to the audit record
Name
Affected Record Name
ID
Affected Record ID
Changes
Table of specific changes. On Add and Remove, the change indicates each
attribute setting. On Edit, the change shows the before and after value of
changed attributes.
Change Record Definition
Field
Description
Property
Property that was edited
Before
Value before edit
After
Value after edit
On Adds, the current property setting is shown in the After field. The Before field is empty.
Auditing the PI Server
7
The PI Audit Database
On Removes, each property is shown in the Before field. The After field is empty.
Example Audit Records
The following sections show examples of audit records for selected PI Server databases.
Note: The examples in this section assume that the PI Server has been configured to
use PI Server 3.4.380 security settings, in which user accounts in Windows are
mapped to PI Identities. For these servers the Windows user name displays in the
PI Username field. For more information, see Configuring PI Server Security.
PI Points
Create
The following table shows the audit record that results when a user called OSI\jsmith creates
a point called NewPoint:
Date
PI Database
DB
RecordID
DB
RecordName
PI Username
Action
2009-09-27
16:37:3107:00
PIPoints
14
NewPoint
OSI\jsmith
Add
Changes
Property
Before
After
PointClass
null
classic
Compdev
null
2.0
Compmax
null
28800
Delete
The following table shows the audit record that results when a user called OSI\jsmith deletes
a point called NewPoint:
8
Date
PI Database
DB
RecordID
DB
RecordName
PI Username
Action
2009-09-27
16:39:0607:00
PIPoints
14
NewPoint
OSI\jsmith
Remove
Example Audit Records
Changes
Property
Before
After
PointClass
classic
null
Compdev
2.0
null
Compmax
28800
null
Edit
The following table shows the audit record that results when a PI user called OSI\jsmith
modifies the compression specifications of the point with an ID of 9.
Date
PI Database
DB
RecordID
DB
RecordName
PI UserName
Action
13:00:00
11-Oct-01
PIPoints
9
Ba:temp.1
OSI\jsmith
Edit
Changes
Property
Before
After
Compmin
10
0
Compdev
2.0
1.25
Compmax
5000
6000
PI Archive
Attempts to modify the PI Archive are posted by the Snapshot Subsystem. The Snapshot
Subsystem performs some validation. On successful validation, it creates an audit record
indicating it is a removal attempt or an edit attempt.
The attempt is then forwarded to the Archive Subsystem for completion. If the modification
is successful, the Archive Subsystem creates a corresponding audit record.
Remove Archive Event
When an event is removed from the Archive, passing the value is optional. If it is passed, it is
displayed in the Snapshot audit record.
The user is identified through the Snapshot audit record but is shown as 0 in the Archive audit
record.
The following show examples of audit records generated by the PI Snapshot Subsystem and
PI Archive Subsystem when an event is deleted from the Archive:
Auditing the PI Server
9
The PI Audit Database
Removal: PI Snapshot Subsystem
Date
PI Database
DB
RecordID
TimeStamp
PI UserName
Action
2009-09-25
11:59:2807:00
PIArchive
3
2009-09-25
11:41:25-07:00
OSI\jsmith
Remove
Attempt
Changes
Property
Before
After
Value
Null or value
(128.2149)
Null
Removal: PI Archive Subsystem
Date
PI Database
DB
RecordID
TimeStamp
PI UserName
Action
2009-09-25
11:59:2807:00
PIArchive
3
2009-09-25
11:41:25-07:00
0
Remove
Changes
Property
Before
After
Value
128.2149
Null
Edit
For an Edit call, the Before value is not displayed in the PI Snapshot Subsystem audit record.
The corresponding archive record does pass and displays the old value. The user name is
displayed only in the Snapshot record. User ID is shown as 0 in the Archive audit record.
The following are the audit records generated by the PI Snapshot Subsystem and the PI
Archive Subsystem when an event is edited in the Archive:
Edit: PI Snapshot Subsystem
Date
PI Database
DB
RecordID
TimeStamp
PI UserName
Action
2009-09-25
11:58:5607:00
PIArchive
3
2009-09-25
11:23:2507:00
OSI\jsmith
Edit
Attempt
Changes
10
Property
Before
After
Value
Null
159
Example Audit Records
Edit: PI Archive Subsystem
Date
PI Database
DB
RecordID
TimeStamp
PI UserName
Action
2009-09-25
11:58:5607:00
PIArchive
3
2009-09-25
11:58:56-07:00
0
Edit
Changes
Property
Before
After
Value
150
159
Flags
Null
S
Flags has changed from empty to S. S is the Substituted flag that PI Server sets when an
event is edited.
Module Database and Batch Database
The Module Database and Batch Database objects pose a more difficult auditing issue. For
the most part, audit records are similar to the examples for the other databases.
Modules
A module is an array of module values. Modules support change over time. Each module
value represents the module that was in effect for a given time period. Therefore, a module
audit record is actually a module value change record.
A module value is uniquely identified by the module unique ID and the module effective
date. This is different from most audit records that require only the record ID for unique
identification. For example, the Point Database needs only the Point ID to identify the record.
The following is an example of a module record identification. It consists of the unique ID,
effective date, and name:
UniqueID="e9f0a8cb-bb08-44b5-8b50-899a8813d09e, 31-Dec-69
16:00:01" Name="Child Module 01"
Module Hierarchy
Modules are hierarchical. A module may have parent modules and child modules. Although,
inserting a module into a parent module is effectively an edit of both parent and child module,
the Audit Database only shows this modification as a change to the parent.
Child modules are inserted into a specific value of the parent. This is an explicit edit of a
module value. The parent references of a child are not assigned to a specific value. All
module values that represent this child implicitly acquire the link to the parent. Since it is
implied a child module was edited and to avoid clutter and confusion in the Audit Database,
only the change to the parent is shown. The inserting of a child into a module is shown as a
change to the module's Children attribute.
Auditing the PI Server
11
The PI Audit Database
The following represents the change to that attribute when adding a child. Notice the after
value has the additional unique ID of the child that was inserted.
PIModuleAttribute Name="Children"
Before=12e0e168-4ec6-499e-b6e3-271489893442
After=6895acf1-d177-4efd-a5fa-eeaf9c115bd9, 12e0e168-4ec6-499eb6e3-271489893442
PI Properties
PI Properties are hierarchical. Properties can have properties, which can have properties, and
so on. Since properties do not have unique identifiers, a rename is indistinguishable from a
deletion followed by an addition.
Adding a PI Property is shown as an edit to the module by showing the parent property to
which the property was added. All modules have an implicit root property called
\\PIProperties.
The following are details of adding a root property with a value of 106.
PIProperty Name="Prop-106" ParentUNC_Name="\\PIProperties"
Value=106
Here are details of adding a sub-property to the above property.
PIProperty Name="Sub-Prop" ParentUNC_Name="\\PIProperties\Prop106"
Value=99
These examples focus only on the attribute that changed. The audit record contains
information that completely identifies the modified module. Also, renaming a property is
shown as a deletion followed by an addition in a single audit record.
PI Batches
PI Batch audit records are similar to Module audit records. PIProperties are handled
identically as Module properties. Inserting a PIUnitBatch is similar to inserting a child
module: the PIUnitBatches property shows the list of Unique IDs that represent the
PIUnitBatches. The reference to the PIUnitBatch gains to the PIBatch is also shown as an
edit to the PIUnitBatch.
PI Unit Batches
PIUnitBatches only have one unique issue, which is showing changes to the PISubbatches
collection. This is handled similarly to PIProperties. Unlike PIProperties, however, subbatches are uniquely identified, so a rename is not the same as a deletion followed by an
addition.
Audit Records Suppressed when End Time is Not Set
Audit records are only generated for batches if the End Time is set. This prevents the
creation and modification of PIBatches, PIUnitBatches, and PITransferRecords through
12
Reference
automated processes such as Batch Event File Monitor (EVTintf) and the PI Batch
Generator (PIBaGen). Automatic generation of audit records for each modification
indefinitely would quickly overwhelm the Audit Database.
Deletions of batches are an exception. All deletions create an audit record when auditing is
enabled.
Reference
EnableAudit Tuning Parameter
You can enable auditing on individual database tables. Auditing is controlled through the
EnableAudit tuning parameter. The value is a bitmask where each bit controls auditing to a
specific database. A bit value of 1 enables auditing for the corresponding database. The
following table lists the PI Server databases and the controlling bitmask value in hexadecimal
and decimal format.
Database Table
Subsystem
Value
Hexadecimal
Decimal
0x1
1
Digital State
0x2
2
Attribute Set (Point
database schema)
0x4
4
Point Class (Point
database schema)
0x10
16
User
0x20
32
Group
0x40
64
Trust
0x80
128
Modules
0x100
256
Headings and
HeadingSets
0x200
512
Server
0x4000
16384
Collective
0x8000
32768
Identity
0x10000
65536
Identity Mapping
0x20000
131072
Database Security
0x40000000
1073741824
0x400
1024
Campaign
0x800
2048
Batches
0x1000
4096
Unit Batches
0x2000
8192
0x10000000
268435456
Point
Transfer Records
Snapshot
Auditing the PI Server
PI Base
PI Archive
PI Snapshot
13
The PI Audit Database
Database Table
Archive
Subsystem
PI Snapshot and PI
Archive
All Databases
Value
Hexadecimal
Decimal
0x30000000
536870912
0xFFFFFFFF
-1
For example, to enable auditing for the Point Database (which has a bitmask value of 1) and
Digital State Table (which has a bitmask value of 2) set the EnableAudit parameter to 3 (= 1
+ 2.) Similarly, set the EnableAudit parameter to 131 (= 1 + 2 + 128) to enable Point, Digital
State, and Trust Table auditing.
Enter numeric values into the Timeout Table as decimal numbers. Hexadecimal (base 16)
notation is more convenient for creating or examining the bitmask value entered into the
EnableAudit parameter. It is easier to use hexadecimal notation to create the desired bitmask
and convert to decimal for entry into the Timeout Table. Conversely, it is easier to read a
decimal entry from the Timeout Table and convert to hexadecimal to interpret the value as a
bitmask.
To change the value of EnableAudit, use PI SMT as described in Edit PI Server Tuning
Parameters (page 2).
Alternatively, use the piconfig utility. For example, enter the following commands in the
PI\adm directory to enable auditing on all databases:
piconfig
(Ls - ) Piconfig> @table pi_gen,pitimeout
* (Ls - PI_GEN) Piconfig> @mode create,t
* (Cr - PI_GEN) Piconfig> @istr name,value
* (Cr - PI_GEN) Piconfig> EnableAudit,-1
*> EnableAudit,-1
* (Cr - PI_GEN) Piconfig>
Changes to EnableAudit do not take effect until you restart the affected subsystem.
Audit Database File Open Failure
If an Audit Database file cannot be re-opened or created, the associated PI Server subsystem
creates an alternate Audit Database file named pisubsystemAudit~UTCSeconds.dat,
where pisubsystem is the name of the associated subsystem and UTCSeconds is the current
time expressed in UTC seconds. For example: pisnapssAudit~1003043789.dat.
The subsystem once again attempts to open or create pisubsystemAudit.dat. If this fails
again, a new file, using the same format above, is created and used for auditing.
Note: The pisubsystemAudit~UTCSeconds.dat files in the PI\log directory
contain valid audit records that are not included in the primary defined Audit
Database file. There is no merge function available. To maintain a complete audit
trail, you need to store and back up these alternate files.
14
Reference
To avoid creating alternate Audit Database files during Audit Database maintenance:
1. Close the audit files (page 6).
2. Immediately copy or move the audit files to a different directory.
3. Re-open the audit files (page 6).
PI Snapshot Subsystem Considerations
Data Buffering and the Audit Database
If the PI Snapshot Subsystem is not running, data from non-buffered API and PINet nodes
can be lost. However, because it plays a key role in preventing data loss, the PI Snapshot
Subsystem buffers all events until they can be successfully written to the PI Archive
Subsystem.
Likewise, when the Audit Database file for the PI Snapshot Subsystem is closed, the
subsystem continues to accept new audit record values in an internal buffer. These records are
cached until the file is re-opened and the cached records are transferred to the Audit
Database.
PI Snapshot Audit Database Exceptions
Only data that is replaced or changed is audited. However, some interfaces use editing
operations even when the data is new or unchanged. Such interfaces trigger the creation of
audit records.
The -xa Option for the pidiag Utility
The pidiag utility is a collection of tools for diagnostics, information, and simple repairs. You
can use the -xa option of pidiag to export Audit Database records to XML format text. The
exported XML text allows you to view and analyze records with applications such as
Microsoft Access, Microsoft Excel, or a Web browser.
For more information on pidiag, see the PI Server Reference Guide.
Export Procedure
To export audit records from an Audit Database file to XML:
1. Close (page 6) the Audit Database file.
2. Copy the Audit File from the PI\log directory to another directory.
3. Re-open (page 6) the Audit Database file.
4. Use pidiag to export the Audit Database file.
The following is the minimum syntax, which exports all records in the specified file:
pidiag -xa AuditFilePath
Auditing the PI Server
15
The PI Audit Database
For example:
pidiag -xa ..\temp\pibasessAudit.dat > ..\temp\BaseAudit.xml
Optional Arguments
Use the following arguments to control output.
Time Range
To constrain output to audit records during a time range, specify the start time and end time.
Use the -st and -et arguments to specify the time range in PI Time Format. For details on PI
Time Format, see the PI Server Reference Guide.
The first audit record on or before the start time through the last record on or after the end
time is displayed. For example:
pidiag -xa ..\temp\pibasessAudit.dat -st "21-Feb-99 13:00:00" -et
"*"
This displays the first audit record on or before 1:00 PM, February 21, 1999, through the
current time.
Note: To avoid confusion in the command-line interpretation, enclose the time
arguments in double quotes (") as shown in the example.
Unique Audit Record ID
To specify an audit record to export, include the audit record ID. Start time and end time
options are ignored when you use this option. For example:
pidiag -xa ..\temp\pibasessAudit.dat -uid "1A027C7F-3B82-49928BBF-B20C2EA66FD1"
Audit Database Mask
To specify one or more Audit Databases to export to XML, use the pidiag -xa dbmask
mask option. See Enable Auditing (page 4) for a list of database mask values. The mask is a
decimal integer sum of the values corresponding to the databases to export. For example, the
mask for the User database is 32, and the mask for the Group database is 64. You can export
Audit records for these two databases by specifying a -dbmask value of 96:
pidiag -xa ..\temp\pibasessAudit.dat -dbmask 96
Schema
The exported XML includes a reference to URLs for XSD (XML Schema Definition) files.
The XSD files are a formal declaration of the schema. The schema describes and constrains
the content of the Audit Database output.
OSIsoft specifies the URL of a default PI Audit Database schema that is W3C-compliant. The
default OSIsoft schema reference included in the exported XML is:
16
Reference
<PIAudit xmlns="xml.osisoft.com-schemas-piaudit"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="xml.osisoft.com-schemas-piaudit
http://xml.osisoft.com/Schemas/PIAudit">
In certain cases it may be advantageous to specify a different reference for a schema. For
example, an application running on a computer behind a firewall may not have access to XSD
files on the Internet.
The schema may be specified on the command line by the -xh export header option. The
schema specified replaces everything inside the PIAudit tag in the default PIAudit schema
reference. Specifying this argument has no other effect.
For example, use the following command to refer to the schema located at
http://xml.yourcompany.com/Schemas/PIAudit:
pidiag -xa ..\temp\pibasessAudit.dat -xh
"xmlns=\"xml.osisoft.com-schemas-piaudit\"
xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
xsi:schemaLocation=\"xml.osisoft.com-schemas-piaudit
http://xml.yourcompany.com/Schemas/PIAudit\""
Note: Double quote characters (") embedded in command-line parameters must be
preceded with a backslash (\)character.
Auditing the PI Server
17
Appendix A
Configuring Audit Logging
The Archive and Snapshot Subsystems can be configured to report audit information to the PI
Server Message Log. This audit logging can be useful for testing and troubleshooting or for
other custom monitoring applications, but it is not a sufficient alternative to the PI Audit
Database for compliance with regulations such as FDA Title 21 CFR Part 11. Audit logging
is independent of the PI Audit Database and does not interfere with its operation.
To monitor the PI Server Message Log, use the SMT Message Log tool (Operation >
Message Logs). For details on managing and monitoring the PI Server Message Log, see the
PI SMT help for the Message Log tool or the PI Server System Management Guide.
Note: To view the message logs on PI Server versions 3.4.380 and later, you need read
permissions to the PIMSGSS entry in the Database Security tool in PI SMT
(Security > Database Security).
Enabling Audit Logging
To enable the Message Log audit trail, use the following tuning parameters:
Parameter
Tracked Actions
Notes
ArchiveEditLogging
Deletions and edits to PI
Archive and PI Snapshot
events
For changes to take effect, restart the
Archive and Snapshot Subsystems
BatchDbEditLogging
Changes and deletions in
PIBatch and PIUnitBatch
For changes to take effect, restart the
Archive Subsystem
These tuning parameters are not available in PI SMT by default; to enable logging, you must
add the parameters to the General tab in the Tuning Parameters tool (Operation > Tuning
Parameters).
To enable logging, add these entries to the list of tuning parameters. Set the value to 1 to
enable and 0 to disable.
Auditing the PI Server
19
Configuring Audit Logging
Content of Audit Log Messages for Archive and Snapshot Changes
The audit log messages for changes to Archive and Snapshot events contain the following
information:
Field
Description
Message source
The message source is Archive Edit
Edit date
Edit date
Edit type
Delete or Replace
Point ID
Point ID
Connection ID
Connection ID
User
Only in message from the PI Snapshot
Subsystem
Event time
Edit time
New value
Only in message from the PI Snapshot
Subsystem
Old value
Only in message from PI Archive.
Content of Audit Log Messages for PI Batch Database/SDK Object
Changes
The audit log messages for changes to PI Batch Database objects contain the following
information:
20
Field
Description
Source
PIBatchDb Edit Always included
Edit Time
Always included
Edit type
Edit or Delete
Batch ID
Pre-edit Batch ID Always included
Unique ID
Always included
Start time
New and old, if changed
End time
Initial setting of the end time is not recorded.
Subsequent changes are recorded
Product
New and old, if changed
Recipe
This attribute only applies to PIBatch objects
ProcedureName
This attribute only applies to PIUnitBatch objects
Appendix B
Technical Support and Resources
You can read complete information about technical support options, and access all of the
following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com (http://techsupport.osisoft.com)
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
•
Product name, version, and/or build numbers
•
Computer platform (CPU type, operating system, and version number)
•
The time that the difficulty started
•
The message log(s) at that time
Help Desk and Telephone Support
You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table
below to find the most appropriate number for your area. Dialing any of these numbers will
route your call into our global support queue to be answered by engineers stationed around
the world.
Office Location
Access Number
Local Language Options
San Leandro, CA, USA
1 510 297 5828
English
Philadelphia, PA, USA
1 215 606 0705
English
Johnson City, TN, USA
1 423 610 3800
English
Montreal, QC, Canada
1 514 493 0663
English, French
Sao Paulo, Brazil
55 11 3053 5040
English, Portuguese
Altenstadt, Germany
49 6047 9890
English, German
Manama, Bahrain
973 1758 4429
English, Arabic
Singapore
65 6391 1811
86 021 2327 8686
English, Mandarin
Mandarin
Perth, WA, Australia
61 8 9282 9220
English
Auditing the PI Server
21
Technical Support and Resources
Support may be provided in languages other than English in certain centers (listed above)
based on availability of attendants. If you select a local language option, we will make best
efforts to connect you with an available Technical Support Engineer (TSE) with that language
skill. If no local language TSE is available to assist you, you will be routed to the first
available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted
to remain on the line to wait for the next available TSE or else leave a voicemail message. If
you choose to leave a message, you will not lose your place in the queue. Your voicemail
will be treated as a regular phone call and will be directed to the first TSE who becomes
available.
If you are calling about an ongoing case, be sure to reference your case number when you call
so we can connect you to the engineer currently assigned to your case. If that engineer is not
available, another engineer will attempt to assist you.
Search Support
From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site's Support Solutions,
Documentation, and Support Bulletins using the advanced MS SharePoint search engine.
Email-based Technical Support
techsupport@osisoft.com
When contacting OSIsoft Technical Support by email, it is helpful to send the following
information:
•
Description of issue: Short description of issue, symptoms, informational or error
messages, history of issue
•
Message logs: See documentation for your PI System for information on obtaining
message logs pertinent to the situation.
Online Technical Support
From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.
Using OSIsoft's Online Technical Support, you can:
22
•
Enter a new call directly into OSIsoft's database (monitored 24 hours a day)
•
View or edit existing OSIsoft calls that you entered
•
View any of the calls entered by your organization or site, if enabled
•
See your licensed software and dates of your Service Reliance Program agreements
Content of Audit Log Messages for PI Batch Database/SDK Object Changes
Remote Access
From the OSIsoft Technical Support Web site, click Contact Us > Remote Support
Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on
troubleshooting and assistance. See the Remote Access page for details on the various
methods you can use.
On-site service
From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service
Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more
information.
Knowledge Center
From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers. For these options, click
Knowledge Center on the Technical Support Web site.
•
The Search feature allows you to search Support Solutions, Bulletins, Support Pages,
Known Issues, Enhancements, and Documentation (including user manuals, release
notes, and white papers).
•
System Manager Resources include tools and instructions that help you manage: Archive
sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server
security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.
Upgrades
From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.
You are eligible to download or order any available version of a product for which you have
an active Service Reliance Program (SRP), formerly known as Tech Support Agreement
(TSA). To verify or change your SRP status, contact your Sales Representative or Technical
Support (http://techsupport.osisoft.com/) for assistance.
Auditing the PI Server
23