Skip to content

Extend the mon schema

This page describes how to extend the KX Sensors mon schema, either by adding monitoring for a new custom process or by adding columns to an existing process's monitoring table.

KX Sensors lets you extend the mon schema in two ways: add monitoring statistics for a non-core or custom process that has none by default, or add new columns to the monitoring table of a process that is already monitored. The sections below cover each case.

Monitor a custom process

All core KX Sensors processes are supplied with monitoring tables by default. If you want to capture monitoring statistics for non-core or custom processes, follow these steps:

  1. Create a database schema table of type monitor defining the data that you want to capture.
  2. If your table contains columns custom to your process, initialize them during your process's start-up sequence.
  3. Implement logic to populate the custom values that you support; you can do this in, for example, a routine called sample in your code. The application reporting utilities in src/mon/sample.q may be helpful in updating these properties. It may also be instructive to look at how other processes manage their custom monitoring statistics.
  4. Set up your monitoring parameters for the new process/table in config/mon.yaml. It is through this configuration object that your sampling routine is attached to the execution of your process.

Create a table schema for the process

There are two types of process monitoring tables in KX Sensors: process and non-process. KXS process tables relate to a specific service class; by default, these tables require a set of standard columns that apply to all service classes. The logic for computing values for these columns is predefined in src/mon/sample.q. If you want to override the behavior of these columns, you can do so by overriding the sampling function for that particular column within your own code.

Most monitoring tables are process tables. A few non-process tables exist to cover entities such as the system overview, server summary, volume state, interprocess communication queues, and feed state. For non-process tables, the only requirements are the presence of the columns proc and ts.

The following table compares the standard columns for process and non-process monitoring tables:

Process table columns Type Non-process table columns Type
proc symbol proc symbol
ts timestamp ts timestamp
procStartTS timestamp
procState short
memUsed long
memHeap long
memPeak long
memMax long

Set up your monitoring table in config/mon.yaml

In config/mon.yaml, you set up your process-specific table handling rules. For each entry, you specify whether the table is related to a process, the sampling function, the key columns, the columns that require a daily total and the columns that will be reset to zero at the end of each interval/day.

For example, the following excerpt from config/mon.yaml configures several processes:

mon:
  values:
   - process: agg
     table: MonAgg
     isProcTbl: true
   - process: dbw
     table: MonDBW
     isProcTbl: true
   - process: dbc
     table: MonDBC
     isProcTbl: true
     sampleFn: .dbc.sample
   - process: sdl
     table: MonFeed
     isProcTbl: false
     sampleFn: .hadl.sample_
     keyCols: feed
     dailyTotCols: [ mbResets:totMbResets, mbTerms:totMbTerms, mbExps:totMbExps, replLoss:totReplLoss ]
     intvResetCols: [ msgs, segs, wms

The following table describes the columns available in config/mon.yaml:

Column Name Description Example
process The process name. Can be blank for all processes or the name of a specific process or a service class.
table The table name. Can be a schema group, a table category or a specific table name.
isProcTbl If the monitoring table is specific to that process, set the flag to true and ensure that the table contains the mandatory process-related columns. If you are monitoring a message stream, inter-process communication or some other non-process table, set this flag to false. The only mandatory columns in the table are proc (symbol) and ts (timestamp). true
sampleFn Placeholder for custom logic for properties specific to the service class or table. This sampling function will run at the monitoring report frequency defined in .cfgp.monFreq. .rp.sample
keyCols In this column, you define any extra columns apart from proc that the table should be keyed on.
dailyTotCols The column or columns for which daily totals are calculated by the monitoring framework. reqs:totReqs,reqErrs:totReqErrs
invtResetCols The column or columns that will be reset to zero at the end of each monitoring interval. msgs,readings
dailyResetCols The column or columns that will be reset to zero at EOD. wms,wmRows,msgs,rows

Extend monitoring for an existing process

You extend monitoring for an existing process by adding the appropriate columns to your monitoring table. In the following example, the statistics reported by RDB are extended:

MonRDB:
  m-meta: schema.yaml
  description: This schema extends the statistics reported by RDB processes
  columns:
   - name: sensor
     type: integer
     description: Count of sensors updated in interval
   - name: event
     type: integer
     description: Count of events received in interval

To add new columns to an existing process's monitoring table:

  1. Navigate to the schema directory.
  2. Copy any one of the MonXXX.yaml files from the core directory and assign your copy a new name (for example, MonRDB).
  3. Enter a description for your new monitoring table.
  4. Remove unnecessary content from the file.
  5. Enter the additional columns and their corresponding column types that you want to publish. You do not need to include columns already present in the base table.
  6. Assign a description to each new column.
  7. Save your changes and move your YAML file to the appropriate override config directory from which it will be deployed.

Next steps