OPTIMATE INTEGRATOR FOR PI SYSTEM TO SPLUNK Command …optimate.net.au/splunk/Optimate Integrator for PI System... · 2018. 8. 22. · Revision No: 2.3 Effective Date: 31st July 2018

For further information or support email [email protected] Integrator Version 2.x © Optimate Pty Ltd 2018. www.optimate.net.au June 2018

OPTIMATE INTEGRATOR FOR PI SYSTEM TO SPLUNK

Command Reference

mailto:[email protected]

http://www.optimate.net.au/


REVISION INFORMATION

Author: Ebrahim Mardani, Georgia Webber, David Harte

Revision No: 2.3

Effective Date: 31st July 2018

Filename: Optimate Integrator for PI System to Splunk Command Reference

REVISION HISTORY

Rev No. Description Author Reviewed Date

1.0 First draft. EM DH 30th May 2018

2.0 Reviewed, minor modifications. DH 25th June 2018

2.1 Reviewed, modifications to AF section. GW EM 28th June 2018

2.2 Modified the description of attribute

term

DH EM 20th July 2018

2.3 Added examples and details to match

changes in latest release of the app.

GW DH 31st July 2018




Contents 1 DOCUMENT CONVENTIONS AND NOTES .............................................................................................. 4

2 SPL COMMANDS ................................................................................................................................... 4

2.1 PI Tag value commands ................................................................................................................ 5

2.1.1 Index ...................................................................................................................................... 5

2.1.2 Host ....................................................................................................................................... 5

2.1.3 Hosttype ................................................................................................................................ 5

2.1.4 Query ..................................................................................................................................... 6

2.1.5 Calculation Basis (calc_basis) ................................................................................................ 6

2.1.6 Expression ............................................................................................................................. 7

2.1.7 Filter Expression (filter_expr) ................................................................................................ 8

2.1.8 Mode ..................................................................................................................................... 8

2.1.9 Sample Interval (sample_interval) ...................................................................................... 10

2.1.10 Show Filtered (show_filtered)............................................................................................. 10

2.1.11 Timestep.............................................................................................................................. 10

2.1.12 Time Type (time_type) ........................................................................................................ 11

2.1.13 Event Limit (eventlimit) ....................................................................................................... 11

2.2 PI AF (ASSET FRAMEWORK) Commands ..................................................................................... 12

2.2.1 Index .................................................................................................................................... 13

2.2.2 Host ..................................................................................................................................... 13

2.2.3 Hosttype .............................................................................................................................. 14

2.2.4 Database ............................................................................................................................. 14

2.2.5 Query ................................................................................................................................... 14

2.2.6 Attribute .............................................................................................................................. 15

2.2.7 AF Metadata ........................................................................................................................ 15

2.2.8 AF Data Values .................................................................................................................... 17

2.2.9 Desired UoM ....................................................................................................................... 19

2.2.10 Eventlimit ............................................................................................................................ 20

2.3 Supplementary commands ......................................................................................................... 21

2.3.1 Debug/Log commands ........................................................................................................ 21

2.3.2 More data extraction .......................................................................................................... 22




1 DOCUMENT CONVENTIONS AND NOTES

• This document uses the OSIsoft demonstration database NuGreen.

• The PI tags CDT158 and CDM158 are referred to in many of the examples in the following

sections. These tags are provided out of the box by OSIsoft PI.

• Many of the examples in the following sections refer to <pi server>. If you use these examples,

change out <pi server> for your PI server name.

2 SPL COMMANDS

After the Integrator has been installed into Splunk, users can use SPL to extract metadata and data from

the OSIsoft PI system. This document explains the use of the Integrator commands.

In general, there are three types of commands:

1. PI tag value commands

2. PI AF (Asset Framework) commands

o AF metadata commands

o AF data value commands

3. Supplementary commands

o Debug/ Log commands

o More data extraction




2.1 PI TAG VALUE COMMANDS

PI tag value commands are designed to read values for one or more tags from the PI Data Archive. The

following is the basic format for this command:

Example:

index=pi host=<pi server> hosttype="pi" query=<pi query expression>

The query_expression can take many forms which are discussed in the following sections. The following

examples show how to get basic tag data, note the use of the parenthesis to separate multiple tags or if

there is a space character in the tag name. If using parenthesis, the query expression must be enclosed

in quotes.

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158

index=pi host=<pi server> hosttype="pi" query="CDT158"

index=pi host=<pi server> hosttype="pi" query="(CDT158) OR (CDM158) "

2.1.1 Index

This is a required parameter.

It specifies the virtual index that will be used to access data from the PI Data Archive.

In order to trigger the execution of the Integrator, this parameter must be set to a value of ‘pi’.

Example:

index=pi ...

2.1.2 Host


It specifies which PI Data Archive or PI Asset Framework server to use as the data context for queries.

Example:

index=pi host=<pi server> ...

2.1.3 Hosttype

This is an optional parameter. Note, in future versions this will be mandatory

It specifies the type of search to run against this host. There are three possible options:




• “pi”: triggers a PI Data archive search.

• “af”: triggers an Asset Framework metadata search.

• “afdata”: triggers an Asset Framework data search.

Examples:

index=pi host=<pi server> hosttype="pi" ...

index=pi host=<pi server> hosttype="af" ...

index=pi host=<pi server> hosttype="afdata" ...

2.1.4 Query

This is an optional parameter.

It is used to specify a tag mask for searching a list of PI points for which data will be returned.

The standard '*' PI wildcard character is supported to mask multiple characters in a Point name, as well

as the standard '?' PI wildcard character to mask a single character. Multiple tag masks can be passed

within this parameter value using the 'OR' operator.

Examples:

index=pi host=<pi server> hosttype="pi" query=Sinusoid

index=pi host=<pi server> hosttype="pi" query=CD*158

index=pi host=<pi server> hosttype="pi" query=CD?158

index=pi host=<pi server> hosttype="pi" query="CD?158 OR S?nusoid"

index=pi host=<pi server> hosttype="pi" query="CDT* OR sin*"

index=pi host=<pi server> hosttype="pi" query="(CDT*) OR (sin*)"

Note: To maintain continuity with version 1 of the Integrator, ‘tagmask’ has been kept as a viable field,

and can be used instead of ‘query’ with the exact same functionality. While ‘tagmask’ is used,

‘hosttype’ does not need to be included as a search field. ‘Tagmask’ will however be deprecated in

version 3.

2.1.5 Calculation Basis (calc_basis)


It is used to determine the basis on which summary values are calculated from the source values. By

default, summaries are calculated using a Time Weighted basis. To override this behaviour, you can use

the calc_basis parameter to change the basis on which source values are weighted when calculating a




summary.

The list of possible calculation basis options is:

- TimeWeighted: This is the default option and weights the values in the calculation by the time

over which they apply. Interpolation is based on whether the point is stepped. Interpolated

events are generated at the boundaries if necessary.

- EventWeighted: Values are given equal weighting for each event, regardless of the amount of

time between changes. No interpolation is done. This option requires at least one recorded

value in a time period (two recorded values for standard deviation calculations).

- TimeWeightedContinuous: Values are weighted on the same basis as TimeWeighted, except

interpolation is performed as if the data was continuous, regardless of whether the point is

stepped.

- TimeWeightedDiscrete: Values are weighted on the same basis as TimeWeighted, except

interpolation is performed as if the data was discrete, regardless of whether the point is

stepped.

- EventWeightedExcludeMostRecentEvent: Values are weighted on the same basis

as EventWeighted, except in the handling of events at the boundary of summary intervals in a

multiple intervals calculation. Use this option to prevent events at the intervals boundary from

being double count at both intervals. With this option, events at the end time (most recent

time) of an interval is not used in that interval.

- EventWeightedExcludeEarliestEvent: Values are weighted on the same basis

as EventWeightedExcludeMostRecentEvent. Events at the start time (earliest time) of an

interval is not used in that interval.

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=average calc_basis=eventweighted

index=pi host=<pi server> hosttype="pi" query="CDT158" mode=total calc_basis=timeweighted | eval val

ue = value * 1440

2.1.6 Expression

This is an optional parameter that can be used in place of, but not in addition to the query parameter.

When specified, data is returned for the results of the passed expression.

Expressions must conform to standard PI Performance Equation expression syntax, with the following

additional requirements to be noted:

- The entire expression should be wrapped in double quotes



http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#tagmask-section


- String literals within the expression require that the enclosing double quotes be escaped with

the backslash character (see example)

- If the expression finishes with a string literal, the expression should be enclosed within

parentheses, then enclosed within double quotes (see example)

By default, the expression is sampled based on the archive events of all PI points used in the expression.

The expression is evaluated at each of the timestamps of these source events. If

the sample_interval parameter is specified, the expression is sampled at the specified time interval.

Examples:

index=pi host=<pi server> hosttype="pi" expression="IF 'sinusoid' > 35 THEN 1 ELSE 0"

index=pi host=<pi server> hosttype="pi" expression="(IF TagMax('sinusoid','*-4h','*') > 35 THEN \"Tr

ue\" ELSE \"False\")"

index=pi host=<pi server> hosttype="pi" expression="'Sinusoid' + 'CDT158'" sample_interval=5m

2.1.7 Filter Expression (filter_expr)

This is an optional parameter that cannot be passed when using an expression based query.

It allows a filter expression to be passed when retrieving PI point data.

Filter expressions must conform to standard PI Performance Equation expression syntax, and must

return a Boolean result.

The following additional requirements for filter expressions should be noted:

- The entire expression should be wrapped in double quotes.

- String literals within the expression require that the enclosing double quotes be escaped with

the backslash character (see example).

- If the expression finishes with a string literal, the expression should be enclosed within

parentheses, then enclosed within double quotes (see example).

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158 filter_expr="'Sinusoid' > 60"

index=pi host=<pi server> hosttype="pi" query=CDT158 filter_expr="('CDM158' = \"Manual\")"

2.1.8 Mode


It is used to specify a summary calculation to be performed on PI data over the requested time interval.

The list of possible mode options is:



http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#sampleinterval-section

http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#expression-section


- None (Default): If specified or if mode is omitted, returns raw compressed values from PI.

- Total: Sums values during the interval.

- Average: Returns the average of the recorded values during the interval. If calc_basis is not

specified, returns the time-weighted result.

- Maximum: Finds the maximum value during the interval.

- Minimum: Finds the minimum value during the interval.

- Range: Returns the maximum value minus the minimum value during the interval.

- StdDev: Returns the standard deviation of values during the interval.

- PopulationStdDev: Returns the population standard deviation of values during the interval.

- Count: See below.

- PercentGood: See below.

- All: Returns all available summary calculations.

- AllForNonNumeric: Returns all available summary calculations for non-numeric data.

By default, summary calculations will be performed on a Time Weighted basis. This can be modified

using the calc_basis directive.

The Count and PercentGood calculations are treated as follows:

- Count: The sum of event count over the time range when calculation basis is event weighted.

The sum of event time duration over the time range when calculation basis is time weighted.

- PercentGood: Percent of data with good value during the calculation period. For time weighted

calculations, the percentage is based on time. For event weighted calculations, the percent is

based on event count.

The Total mode performs a totalization of values over the time range.

For time-weighted total calculations, specify a factor that converts recorded rate values to the Data

Archive server default time unit of units per day (see example below).

If the timestep parameter is specified, the summary calculation will be performed at the specified

intervals over the time range.

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=average

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=stddev calc_basis=eventweighted

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=average calc_basis=eventweighted timestep=

1h

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=total | eval value = value * 24



http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#calculationbasis-section

http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#timestep-section


2.1.9 Sample Interval (sample_interval)


It is used to specify how often an expression is evaluated.

When used with the expression parameter, it determines the frequency at which the expression is

sampled and evaluated.

Example:

index=pi host=<pi server> hosttype="pi" expression="'Sinusoid' + 'CDT158'" sample_interval=5m

2.1.10 Show Filtered (show_filtered)


It can be used in conjunction with the filter_expr parameter.

It is passed with a Boolean value of either true or false, and is used to determine whether results filtered

out by the filter expression are shown in the returned result set. If show_filtered=true is passed,

the filtered results are displayed with a value of ‘Filtered’. If this parameter is not passed, the default

behaviour for filter_expr is the same as passing show_filtered=false.

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158 filter_expr="'Sinusoid' > 65" show_filtered=fal

se

index=pi host=<pi server> hosttype="pi" query=CDT158 filter_expr="('CDM158' = \"Manual\")" show_filt

ered=true

2.1.11 Timestep


It can be used in conjunction with the mode parameter to return summary calculations at a specified

interval over the query time range.

When used with a raw query that simply uses a query (mode=raw, or mode is not specified at all), the

timestep parameter can be used to return interpolated data at evenly spaced sample times.

Timestep values must consist of an unsigned number and one of the following valid time unit

abbreviation strings:

- s: (seconds)

- m: (minutes)

- h: (hours)



http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#expression-section

http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#filterexpression-section

http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#mode-section


- d: (days)

- w: (weeks)

- mo: (months)

- y: (years)

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158 timestep=30m

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=average timestep=1d

index=pi host=<pi server> hosttype="pi" expression="('Sinusoid' * 1.2) + 'CDT158'" timestep=30m

2.1.12 Time Type (time_type)


It is used to define the timestamp returned for a value when a summary calculation is performed using

the mode parameter.

The list of possible options is as follows:

- Auto (Default) - The timestamp returned will be the minimum or maximum time for those

summary types, or, the start time of the summary period otherwise.

- EarliestTime - The timestamp returned will be for the start of the summary period.

- MostRecentTime - The timestamp returned will be for the end of the summary period.

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=average time_type=MostRecentTime

index=pi host=<pi server> hosttype="pi" query=CDT158 mode=average timestep=15m time_type=EarliestTim

e

2.1.13 Event Limit (eventlimit)


This command restricts the number of returned events. Note that the truncated events will not be

injected into Splunk.

Example:

index=pi host=<pi server> hosttype="pi" query=CDT158 eventlimit=20



http://localhost:9000/en-US/app/PI_Integrator/CommandReference?earliest=0&latest=#mode-section


2.2 PI AF (ASSET FRAMEWORK) COMMANDS

AF commands are designed to read metadata or values out of the PI Asset Framework. AF SPL searches

are divided into two categories:

• Asset Framework Metadata

AF metadata searches return the Asset Framework metadata for the matched elements, i.e.

UoM for a given element.

• Asset Framework Data Values

AF data searches return the data associated with elements and attributes.

The following image shows a portion of the AF tree from the PI System Explorer. This is referenced in the

following examples.




The following are basic command formats:

Examples:

index=pi host=<af server> hosttype="af" database=<Database name> query=<pi query expression>

index=pi host=<af server> hosttype="afdata" database=<Database name> query=<pi query expression> att

ribute=<attribute names>

Using hosttype=“af” and hosttype=“afdata”, the command fetches AF metadata or AF data

values, respectively.

• Host: Name of the server to search.

• Hosttype: Triggers an Asset Framework search, must be “AF” or “AFDATA”, case insensitive.

• Database: Name of the specific AF database to search.

• Query: Items for filtering AF data source.

• Attribute: List of attributes to return of the search.

Examples:

index=pi host=<af server> hosttype="af" database=nugreen query="b-*"

index=pi host=<af server> hosttype="af" database=nugreen query="name:b-*"

index=pi host=<af server> hosttype="af" database=nugreen query="description:compressor"

index=pi host=<af server> hosttype="afdata" database=nugreen query="name:b-*" attribute="Fuel Gas Fl

ow"

2.2.1 Index


It specifies the virtual index that will be used to access data/metadata from the PI Data Archive or PI

Asset Framework.

In order to trigger the execution of the connector, this parameter must be set to a value of ‘pi’.

Example:

index=pi ...

2.2.2 Host


It specifies which PI Data Archive or PI Asset Framework server to use as the data context for queries.




Example:

index=pi host=<af server> ...

2.2.3 Hosttype

This is an optional parameter (by default is set to "pi"). Note, in future versions (version 3+) this will be mandatory term. It specifies the type of search to run against this host. There are three possible options:

• "pi": Triggers a PI Data Archive search.

• "af": Triggers an Asset Framework metadata search.

• "afdata": Triggers an Asset Framework data search.

Examples:

index=pi host=<af server> hosttype="pi" ...

index=pi host=<af server> hosttype="af" ...

index=pi host=<af server> hosttype="afdata" ...

2.2.4 Database


It specifies the database that will be used to access in PI Asset Framework. Note that the database must be

indexed.

Indexed databases in each AF server are accessible using the following link:

https://<pi server>/piwebapi/admin/search/database.html

2.2.5 Query


It is used to specify a mask for searching Asset Framework elements.

The standard '*' PI wildcard character is supported to mask multiple characters in an element name, as well

as the standard '?' PI wildcard character to mask a single character.

Searches can be based on multiple terms. If multiple terms are entered they are assumed to be OR’ed

together.

You can specify AND, OR, and NOT operators, along with parenthesis to create complex searches, for

example "(vibration* AND datatype:float32) OR afelementtemplate:pump".




Examples:

index=pi host=<af server> hosttype="af" database=nugreen query=pump

index=pi host=<af server> hosttype="af" database=nugreen query="name:b-*"

index=pi host=<af server> hosttype="af" database=nugreen query="name:b-21?"

index=pi host=<af server> hosttype="af" database=nugreen query="name:(Cracking Process)"

2.2.6 Attribute

This is a required parameter if hosttype=”afdata” and is optional for hosttype=”af”.

It specifies a list of attributes for which metadata/values will be returned from the Asset Framework.

Attributes names are semicolon(;) separated.

• Note: Use brackets ‘[]’ to refer to a child/children of an attribute

Examples:


ow;Process Feedrate;Total Fuel Gas"

index=pi host=<af server> hosttype="afdata" database=nugreen query="name:b-*" attribute="Attrib1[chi

ld]"


ld][grand_child]"


ld][*]"

2.2.7 AF Metadata

The following is the basic command format for reading Asset Framework metadata:

Example:

index=pi host=<af server> hosttype="af" database= <Database name> query=<pi query expression> attri

bute=<attribute names>

Where:

• host: Name of the server to search.

• hosttype: Triggers an Asset Framework search, must be AF or “AF”, case insensitive.

• database: Name of the specific AF database to search.

• query: Items for filtering AF data source.




This command searches AF for elements that match query_expression and returns the metadata for the selected attributes if available in the matched elements.

The attributes are semicolon(;) separated.

The first SPL command below returns all AF elements and templates that include ‘pump’ and the second and thrid commands return the matched elements and their attributes as well.

Example:

index=pi host=<af server> hosttype="af" database=nugreen query=pump

index=pi host=<af server> hosttype="af" database=nugreen query=pump attribute="*"

index=pi host=<af server> hosttype="af" database=nugreen query=pump attribute="[*]"

• Note: A search can be based on a term in the form of field:value, such as "name:pump". If no field is specified, i.e. "pump", then the following fields will all be used: name, description, afcategories, afelementtemplate, attributename, attributedescription. The '*' and '?' wildcards are supported, for example: boil* or boi?er

The first command below retrieves all boilers that start with b-21 and have any single character at the end of the name.

The second command returns all attributes (first level of attributes) for the matched elements as well.

The third command returns all attributes (first level) and all child attributes of 'attrib1' (second level of attributes) for the matched elements.

Example:

index=pi host=<af server> hosttype="af" database=nugreen query="name:b-21?"

index=pi host=<af server> hosttype="af" database=nugreen query="name:b-21?" attribute="[*]"

index=pi host=<af server> hosttype="af" database=nugreen query="name:b-21?" attribute="[*];[attrib1]

[*]"

The following returns all boilers with a description that starts with 'boiler' and ends in any series of characters.

Example:

index=pi host=<af server> hosttype="af" database=nugreen query="description:boiler*"

Searches can be based on multiple terms. If multiple terms are entered they are assumed to be OR’ed

together.

You can specify AND, OR, and NOT operators, along with parenthesis to create complex searches, for example

"(vibration* AND datatype:float32) OR afelementtemplate:pump".

Example:




index=pi host=<af server> hosttype="af" database=nugreen query="(name:p-3??)

AND (description:pump*)" attribute="[*]"

2.2.8 AF Data Values

The following is the basic command format for reading Asset Framework data values:

Example:

index=pi host=<af server> hosttype="afdata" database= <Database name> query=<pi query expression> at

tribute=<attribute names>

Where:

• host: Name of the server to search.

• hosttype: Triggers an Asset framework search, must be AFDATA or “AFDATA”, case insensitive.

• database: Name of the specific AF database to search.

• query: Items for filtering the AF data source.

• attribute: List of attributes to return in the search.

This command searches AF for elements that match the query expression and returns the data for the

selected attributes if available in the matched elements.

The attributes are semicolon(;) separated attribute names returned by ‘SPL commands for AF metadata’.

Aside from the 'hosttype=afdata', the rest of the command is the same as in the previous section (AF

Metadata)

Warning, if there are large numbers of attributes for an element, it may return a significant amount of data

that may affect your daily ingestion.

Examples:

index=pi host=<af server> hosttype="afdata" database=nugreen query="name:b-210" attribute="Fuel Gas

Flow"

index=pi host=<af server> hosttype="afdata" database=nugreen query="name:b-2??" attribute="*"

index=pi host=<af server> hosttype="af" database=nugreen query="(name:p-3??) AND (description:pump*)

" attribute=*

index=pi host=<af server> hosttype="afdata" database=nugreen query="description:boiler*" attribute="

Fuel Gas Flow"

To return all elements and all attributes for elements that are based on a template. Warning, this

may return a substantial amount of data.

index=pi host=<af server> hosttype="afdata" database=nugreen query="afelementtemplate:*"

attribute="*"




index=pi host=<af server> hosttype="afdata" database=nugreen query="afelementtemplate:Boiler"

attribute="fuel gas flow"

In the case of multiple elements of the same name, path specific elements can be accessed using the

following syntax:


ribute="\\parentelement\\childelement[<attribute names>]"

Some examples of this are below:

Examples:

index=pi host=<af server> hosttype="afdata" database="nugreen" query="name:(Boiler Fan)" attribute="

\\NuGreen\\Houston\\Cracking Process\\Equipment\\B-210\\Boiler Fan[Blades]"


\\NuGreen\\Houston\\Cracking Process\\Equipment\\B-210\\Boiler Fan[*]"

index=pi host=<af server> hosttype="afdata" database="nugreen" query="name:(Cracking Process)" attri

bute="\\NuGreen\\Houston\\Cracking Process[*];\\Nugreen\\Tucson\\Cracking Process[*]"

If the desired attribute is the child of another attribute, the following syntax should be used:


ribute="[parentAttribute][childAttribute][grandchildAttribute]…"

Some examples of this are below:

To return all child attributes of Blades attribute for the Boiler 210, boiler fan. Note the use of t

he parenthesis "()" on the name search term, the parenthesis ensure any spaces in element names are

considered as one term:


\\NuGreen\\Houston\\Cracking Process\\Equipment\\B-210\\Boiler Fan[Blades][*]"

Return all child attributes for the Blade 1 attribute:


\\NuGreen\\Houston\\Cracking Process\\Equipment\\B-210\\Boiler Fan[Blades][Blade 1][*]"




Return the values of Boiler B-210, Boiler Fan, Blade 1, last pitch angle:

index=pi host=<af server> hosttype="afdata" database="nugreen" query="name:(boiler fan)" attribute="

\\NuGreen\\Houston\\Cracking Process\\Equipment\\B-210\\Boiler Fan[Blades][Blade 1][Current Blade Pi

tch Angle][*]"

Return the installation date of each blade and the name of the blade manufacturer for each boiler fa

n, as a table.


[blades][Blade set manufacturer];[blades][blade 1][installation date];[blades][blade 2][installation

date];[blades][blade 3][installation date];[blades][blade 4][installation date]" | table tagname, va

lue

2.2.9 Desired UoM

This feature is optional.

While requesting AF data values, users can take advantage of changing the data values based on a desired

UoM (Unit of Measure).

Here is the SPL command template:

Example:


ribute="field1|UoM1;field2|UoM2"

As shown in the template, the desired UoM can be requested for each attribute. If UoM is not specified for

an attribute, the attribute's default unit of measure will be returned.

Examples:

index=pi host=<af server> hosttype="afdata" database="nugreen" query="boiler" attribute="Fuel Gas Fl

ow|bbl/d"


ow|barrel per day"

The ‘Fuel Gas Flow’ data values have been requested under a new UoM (bbl/d).

In the following example, the result will be all data values for ‘Fuel Gas Flow’ and ‘Process Feedrate’ for all

matched elements.

The UoM for ‘Fuel Gas Flow’ will be also changed to ‘barrel per day’.

No data value conversion is requested for the ‘Process Feedrate’ attribute.




Example:


ow|barrel per day;Process Feedrate"

• Note: ‘|’ is not allowed in the ‘attribute’ if ‘hosttype=af’.

Below are some examples of UoM selection using a mixture of child and parent elements and attributes:

Example:

index=pi host=<af server> hosttype="afdata" database=Nugreen query="name:(Boiler Fan)" attribute="Bo

iler fan[blades][Blade 1][Current Blade Pitch Angle]|radian;Installation Date"

index=pi host=<af server> hosttype="afdata" database=Nugreen query="name:(Boiler Fan)" attribute="\\

Nugreen\\Houston\\Cracking Process\\Equipment\\B-210\\Boiler fan[blades][Blade 1][Current Blade Pitc

h Angle]|radian;\\Nugreen\\Tucson\\Cracking Process\\Equipment\\B-309\\Boiler fan[blades][Blade 1][C

urrent Blade Pitch Angle]|revolution"

2.2.10 Eventlimit


This command restricts the number of returned events. Note that the truncated events will not be injected

into Splunk.

Examples:

index=pi host=<af server> hosttype="af" database=nugreen query=pump eventlimit=20


ow" eventlimit=20




2.3 SUPPLEMENTARY COMMANDS

2.3.1 Debug/Log commands

The Integrator provides debug logging. By default, the debug message and logging feature is disabled, it

is enabled by a search term in the SPL. To activate, include a debug=true in the SPL. Debugging

messages will be displayed in Splunk search results. Debug logging can also be affected by setting the

debuglevel which determines how much and the type of logging provided. Debuglevel can be one of

the following values:

• debuglevel=fine

• debuglevel=info

• debuglevel=warning

• debuglevel=severe

Examples:

index=pi host=<pi server> hosttype="pi" query=CDT158 debug=true

index=pi host=<pi server> hosttype="pi" query=CDT158 debug=true debuglevel=info

Debugging can also be redirected to a file by including the ‘logfile=true’ command.

Example:

index=pi host=<pi server> hosttype="pi" query=CDT158 debug=true debuglevel=info logfile=true

Note, to access the log files you will need access to the HDD that Splunk is installed on. The log files can

be located in the following directory:

\SPLUNK_HOME\etc\apps\PI_Integrator\bin\logs

To remove results and view debug messages only, sample the following snippet.

Example:

index=pi host=<pi server> hosttype="af" database="nugreen" query="pump" debug=true debuglevel=fine l

ogfile=true

| search debuglevel != ""

| table debuglevel, message




2.3.2 More data extraction

All SPL commands for PI AF can be piped as a source to the next level of SPL commands for AF data

extractions.

An Element (name, description) extraction.

Example:

index=pi host=<pi server> hosttype="af" database="nugreen" query="pump"

| spath input=element output=elementName path=name

| spath input=element output=elementDescription path=description

| table elementName, elementDescription

Element (name, description) and Attribute (name, description) extraction.

Example:




| spath input=element output=attribs path=attributes{}

| mvexpand attribs

| spath input=attribs output=AttributeName path=name

| spath input=attribs output=AttributeDescription path=description

| table elementName, elementDescription, AttributeName, AttributeDescription

Extraction by Element.

Example:





| mvexpand attribs



| eval Element=elementName + ", " + elementDescription




| eval Attributes=AttributeName + ", " + AttributeDescription

| stats values(Attributes) by Element

Extraction of all attribute fields by Element.

Example:

index=pi host=<pi server> hosttype="af" database="nugreen" query="pump" attribute="[*]"




| mvexpand attribs



| spath input=attribs output=AttributeUoM path=uom

| spath input=attribs output=AttributeDataType path=datatype

| eval Element=elementName + ", " + elementDescription

| eval Attributes=AttributeName + ", " + AttributeDescription + "," + AttributeUoM + "," + Attribute

DataType

| stats values(Attributes) by Element



Documents

OPTIMATE INTEGRATOR FOR PI SYSTEM TO SPLUNK Command …optimate.net.au/splunk/Optimate Integrator for PI System... · 2018. 8. 22. · Revision No: 2.3 Effective Date: 31st July 2018