ESA Performance Management
Ericsson SNMP Agent 16.0

Contents

1About This Document
1.1Purpose
1.2Target Group
1.3Prerequisites
1.4Typographic Conventions

2
Introduction
2.1Overview
2.2Configuration Work Process
2.3Groups and Counters
2.4Data Sources
2.5Output
2.6Thresholds

3
Define a Counter
3.1Introduction
3.2Function Description
3.3Configuration Format
3.4Configuration Deployment
3.5Configuration Activation
3.6Examples

4
Define a Job
4.1Introduction
4.2Function Description
4.3Configuration Format
4.4Configuration Deployment
4.5Configuration Activation
4.6Examples

5
Define a Threshold
5.1Overview
5.2Function Description
5.3Configuration Format
5.4Configuration Deployment
5.5Configuration Activation
5.6Examples

6
Output SNMP
6.1Introduction
6.2SNMP MIB Format and Content

7
Output 3GPP XML File
7.1Introduction
7.2File Format and Content

8
Administration
8.1Log Files
8.2Backup and Restore

9
Command Line Interface
9.1Introduction
9.2Command: Counter Status
9.3Command: Reset Counter
9.4Command: Verify Data Source
9.5Command: Read Counter
9.6Command: Write Counter
9.7Command: View Job
9.8Command: View Threshold Alarms

10
Application Programming Interface
10.1Introduction
10.2Interface: Counter
10.3Interface: Job
10.4Interface: Threshold
10.5Interface: Output Reporter

Glossary

Reference List

1   About This Document

1.1   Purpose

The purpose of this document is to describe the system administration tasks for the Performance Management Agent (PMA) within the product Ericsson SNMP Agent (ESA). The document contains description about how to configure the PMA for gathering and publishing PM counters.

1.2   Target Group

The target group for this document is personnel responsible for administration of the ESA.

1.3   Prerequisites

It is assumed that the user of this document fulfils the following prerequisites.

1.4   Typographic Conventions

The typographic conventions used in this document are described in Reference [1].

2   Introduction

2.1   Overview

The configuration of the PM Agent (PMA) in the ESA is about setting up one or several of the following configurations.

Counter Definition

This is about defining all the counters to collect and made available by using the ESA PMA. Each counter is given a unique identity, a name and description, and, if available, the collection operation to perform to read data from the data source.

Job Definition (optional)

This is about defining the jobs, which are creating PM data files containing the collected counter data. Each job contains information about the counter group to publish and how often to publish it. If file output is not wanted, the job definition is not needed.

Threshold Definition (optional)

This is about defining counter thresholds, which will trigger alarms if thresholds are breached. When a counter is too high or low breaching a defined threshold, a SNMP alarm can be sent. If threshold alarms are not wanted, the threshold definitions are not needed.

Figure 1   An overview of the configuration needed to get the ESA PMA in operation.

The figure above gives an overview of the three configuration files needed for setting up the PMA.

At least one counter definition must be created to get the PMA into operation. It makes the PMA operational and also the counter is made visible on the SNMP interface, which means an OSS can read PM data using a SNMP get operation.

If a 3GPP XML file is wanted as output, a job definition must be created.

Finally, to get alarms when a threshold is reached on a counter, a threshold definition must be created. Please note that creating a threshold definition means that also the alarm to trigger must be defined. This is done as an alarm definition in the FM Agent, see Reference [3].

All configuration files are created using XML syntax.

2.2   Configuration Work Process

The ESA PMA is setup by executing the following work process:

  1. Define PM counter(s).

    Described in Section 3.

  2. If PM data output to file is wanted, defined job(s).

    Described in Section 4.

  3. If PM threshold alarms are wanted, define threshold(s).

    Described in Section 5.

2.3   Groups and Counters

A "Group" is a collection of counters. The group concept is used to give the possibility to group counters that are similar to each other or that in some way belong or have a relation to each other. From ESA point of view there is no restriction on how to use groups. To get the PMA into operation at least one group must be defined and within the group there must be at least one counter.

A "Counter" is a single value supporting only non negative numbers up to value 263-1. Each counter defined in the PMA must be connected to a group. The ESA as such does not care, does not know and does not understand what the counter is used for. The ESA is simply responsible for collecting the counter value and making it accessible for one or several OSS systems.

If the PMA gets a non-valid value, such as a string or a null value, the operation is considered erroneous and logged. The PMA does however not update the counter value in the PMA storage (as no new valid value was given) and continues to work as normal. If a data source is defined, the ESA will at each interval try to read PM data from the data source, no matter if the data collection operations are erroneous and/or give bad values.

A counter is either of the following two types:

2.4   Data Sources

2.4.1   Description and Definition

Each counter may have a data source from which the PMA is reading the counter value. The data source can be one of the following:

CSV The ESA may capture the value from any column from the last line in any CSV file.
JMX The ESA may capture the value from any JMX MBean in the system.
Script The ESA may capture the value returned from any script.

Please note that this implies that an executable of some kind must be created that returns the data of interest and the returned data must be a single value only.

SNMP The ESA may capture the value from any SNMP leaf from any SNMP agent on any IP address.
XML The ESA may capture a value from any XML element or attribute in any XML file using Xpath expressions.

The ESA has the possibility to support a multi counter script, which means a shell script can be executed to return more than one value in one operation. This is useful for large data sources. Instead of setting up the ESA to read the counters one by one, all the counters could be fetched at once.

2.4.2   Data Capturing Interval

For each data source defined there is a capture interval defined. The interval specifies at which interval the ESA shall read data from the data source. The interval is defined in seconds and the following values are allowed; 10 | 15 | 20 | 30 | 60 | 120 | 300 | 600 | 900 | 1200 | 1800 | 3600. Keep in mind that when using the lower values the ESA (and the system) is put into a more heavy load as the data collections occur more frequently.

The ESA is synchronizing the data capturing within an hour. That means that for example a 5 minute definition (300 seconds) captures the data at even 5 minute periods within an hour. Even though the PMA for example is started at 12:03:41 the PMA starts the capturing of data from the data sources at 12:05, 12:10, 12:15 and so on. The reasoning is also valid for intervals in seconds within a minute.

Note:  
Please note that if the system date or time is change, the ESA PMA needs to be restarted in order to prevent 3GPP reports with faulty date and time.

2.5   Output

The ESA supports the following outputs of the managed counters:

SNMP The counters are reported on the SNMP interface.

See Section 6.

XML The counters are reported to file in XML format following 3GPP standards.

See Section 7.

Custom The counters may be reported in any format, such as to an own file format or to a SQL database. This is possible by using the PM API for creating a customized output reporter.

See Section 10.5.

The SNMP interface is useful for OSS systems that needs PM data more close to real time. As the SNMP is a direct read operation the value is instantly collected from the ESA and can immediately be used by the OSS. However, keep in mind that the SNMP interface only holds the last value. Historical representation of PM data on SNMP is not available.

The XML file based format is useful for reporting tools, which are harvesting data from systems in a network and then processes the data for later use, such as for creation of reports. The files contain a history of data.

2.6   Thresholds

The ESA supports definition of thresholds on the PM data. When a counter rises above the threshold the ESA may send an alarm raise. And, when a counter falls below the threshold the ESA may send an alarm clear. By using thresholds in the PMA it means Fault Management operations are introduced in your system by setting up the PMA.

If the correlation of alarm raise and alarm clear is not wanted, an event can be sent instead. The event is in such case sent both when the threshold is breached and when the value falls back below the threshold. The event content indicates what has happened.

3   Define a Counter

3.1   Introduction

The counter definition is about creating unique counters that are used to represent levels, statuses and statistics in the system being monitored. The ESA is managing the counters by holding the PM data, updating the PM data and reporting the PM data.

3.2   Function Description

When setting up the PMA, the data sources holding the PM data of interest must be known. Then decisions must be taken about which counters are to be managed using the PMA. When the PM counters are known and the data sources are known, it is time for setting up the Counter Definition(s) in the PMA.

Each "counter" always belong to a "group". The group is used for two purposes; grouping similar objects together and for identifying output of data to file when setting up jobs. The "group identity" and "counter identity" are concatenated, such as GROUP:COUNTER, always a unique identity of each counter. They may never occur twice in the PM configuration. When a counter is created it is either concrete or abstract. A concrete counter is a single counter holding a single value. An abstract counter does not hold any values, but can be instantiated where each counter instance is holding a value.

Example 1   A counter grouping and identification example using concrete counters.

A counter group is created to hold a set of counters
related to hardware monitoring. The following group name
is defined.

   HARDWARE

The group of counters shall hold the values for CPU load,
Memory usage and Disk usage. The following counters are
defined.

   CPULOAD
   MEMUSAGE
   DISKUSAGE

The PMA will now hold three unique counters identified with
the following concatenated identities.

   HARDWARE:CPULOAD
   HARDWARE:MEMUSAGE
   HARDWARE:DISKUSAGE

The three counters are now defined and unique in the PMA.

Example 2   A counter grouping and identification example using abstract counters.

A counter group is created to hold three abstract counters
handling call counts for clients managed in the system. The
following group name is defined.

   CLIENT

The counter shall hold the value for number of call
attempts, number of successful calls and number of
unsuccessful calls. The following counters are defined.

   CALLATTEMPTS
   CALLSUCC
   CALLUNSUCC
   
The PMA will now manage three unique abstract counters
identified with the following concatenated identities.

   CLIENT:CALLATTEMPTS
   CLIENT:CALLSUCC
   CLIENT:CALLUNSUCC

When a new client CLIA is introduced in the system,
the PMA will manage three new counters where all are
instantiated from the abstract counter.

   CLIENT:CALLATTEMPTS:CLIA
   CLIENT:CALLSUCC:CLIA
   CLIENT:CALLUNSUCC:CLIA

With two additional clients CLIB and CLIC there will
be the following counters.

   CLIENT:CALLATTEMPTS:CLIB
   CLIENT:CALLSUCC:CLIB
   CLIENT:CALLUNSUCC:CLIB
   CLIENT:CALLATTEMPTS:CLIC
   CLIENT:CALLSUCC:CLIC
   CLIENT:CALLUNSUCC:CLIC

With only three defined abstract counters the PMA
now handles nine counter values in total.

A counter in the PMA may get the value from two different interfaces:

If the PMA is setup to fetch the data, the PMA is configured to do so with an interval. When the PMA is capturing data from a data source and it fails, the error is logged and the PMA continues to work as normal.

The PMA API is described in Section 10.

The collection of data from data sources work in two modes:

The multiple counter option should be used if a large number of counters are defined. The load on the ESA is kept lower by providing several counters at one capture operation than using one capture operation for each counter. This is also known as a "Collection of counters", not to be mistaken with the definition of "Groups".

3.3   Configuration Format

3.3.1   Overview

The figure below shows a high-level overview of the counter definition configuration file.

Figure 2   An overview of the XML objects used to create one or several PM counters in the ESA PMA.

One group contains one or several counters and/or one or several counter collections. The group is described by giving it a unique identity and a description. The counter is defined by a unique identity within the group and a description. If a data source in the system is holding the counter value, the data source is defined. If there is a script developed to return several counter values in one execution a counter collection can be defined. The collection is defined with a number of counters and the one and only data source. The details of the counter definition configuration file are found in the following chapters.

3.3.2   Group Definition

The following is an example of how to define a PM counter group:

<pmCntGroup active="yes">
  <identification>
    <groupId>MXDB</groupId>
  </identification>
  <description>
    <groupDescr>Message Transfer Database</groupDescr>
    <groupInfo>The counters show the database usage for
               message handling processes.</groupInfo>
  </description>

  ...more...

</pmCntGroup>

3.3.3   Single Counter

The following is an example of a defined counter within a defined group:

<cntDefinition active="yes" activeSnmp="yes" cntType="CC">
  <identification>
    <counterId>MYCOUNTERCSV</counterId>
  </identification>
  <description>
    <counterDescr>A description of the counter</counterDescr>
    <counterInfo>Additional counter information</counterInfo>
  </description>
  <preferences>

    ...counter value preferences...

  </preferences>
  <dataSource interval="60">

    ...data source definition...

  </dataSource>
</cntDefinition>

The XML element and attribute definitions:

3.3.4   Multiple Counter

The following is an example of a defined collection holding several counters as part of a defined group:

<cntCollection active="yes" activeSnmp="yes">
  <identification>
    <collectionId>MSGPROCCOLLECTION</collectionId>
  </identification>
  <cntDefinition cntType="CC">
    <identification>
      <counterId>MSGPROC1</counterId>
    </identification>
    <description>
      <counterDescr>Message process 1</counterDescr>
      <counterInfo>The number of messages processed by process
                   engine 1 in system XYZ.</counterInfo>
    </description>
    <preferences>
      ...counter preferences added here...
    </preferences>
  </cntDefinition>
  <cntDefinition cntType="CC">
    <identification>
      <counterId>MSGPROC2</counterId>
    </identification>
    <description>
      ...counter description added here...
    </description>
    <preferences>
      ...counter preferences added here...
    </preferences>
  </cntDefinition>
  <cntDefinition cntType="GC">
    <identification>
      <counterId>MSGPROC3</counterId>
    </identification>
    <description>
      ...counter description added here...
    </description>
    <preferences>
      ...counter preferences added here...
    </preferences>
  </cntDefinition>
  <dataSource interval="60">
    <script>
        <location>/opt/path/script</location>
    </script>
  </dataSource>
</cntCollection>

The example above defines three counters and the counter values are received by the one and only script defined, which means one script returns three values.

The XML element and attribute definitions:

3.4   Configuration Deployment

The counter definition configuration files are stored in the following directory.

{esa basedir}/conf/pmCounters/.

The format and syntax of the counter definition configuration file is verified with an XML Schema. The XML Schema file is found at the following location:

{esa basedir}/conf/pmCounters/pmCounter.xsd

Please note that the counter definition configuration directory is configurable. See Reference [2]. The directories described in this section are the default directories.

3.5   Configuration Activation

At PMA startup the PMA reads all the XML files available in the counter definition directory. If the files and file content are in correct format the content is loaded and activated. If not, the errors found are written to the PMA log file. The PMA is still started, but neglects the erroneous configurations. The PMA also supports runtime loading of configuration files, which means that changes made while the PMA is running will be detected by the PMA and it will reload the configuration without a restart.

3.6   Examples

Counter definition configuration file examples are found in directory:

{esa basedir}/conf/examples/

4   Define a Job

4.1   Introduction

The purpose of a job is to get the ESA PMA to produce PM output files in 3GPP format. Without a job definition, no files are produced. This simply means that if PM data on files are not needed, there is no need to define jobs.

4.2   Function Description

The job definition in brief is about creating a job with a unique identity, describing which counter group to publish (not a single counter) and, if needed, time statements for start time, stop time and the granularity period. The job configuration also provides the capability to replace the 3GPP XML format with an own output reporter, which means the output PM data can be written to a file in a format of own choice or maybe writing the data to a database. This requires creating an own reporter class in java.

4.3   Configuration Format

4.3.1   Overview

The figure below shows a high-level overview of the job definition configuration file.

Figure 3   An overview of the XML objects used to create one or several PM jobs in the ESA PMA.

A job definition configuration file contains a collection of job definitions.

Please note that only job identity and a counter group are mandatory parameters. The details of the job definition configuration file are found in the following chapters.

4.3.2   Basic Configuration

The following shows the format of a basic PM job configuration:

<jobDefinition active="data">
  <jobId>data</jobId>
  <groupId>data</groupId>
</jobDefinition>

The XML element and attribute definitions:

4.3.3   Customized Configuration

The following shows the format of a customized PM job configuration:

<jobDefinition active="data">
  <jobId>data</jobId>
  <groupId>data</groupId>
  <startTime>data</startTime>
  <stopTime>data</stopTime>
  <granularityPeriod>data</granularityPeriod>
  <outputReporterClass>data</outputReporterClass>
</jobDefinition>

The XML element and attribute definitions:

4.3.4   Advanced Configuration

The following shows the format of an advanced PM job configuration:

<jobDefinition active="data">
  <jobId>data</jobId>
  <groupId>data</groupId>
  <outputReporterClass>data</outputReporterClass>
</jobDefinition>

or

<jobDefinition active="data">
  <jobId>data</jobId>
  <groupId>data</groupId>
  <outputReporterGroup std3gppxml="data">
    <outputReporterClass>data</outputReporterClass>
  </outputReporterGroup>
</jobDefinition>

The XML element and attribute definitions:

4.4   Configuration Deployment

The job definition configuration files are stored in the following directory.

{esa basedir}/conf/pmJobs/.

The format and syntax of the job definition configuration file is verified with an XML Schema. The XML Schema file is found at the following location:

{esa basedir}/conf/pmJobs/pmJob.xsd

Please note that the job definition configuration directory is configurable. See Reference [2]. The directories described in this section are the default directories.

4.5   Configuration Activation

At PMA startup the PMA reads all the XML files available in the job definition directory. If the files and file content are in correct format the content is loaded and activated. If not, the errors found are written to the PMA log file. The PMA is still started, but neglects the erroneous configurations. The PMA also supports runtime loading of configuration files, which means that changes made while the PMA is running will be detected by the PMA and it will reload the configuration without a restart.

4.6   Examples

Job definition configuration file examples are found in directory:

{esa basedir}/conf/examples/

5   Define a Threshold

5.1   Overview

The purpose of using thresholds is to send SNMP notifications when the counters breach defined threshold levels.

5.2   Function Description

What must be defined is one or several threshold collections where each contains one or several threshold definitions. The threshold is defined by specifying which counter to monitor and how to monitor it by selecting either type "level" or "span". Finally, the alarm to trigger when the threshold is breached is also specified. Please note that the alarm to trigger must be defined in the FMA, see Reference [3].

The figure below shows a high-level overview of the threshold definition configuration file.

Figure 4   An overview of the XML objects used to create one or several PM thresholds in the ESA PMA.

The box "Counter" represents a single counter or a single or multiple counter instances. The threshold type specified is valid for all counters or counter instances specified.

The threshold types "level" and "span" are presented in Figure 5. The "level" indicates a level as a limit for what is ok (OK) and not ok (NOK). When the limit is breached an alarm is sent. The "span" has also limits, but there is an upper limit and a lower limit that indicates if the PM counter value is ok or not ok.

Also, there is an attribute in the configuration file allowing to invert the limits defined. Normally a limit is breached when the value rises above a limit, such as when a CPU load "is higher than 90%". In situations such as monitoring success rates the goal is to stay at 100%. If the success rate is below 95% an alarm should be sent. This scenario is setup using the invert option.

Figure 5   An overview of the threshold types available when threshold monitoring is setup in the PMA.

Even though the Figure 5 presents the limits as a single line, the configuration parameters allows the use of hysteresis; rising and falling limits. The Hysteresis operates as follows:

If the falling threshold is not defined, the falling threshold is the same as the rising threshold.

Figure 6 shows an example of how alarms are triggered when the type "level" is used. When the counter value rises above the rise definition an alarm is raised. If the optional fall definition is used, the alarm is cleared when the fall level is reached.

If the definition is inverted, the fall level becomes the alarm raise level and the rise level becomes the alarm clear level.

Figure 6   An example of using the threshold type “level” in the PMA.

Figure 7 shows an example of how alarms are triggered when the type "span" is used. When the counter value rises above the span high definition an alarm is raised. If the optional span high return definition is used, the alarm is cleared when the span high return level is reached. If the span high return level is not defined, the span high return level is set to the same as span high. The same rules applies for the low level definition within the span configuration.

If the definition is inverted, the span high/low return level becomes the alarm raise level and the span high level becomes the alarm clear level.

Figure 7   An example of using threshold type “span” in the PMA.

5.3   Configuration Format

5.3.1   Skeleton Format

The following is an example of how to define a PM threshold for a counter:

<threshold active="yes">
  <counter>
    <groupId>MYGROUP</groupId>
    <counterId>MYCOUNTER1</counterId>
  </counter>
  <type>

    ...type definition added here...

  </type>
  <output type="alarm">

    ...alarm definition added here...

  </output>
</threshold>

The following is an example of how to define a PM threshold for counter instances:

<threshold active="yes">
  <instance>
    <groupId>MYGROUP</groupId>
    <counterId>MYCOUNTER1</counterId>
    <instanceId>MYINSTANCE1</instanceId>
    <instanceId>MYINSTANCE2</instanceId>
    <instanceId>MYINSTANCE3</instanceId>
  </instance>
  <type>

    ...type definition added here...

  </type>
  <output type="alarm">

    ...alarm definition added here...

  </output>
</threshold>

The XML element and attribute definitions:

5.3.2   Type Format

The following are examples of how to define PM threshold types:

...
<type>
  <level invert="no">
    <rise>80</rise>
    <fall>70</fall>
  </level>
</type>
...

or

...
<type>
  <span invert="no">
    <high>60</high>
    <highRet>55</highRet>
    <lowRet>45</lowRet>
    <low>40</low>
  </span>
</type>
...

The XML element and attribute definitions:

5.3.3   Output Format

The alarm to send when a threshold is breached is defined according to descriptions in Reference [3]. However, the text that is part of the alarm is made flexible and dynamic by adding codes that are related to the actual threshold breach.

The following are examples of a defined alarm to send when a threshold is breached:

Format A) Same alarm texts for raise alarm and clear alarm

...
<output type="alarm">
  <moduleId>PERFORMANCE</moduleId>
  <errorCode>12</errorCode>
  <resourceId>1.1.1.2.3</resourceId>
  <text>Level threshold breached.</text>
  <origSourceIp>10.21.9.72</origSourceIp>
</output>
...

Format B) Differentiated texts for raise alarm and clear alarm

...
<output type="alarm">
  <moduleId>PERFORMANCE</moduleId>
  <errorCode>12</errorCode>
  <resourceId>1.1.1.2.3</resourceId>
  <textGrp>
    <textRaise>Threshold breached.</textRaise>
    <textClear>Threshold returned back to normal.</textClear>
  </textGrp>
  <origSourceIp>10.21.9.72</origSourceIp>
</output>
...

The XML element and attribute definitions:

The elements text, textRaise and textClear can include codes representing dynamic data that are added to the text string at the trigger time of an alarm. The following codes may be used:

@ig@ The identity of the group that the monitored counter belongs to.
@ic@ The identity of the counter being monitored.
@ii@ The identity of the instance being monitored.
@cv@ Current value of the counter. In other words, this is the value that breached the threshold definition.
@tlr@ A type "level" threshold and value for "rise".
@tlf@ A type "level" threshold and value for "fall".
@tsh@ A type "span" threshold and value for the high limit.
@tshr@ A type "span" threshold and value for the high return limit.
@tslr@ A type "span" threshold and value for the low return limit.
@tsl@ A type "span" threshold and value for the low limit.

Example text string using dynamic data:

...
  <text>Counter @ic@ in group @ig@ breached
        level @tlr@ (current value is @cv@).</text>
...

may lead to an alarm text looking like:

Counter SESSIONS in group MSGPROC breached
level 500 (current value is 508).

5.4   Configuration Deployment

The threshold definition configuration files are stored in the following directory.

{esa basedir}/conf/pmThresholds/.

The format and syntax of the threshold definition configuration file is verified with an XML Schema. The XML Schema file is found at the following location:

{esa basedir}/conf/pmThresholds/pmThreshold.xsd

Please note that the threshold definition configuration directory is configurable. See Reference [2]. The directories described in this section are the default directories.

5.5   Configuration Activation

At PMA startup the PMA reads all the XML files available in the threshold definition directory. If the files and file content are in the correct format the content is loaded and activated. If not, the errors found are written to the PMA log file. The PMA is still started, but neglects the erroneous configurations. The PMA also supports runtime loading of configuration files, which means that changes made while the PMA is running will be detected by the PMA and it will reload the configuration without a restart.

5.6   Examples

Threshold definition configuration file examples are found in directory:

{esa basedir}/conf/examples/

6   Output SNMP

6.1   Introduction

The PMA output to SNMP works according to the following guide:

6.2   SNMP MIB Format and Content

The SNMP MIB format and content is in more detail described in Reference [4].

7   Output 3GPP XML File

7.1   Introduction

The PMA output to XML file works according to the following guide:

7.2   File Format and Content

The 3GPP XML file format and content is in more detail described in Reference [5].

8   Administration

8.1   Log Files

The log files produced by the ESA PM Agent are described in Reference [2].

8.2   Backup and Restore

Backup of the ESA configuration, including the PM Agent configuration files, is described in Reference [2].

9   Command Line Interface

9.1   Introduction

During runtime the PM Agent will contain counters and counter values and the data is made available to the OSS using SNMP and 3GPP XML files. But, also the technician working locally with the system could benefit from looking at the data captured and produced by the PM Agent.

A number of CLI commands exist that makes the setup and configuration of the PM Agent easier. Also, they are useful when troubleshooting faults in the system by looking at the PM counters and PM threshold alarms.

The following CLI commands are available for the PM Agent:

pmcounterstatus
pmresetcounter
pmverifydatasource
pmreadcounter
pmjob
pmwritecounter
pmthresholdalarms

9.2   Command: Counter Status

9.2.1   Description

This command is used for checking the counter status. The command will return the status information indicating counter active or inactive.

9.2.2   Command Format

The command format:

pmcounterstatus <groupId> <counterId>

The command attributes are the following:

groupId The group identity of the group that the counter belongs to.
counterId The counter identity of the counter to check.

9.2.3   Command Output

The command gives the following output:

ACTIVE The counter is defined, loaded and active in the PM Agent.
INACTIVE The counter is defined and loaded, but made inactive, in the PM Agent.

If the counter specified does not exist in the counter definition configurations, the command gives the following output:

UNDEFINED The counter is not defined in the PM Agent.

9.3   Command: Reset Counter

9.3.1   Description

This command is used for resetting a counter value to its reset value. The reset value is entered in the PM Counter Definition configuration file. If there is no reset value given, the command will return an error message.

9.3.2   Command Format

The command format:

pmresetcounter <groupId> <counterId>

The command attributes are the following:

groupId The group identity of the group that the counter belongs to.
counterId The counter identity of the counter to reset.

9.3.3   Command Output

If the counter is successfully reset, the command does not give any output.

If the counter could not be reset, the command returns an error message.

9.4   Command: Verify Data Source

9.4.1   Description

This command is used for verifying that the defined data source for a counter or collection exists, is valid and working. The command should be used on the counter before including the counter in the PM Agent counter definition configuration directory.

Please note that this command can be executed with the PM Agent being shutdown.

9.4.2   Command Format

The command format:

pmverifydatasource <groupId> <counterId> <counterDefFile>

The command attributes are the following:

groupId The group identity of the group that the counter belongs to.
counterId The counter identity of the counter data source to verify.
counterDefFile The counter definition configuration XML file that contains the data source to verify.

9.4.3   Command Output

The command output shows the result from capturing the PM data from the data source itself. If it is verified that the command output shows the same value as what is found in the data source, the counter data source is correct.

In the examples below there is one counter collection MYCOLL with two counters named MYCNT1 and MYCNT2 within group MYGRP being defined in XML file cntdef.xml.

The following table holds example values for the counters in the example.

Table 1   

Group

Collection

Counter

Value

MYGRP

MYCOLL

MYCNT1

1234

MYGRP

MYCOLL

MYCNT2

2222

Example 1:
# pmverifydatasource MYGRP MYCNT1 cntdef.xml
MYGRP; MYCNT1; 1234

Example 2:
# pmverifydatasource MYGRP MYCNT2 cntdef.xml
MYGRP; MYCNT2; 2222

9.5   Command: Read Counter

9.5.1   Description

This command is used for viewing counter information and values and can be used to read both stored values (last read values) from the PM Agent and live values (real time values) being read from the actual data source.

9.5.2   Command Format

The command format:

pmreadcounter [<groupId> <counterId> [<options>]]

The command attributes are the following:

groupId The group identity of the group that the counter belongs to.
counterId The counter identity of the counter to view.
options The level of detail in the command output.

-d

Counter description.

-l

Counter live value. The value is fetched from the data source at the execution of the command. This value does not update the value of the counter.

-t

Counter timestamp. This indicates when the counter was last updated.

-v

Counter value.

9.5.3   Command Output

In the output examples below there are two values used. A stored value, which is the value currently processed by the PMA, and a live value, which is the value that is taken from the data source at the time of running the command. The following values are used in the examples:

The command provides two output formats.

The raw output is a list of counters with a header and a default set of columns separated with semicolons.

Example R1:
The following example prints all active counters in the PM Agent.
# pmreadcounter
Group id; Counter id; Instance id; Timestamp; Counter Value
<Group Id 1>; <Counter Id 1>; <Instance Id 1>; <Timestamp 1>; <Value 1>
<Group Id 2>; <Counter Id 2>; <Instance Id 2>; <Timestamp 2>; <Value 2>
<...>
<Group Id n>; <Counter Id n>; <Instance Id n>; <Timestamp n>; <Value n>

Example R2:
The following example prints all instances of the abstract counter MYCOUNTER in counter group MYGROUP in the PM Agent.
# pmreadcounter MYGROUP MYCOUNTER
Group id; Counter id; Instance id; Timestamp; Counter Value
MYGROUP; MYCOUNTER; <Instance Id 1>; <Timestamp 1>; <Value 1>
MYGROUP; MYCOUNTER; <Instance Id 2>; <Timestamp 2>; <Value 2>
<...>
MYGROUP; MYCOUNTER; <Instance Id n>; <Timestamp n>; <Value n>

The customized output allows the user to filter out a single counter or a set of counters as well as get only specific counter data instead of the default ones by using command options.

Example C1:
# pmreadcounter MYGRP MYCNT -t -v
2014-09-21 12:10:00; 3572

Example C2:
# pmreadcounter MYGRP MYCNT -v -l
3572; 4242

Example C3:
# pmreadcounter MYGRP MYCNT -t -v -l
2014-09-21 12:10:00; 3572; 2014-09-21 12:13:14; 4242

Example C4:
# pmreadcounter MYGRP MYCNT -d -l
Group: Feature Message Control
Counter: Number of Transactions per minute
4242

Example C5:
# pmreadcounter MYGRP MYCNT -d -l -t
Group: Feature Message Control
Counter: Number of Transactions per minute
2014-09-21 12:13:14; 4242

Example C6:
# pmreadcounter MYGRP MYCNT -d -t -l -v
Group: Feature Message Control
Counter: Number of Transactions per minute
2014-09-21 12:10:00; 3572; 2014-09-21 12:13:14; 4242

9.6   Command: Write Counter

9.6.1   Description

This command is used for updating a counter with a new counter value.

9.6.2   Command Format

The command format:

pmwritecounter <groupId> <counterId> [<instanceId>] <cntValue> [<timestamp>]

The command attributes are the following:

groupId The group identity of the group that the counter belongs to.
counterId The counter identity of the counter to update.
instanceId The instance identity of the instance to update.
cntValue The value to set for the counter or instance.

Datatype: Integer

timestamp The timestamp to use for the setting of counter value. If timestamp is not given, the timestamp is set to the timestamp for the operation.

Datatype: Date, 'YYYY-MM-DD hh:mm:ss'

9.6.3   Command Output

If the counter is successfully updated, the command does not give any output.

If the counter could not be updated, the command returns an error message.

9.7   Command: View Job

9.7.1   Description

This command is used for viewing counter jobs that are configured and managed in the PM Agent.

Please note that the command does not allow changes to be made to the jobs. The job configuration is done by editing the job definition configuration files. The command is a view into the ESA to show which jobs the ESA are processing.

9.7.2   Command Format

The command format:

pmjob [<jobId>] [<options>]

The command attributes are the following:

jobId The job identity of the job to view.
options The level of detail in the command output.

-v

Show all job details.

-s

Show jobs with a job state. This option requires one of the following states:


  • inactive(i)
    Show all jobs that are configured, but made inactive.

  • waiting(w)
    Show all jobs that are waiting to get started.

  • running(r)
    Show all jobs that are in operation.

  • stopped(s)
    Show all jobs that are finalized and ended.

9.7.3   Command Output

The command provides two output formats.

The list output is a list of jobs with a header and columns separated with semicolons.

Job id; Group id; Job State; Next Reporting Time
<Job Id 1>;<Group Id 1>;<Job State 1>;<Next Reporting Time 1>
<Job Id 2>;<Group Id 2>;<Job State 2>;<Next Reporting Time 2>
...
<Job Id n>;<Group Id n>;<Job State n>;<Next Reporting Time n>

The detailed output is a block of data for the job.

!---------------------------------------------------------
Job id                : <Job Id>
Group id              : <Group Id>
Job State             : <Job State>
Start Time            : <Start Time>
Stop Time             : <Stop Time>
Granularity Period    : <Granularity Period>
Standard 3GPP XML     : <3gpp Xml Output>
Output Reporter Class : 
   <Status 1> <Output Reporter Class 1>
   <Status 2> <Output Reporter Class 2>
   ...
   <Status n> <Output Reporter Class n>
Next Reporting Time   : <Next Reporting Time>
---------------------------------------------------------!

Example 1:
# pmjob

Job id; Group id; Job State; Next Reporting Time
JOBABC; GROUPSYSRES; RUNNING; 2014-05-05 05:05:00
JOBSYSTEM; GROUPDATABASE; WAITING; 2020-02-20 20:00:00
JOBXYZ; GROUPHW; INACTIVE;
JOBTEST; GROUPAPPL; STOPPED;

The example 1 shows that the ESA is maintaining four jobs, but only two are active. The third job in the list is intentionally made inactive and the fourth job in the list is finished as the configured stop time has been reached. The second job in the list is waiting to be started as it will start when the configured start time is reached.

Example 2:
# pmjob -s r

Job id; Group id; Job State; Next Reporting Time
JOBABC; GROUPSYSRES; RUNNING; 2014-05-05 05:05:00

The example 2 shows all jobs that are maintained by the ESA and in state RUNNING.

Example 3:
# pmjob JOBABC -v

!---------------------------------------------------------
Job id                : JOBABC
Group id              : GROUPSYSRES
Job State             : RUNNING
Start Time            :
Stop Time             :
Granularity Period    : 5
Standard 3GPP XML     : YES
Output Reporter Class :
Next Reporting Time   : 2014-04-08 12:05:00
---------------------------------------------------------!


The example 3 shows the details of job JOBABC, which reports counter values for the counter group GROUPSYSRES. The job is currently running and the next reporting time is 2014-04-08 12:05:00. The printout indicates granularity period 5 minutes, which means the job period started at 2014-04-08 12:00:00. There is no customized reporter class configured. The output will be default 3GPP XML Files.

Example 4:
# pmjob JOBSYSTEM -v

!---------------------------------------------------------
Job id                : JOBSYSTEM
Group id              : GROUPDATABASE
Job State             : WAITING
Start Time            : 2020-02-20 19:00:00
Stop Time             : 2020-02-30 12:00:00
Granularity Period    : 60
Standard 3GPP XML     : YES
Output Reporter Class :
   [ACTIVE]   com.company.myagent.reporter.ExampleReporter
   [INACTIVE] com.company.myagent.reporter.DummyReporter
Next Reporting Time   : 2020-02-20 20:00:00
---------------------------------------------------------!

The example 4 shows the details of job JOBSYSTEM, which reports counter values for the counter group GROUPDATABASE. The job is currently in waiting state since the job start time is set in the future, being 2020-02-20 19:00:00. With the granularity period of 60 minutes it means that the next reporting time is 2020-02-20 20:00:00, which is also stated in the printout. The job will automatically end after 10 days, meaning at 2020-02-30 12:00:00. The output will be default 3GPP XML files, but there are also customized reporter classes specified. One output reporter class is configured to be inactive though.

9.8   Command: View Threshold Alarms

9.8.1   Description

This command is used for viewing the active alarms that have been triggered by the PM Agent, which means the alarms that are triggered by getting PM thresholds being breached.

9.8.2   Command Format

The command format:

pmthresholdalarms

The command does not take any arguments.

9.8.3   Command Output

If there are no active PM alarms, the command output is only a heading.

# pmthresholdalarms

Active alarms:

If there are active alarms, the command output is a complete list of all active alarms. The output example below shows two active PM threshold alarms. The first one is a level threshold alarm and the second is a span threshold alarm.

# pmthresholdalarms

Active alarms:
!---------------------------------------------------------------
Module        : SYSRES
Error Code    : 1001
Resource Id   : 1.1.1.2.8
Timestamp     : Sun Sep 21 09:19:44 CEST 2014
Alarm Text    : CPU Load high. Breached level 90%. 92% 
                   reported.
Group Id      : SYSRESGRP
Counter Id    : CPULOAD
Current value : 95
Trigger value : 92
Limits        : alarm - 90 | 85 - clear
---------------------------------------------------------------!
!---------------------------------------------------------------
Module        : SYSRES
Error Code    : 2001
Resource Id   : 1.1.1.2.6
Timestamp     : Sun Sep 21 14:14:44 CEST 2014
Alarm Text    : Memory usage high, warning. Breached 70%. 74% 
                   reported.
Group Id      : MYGROUP
Counter Id    : MYAPICOUNTER
Current value : 79
Trigger value : 74
Limits        : clear - 92 | 90 - alarm - 70 | 68 - clear
---------------------------------------------------------------!

10   Application Programming Interface

10.1   Introduction

The PM API is used by java applications that need to handle counters. It contains the following interfaces and functions:

The following chapters describe the interfaces in more detail.

10.2   Interface: Counter

This interface gives the API user the possibility to manage PM counters from Java code. The API supports counter operations, such as reading counters and updating counters.

Interface: com.ericsson.esa.pmagent.rmi.ICounter

See javadoc in file esa-javadoc.jar located in {esa basedir}/lib.

Find code examples in file esa-sources.jar located in {esa basedir}/lib.

10.3   Interface: Job

This interface gives the API user the possibility to manage PM jobs from Java code. The API supports job operations, such as reading job definitions.

Interface: com.ericsson.esa.pmagent.rmi.IJob

See javadoc in file esa-javadoc.jar located in {esa basedir}/lib.

Find code examples in file esa-sources.jar located in {esa basedir}/lib.

10.4   Interface: Threshold

This interface gives the API user the possibility to manage PM thresholds from Java code. The API supports threshold operations, such as checking alarm status.

Interface: com.ericsson.esa.pmagent.rmi.IThreshold

See javadoc in file esa-javadoc.jar located in {esa basedir}/lib.

Find code examples in file esa-sources.jar located in {esa basedir}/lib.

10.5   Interface: Output Reporter

This interface gives the API user the possibility to replace the default 3GPP XML output format to an own customized output format. A few examples that could be wanted are "Store PM data in CSV files" and "Store PM data in a SQL database". The ESA itself does not need any software modifications. This is setup with configuration only.

Interface: com.ericsson.mmas.pm.reporters.Reporter

See javadoc in file esa-javadoc.jar located in {esa basedir}/lib.

Find code examples in file esa-sources.jar located in {esa basedir}/lib.

The ESA user must create a reporter class in java and the java class is added to the PMA job configuration. Instead of using the default 3GPP XML output, the PMA will send its output to the new reporter class and the reporter class will publish the output PM data in any way wanted. See Section 4.3, which shows how to configure the PM job to use an own reporter.

Keep in mind that using this customized reporter option makes the ESA loose control of the output data. The following must be handled by the reporter class.

In order to get the ESA PMA to load the reporter class the classpath must be updated with information about where to find the class file. This is done by editing the PMA esapma.vmoptions file.

The following procedure describes all the steps needed to link a new reporter class to the ESA and how to get it into operation.

  1. Stop the ESA PM Agent.
  2. Put the reporter class on the file system.

    The recommended location is {esa basedir}/lib.

  3. Open file {esa basedir}/bin/esapma.vmoptions for editing.
  4. Add the following line.

    -classpath/a {path}/{filename}.jar

    Example)

    -classpath/a /opt/esa/lib/MyPmReporter.jar

  5. Save the file.
  6. Create a job configuration that uses the reporter class.

    Example)

    <jobDefinition active="yes">
  <jobId>MYJOB</jobId>
  <groupId>MYCNTGROUP</groupId>
  <outputReporterClass>
    com.ericsson.myreporter
  </outputReporterClass>
</jobDefinition>

  7. Save the job configuration file named {filename}.xml in {esa basedir}/conf/pmJobs.
  8. Start the ESA PM Agent.

Glossary

Glossary
ESA Glossary of Terms and Acronyms, 0033-CSH 109 532

Reference List

[1] ESA Library Overview, DIRECTIONS FOR USE, 1/1553-CSH 109 532
[2] ESA Setup and Configuration, SYSTEM ADMINISTRATION GUIDE, 1/1543-CSH 109 532
[3] ESA Fault Management, SYSTEM ADMINISTRATION GUIDE, 2/1543-CSH 109 532
[4] ESA SNMP Interface for Performance Management, INTERFACE DESCRIPTION, 2/155 19-CSH 109 532
[5] ESA XML Interface for Performance Management, INTERFACE DESCRIPTION, 3/155 19-CSH 109 532


Copyright

© Ericsson AB 2004-2016. All Rights Reserved.

Disclaimer

No part of this document may be reproduced in any form without the written permission of the copyright owner.

The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing.

Ericsson shall have no liability for any error or damage of any kind resulting from the use of this document.

Trademark List
Ericsson is the trademark or registered trademark of Ericsson AB. All other products or service names mentioned in this document are trademarks of their respective companies.

    ESA Performance Management         Ericsson SNMP Agent 16.0