validateCheckpoint.jar

The validateCheckpoint.jar program analyzes a MATRIXX checkpoint, detects any errors in the database, and produces a validation report listing internal database statistics and any errors found. This information can be sent to a MATRIXX representative to help troubleshoot database errors.

The validateCheckpoint.jar program analyzes checkpoint data for the subscriber and activity databases, including analyzing base and tenant pricing data like balance updates and product offers. For example, the program checks that purchased offers (catalog items) in the subscriber database have the same set of required balances as those defined on the product offer in pricing, and generates a warning on a mismatch.

Note: The version of the system that created the checkpoint must match the version of validateCheckpoint.jar. For example, if the checkpoint is from a system at release 5260, the checkpoint must also be from release 5260.

After loading the data, validateCheckpoint.jar performs the following checks:

Self consistency — The program checks that each database object has all the required fields and that each object is self-consistent.
Object references — For all cross references between objects, the program checks that:
- The referenced object exists and it is the correct object type.
- For bi-directional references, the referenced object points back to the referring object.
Resource references validation:
- The program checks intra-object resource references for validated inter-object dependencies. For example, the ResourceIds within a wallet that identify the required subscriber balances for a purchase offer are analyzed to ensure that they are correct.
- validateCheckpoint.jar analyzes the PurchasePackageResourceId parameter set in MtxPurchasedOffer to verify the offer owner has an MtxPurchasePackage in the PurchasePackageArray with that PurchasePackageResourceId.

After completing the validation checks, the program returns a status line like one:

Analysis complete. Errors=0 Warnings=754 Quarantined=28

and generates the validateCheckpoint log file with details. If the program found any errors, they are listed in the log file in order of severity.

Note: If validateCheckpoint.jar is run on the standby MATRIXX Engine checkpoint during a database upgrade, the validation produces warnings that TriggerTime and NextMaintenanceTime values are overdue for each subscriber/group in the database. These are typical artifacts of the upgrade process. The warnings can be ignored.

In addition, validateCheckpoint.jar can report statistics for the checkpoint to aid in analyzing operational issues. If statistics are enabled:

For each Catalog Item/ Bundle/Product defined in the Pricing database, validateCheckpoint.jar shows:
- How many purchased offers refer to this element, that is, the total number of references.
- How many objects (Subscriber, Group, and Device) have purchased offers that refer to the offer.
Note: If a single subscriber has purchased two instances of the same catalog item, the total count is 2 and the object reference count 1.

The following example shows pricing statistics for base pricing:

Pricing Statistics For Base Pricing File
===============================================
                  Total              Ref Object Count
   CatalogItem  References  Subscriber       Group      Device
  ------------  ----------  ----------  ----------  ----------
             1           0           0           0           0
             2           0           0           0           0
             3           0           0           0           0
             4           0           0           0           0

The next example shows pricing statistics for one tenant:

Pricing Statistics For Tenant With Profile Id 4
===============================================
                  Total              Ref Object Count
   CatalogItem  References  Subscriber       Group      Device
  ------------  ----------  ----------  ----------  ----------
             1          10          10           0           0
             2          10          10           0           0
             3          10          10           0           0
             4           0           0           0           0

If there are multiple tenants, statistics are shown for each tenant.

For each balance defined in the Pricing database, validateCheckpoint.jar shows the number balance instances present in the database and the number of objects owning an instance.

                  Total        Ref Object Count
       Balance  References  Subscriber       Group
  ------------  ----------  ----------  ----------
         21007           0           0           0
         21008      100000      100000           0
         21009           0           0           0
         21011           0           0           0
         21012           0           0           0
         21019      100000      100000           0

Note: If a single subscriber has purchased two instances of the same balance, the total count is 2 and the object reference count 1.

For each life cycle state defined in the Pricing database, it shows the number of objects that are in that state, broken down by device, user, subscriber, and group. This example shows output for devices and users:

Status Lifecycle Statistics
===========================
 
----  Device  ----
Status    RefCount  Description
------  ----------  -----------
     1      100000  Active
     2           0  Temporary Suspended
     3           0  Temporary Disconnected
     4           0  Disconnected
     8           0  Quarantine

----  User  ----
Status    RefCount  Description
------  ----------  -----------
     1       20000  Active
     2           0  Inactive

validateCheckpoint.jar returns the number of purchased catalog items in each offer state. For example:

Offer Lifecycle Statistics
===========================

----  (Default) Offer Lifecycle ID=1 (MTX)  ----
Status  RefCount  Description
------  --------  -----------
     1     59995  active
     2         0  in_cancellation
     3         0  inactive
     4         0  suspended
     5         0  pre_active
     6         0  grace
     7         0  recoverable
     8         0  suspended_grace
     9         0  suspended_recoverable
    10         0  suspended_pre_active

----  Offer Lifecycle ID=2 (Foo) ----
...

The next example shows tenant statistics for base pricing for one tenant:

Tenant : (TenantId_1)
TenantProfileId  RefCount  Description
---------------  --------  -----------
              1         0  Tenant 1 description (Group)
              1         0  Tenant 1 description (User)
              1         0  Tenant 1 description (Subscriber)
              1         0  Tenant 1 description (Device)
              1         0  Tenant 1 description (Account)

If there are multiple tenants, statistics are shown for each tenant.

Syntax

java -jar validateCheckpoint.jar [-d |-h |-v |-w threads | 
 -p configFilename | -s] checkPointFolder [outputFile]

Options

-d, --debug: If specified, then extra messages are printed to help in debugging this script.
-h, --help: Returns information about the script.
-v, --verbose: Runs the script in verbose mode and returns more details as standard output.
-w threads, --workers=threads: Specifies the number of worker threads the program uses to process the checkpoint files. If you do not specify this option, the program uses the default value of 4.
-p -configFilename, --props configFilename: Specifies a configuration file to use.

checkPointFolder: The full path for the directory containing the MATRIXX checkpoint files to be analyzed.
-s, --stats: Runs the script in statistics mode and returns pricing statistics.
outputFile: The name of the file to which to write the validation report messages. If you do not specify this option, the program writes output to a file named validateCheckpoint_datetime.log, where datetime is the current date and time in YYYYMMDD_hhmmss format. If ouputFile exists already, then output is appended to the existing file.

Properties Settings for validateCheckpoint

By default, validateCheckpoint.jar looks for a file called validateCheckpoint.yaml in:

The /opt/mtx/conf directory.
The current working directory.

The validateCheckpoint.yaml file specifies the following properties:

Verbose: [ "true" | "false" ]

Specifies whether the script runs in verbose mode and returns more details as standard output. The default setting is Verbose: "false". Code Verbose: "true" to run the script in verbose mode.

Debug: [ "true" | "false" ]

Sets the debug flag. The default is Debug: "false". To specify printing of extra messages to help in debugging the script, code Debug: "true".

NumWorkers: number

Specifies the number of worker threads the program uses to process the checkpoint files. The default value is 4.

RequiredBalanceMode: [ "strict" | "relaxed" | "disabled" ]

An offer can specify required balances. These are created at purchase time and an association is persisted in the database state. This is used for pricing constructs such as "charge only required balances."

As pricing models evolve, new required balances can be added; however, existing subscribers do not have these balances. Typically, the new required balances are provisioned using another offer, but the relationship necessary for "charge required balances" is not present. The RequiredBalaceMode property specifies whether Balance Mode Checking occurs, and if so, how strict the checking is. The following modes are supported:

"strict" — (default setting) A warning is issued if an offer requires a balance and no appropriate balance instance is found in the offer required balance array.
"relaxed" — A warning is issued if an offer requires a balance and there is no instance of a balance. type in the wallet.
"disabled" — No warnings are generated.

RequiredBalanceIgnore: balance_template_ID1,balance_template_ID2, balance_template_IDn

If required balance checking is enabled (strict or relaxed), specifies a list of balance template IDs for which warnings associated with the associated balances are ignored. The list of balance template IDs is a comma- separated list. For example,

RequiredBalanceIgnore:
							123,456

specifies that warnings for balances associated with balance template IDs 123 and 456 are ignored.

PricingStats: [ "true" | "false" ]

If the PricingStats flag in enabled (PricingStats: "true"), more information is generated on the usage of various pricing options within the checkpoint. The default value is PricingStats: "false".

AggregationWarnCount: count

Generates a warning when a single AggregationSet object has more than the specified number of aggregation objects associated with it.

BalanceWarnCount: count

Generates a warning when a single wallet object has more than the specified number of balance structures associated with it. The balance could be a single simple or periodic balance or a meter. The default is 100. To avoid these warnings, set count to a large number, such as 1000.

DeviceAccessWarnCount: count

Generates a warning when a single device object has more than the specified number of device access objects associated with it.

DeviceWarnCount: count

Generates a warning when a single subscriber object has more than the specified number of device objects associated with it.

PurchasedOfferWarnCount: count

Generates a warning when a single subscriber or group has more than the specified number of purchased offers. The default is 50. To avoid these warnings, set count to a large number, such as 1000.

SessionWarnCount:count

Generates a warning when a single device has more than the specified number of sessions (Charging, Policy, and Voice) associated with it. The default is 10. For example, SessionWarnCount: 10 specifies that a warning is generated when a device has more than 10 sessions associated with it.

TriggerWarnMins: triggertime_limit

The time limit threshold, in minutes, for returning a warning that processing a subscriber or group object is blocking recurring (background) processing. The triggertime_limit starts running when the checkpoint is created, and a warning is issued if the object has not been not modified by the time it runs out. These warnings usually indicate that you must inspect the object and make changes to fix a issue. The default is 720 minutes (12 hours).

ExtraActiveSubscribersDays: number_of_active_subscribers_days

If this optional property is specified, reports the number of active subscribers during the specified number of days and the number of active subscribers in the last 90 days. The default is 0. When this property is not set or is set to 0, validateCheckpoint.jar reports the number of active subscribers in the last 90 days.

For more information about the MATRIXX environment variables, see the discussion about container directories and environment variables in MATRIXX Installation and Upgrade.