Datapoints

DATAPOINTS

As changes occur in the tracked schema, information is collected in the form of datapoints at various stages - or contexts - before being passed to the configured Collector. A datapoint has a globally unique name and code used to calculate its value. Code is called at the stage defined by the context of the datapoint. The available contexts are:

set

base

change

source

column

set (AKA changeset) datapoints are specific to an entire set of changes - insert/update/delete statements grouped in a transaction. Example changeset datapoints include changeset_ts and other broad items. base datapoints are logically the same as set but only need to be calculated once (instead of with every change set). These include things like schema and schema_ver.

change datapoints apply to a specific insert, update or delete statement, and range from simple items such as action (one of 'insert', 'update' or 'delete') to more exotic and complex items like <column_changes_json>. source datapoints are logically the same as change, but like base datapoints, only need to be calculated once (per source). These include things like table_name and source (source name).

Finally, column datapoints cover information specific to an individual column, such as column_name, old_value and new_value.

There are a number of built-in datapoints (currently stored in DBIx::Class::AuditAny::Util::BuiltinDatapoints which is likely to change), but custom datapoints can also be defined. The Auditor config defines a specific set of datapoints to be calculated (built-in and/or custom). If no datapoints are specified, the default list is used (currently change_ts, action, source, pri_key_value, column_name, old_value, new_value).

The list of datapoints is specified as an ArrayRef in the config. For example:

datapoints => [qw(action_id column_name new_value)],

Custom Datapoints

Custom datapoints are specified as HashRef configs with 3 parameters:

name

The unique name of the datapoint. Should be all lowercase letters, numbers and underscore and must be different from all other datapoints (across all contexts).

context

The context of the datapoint: base, source, set, change or column.

method

CodeRef to calculate and return the value. The CodeRef is called according to the context, and a different context object is supplied for each context. Each context has its own context object type except base which is supplied the Auditor object itself. See Audit Context Objects below.

Custom datapoints are defined in the datapoint_configs param. After defining a new datapoint config it can then be used like any other datapoint. For example:

datapoints => [qw(action_id column_name new_value client_ip)],
datapoint_configs => [
  {
    name => 'client_ip',
    context => 'set',
    method => sub {
      my $contextObj = shift;
      my $c = some_func(...);
      return $c->req->address; 
    }
  }
]

Datapoint Names

Datapoint names must be unique, which means all the built-in datapoint names are reserved. However, if you really want to use an existing datapoint name, or if you want a built-in datapoint to use a different name, you can rename any datapoints like so:

rename_datapoints => {
  new_value => 'new',
  old_value => 'old',
  column_name => 'column',
},