Analytics Fields
Analytics fields are the business values Audit keeps with each evaluation in a form that can be counted, grouped and totalled: the customer segment, the region, the order total, the price the rule quoted. With them, the AI Assistant and AI agents connected through the MCP server can answer questions such as "how many orders did the approval rule hold last month, by region?" or "what was the average quoted price for premium customers, week by week?", straight from production records.
Why You Need Them
Every evaluation record already holds the values the rule read, but in a form made for replaying one evaluation, not for analysing thousands. Scanning every record to group them by a value would be slow on the largest table in the database, and the databases the Rule Repository supports do not all have portable ways to query inside records. So you choose, in advance, the few values worth analysing, and Audit copies them into a table of their own, indexed for exactly that.
Without analytics fields, agents can still count evaluations by rule, result, status and period. Analytics fields add your business dimensions and measures.
Setting Them Up
Name the members in AuditSettings.AnalyticsFields, by their path from the evaluated object:
var settings = new AuditSettings
{
AnalyticsFields =
{
"Customer.Segment", // a dimension: a few distinct values
"Customer.Region", // a dimension
"Total", // a measure: a number to sum or average
"QuotedPrice", // a measure the rule's setter writes: read after the rule ran
"Status" // what the rule decided, when a setter writes it
}
};
var audit = new AuditRecorder(dbProvider, settings);
- A path names a property of the evaluated object (
Total) or of an object it holds (Customer.Region). A name is up to 128 characters with no spaces around it; any other name is refused when the recorder is created, with CE20006.
- The values are read when the evaluation ends. A value one of the rule's setters wrote is the value kept, so the outcome of an execution rule (a status, a price) can itself be analysed.
- The fields apply to every evaluation the recorder records. A path that does not exist on an evaluated object keeps nothing for that evaluation.
Some values worth analysing are not on the evaluated object at all: the channel the order came through, the store, the marketing campaign. Add them as tags of the scope you evaluate in:
using(audit.Scope(correlationId: order.Number, tags: new Dictionary<string, object>
{
["Channel"] = channel, // web, mobile, partner: the rule never reads it
["StoreId"] = storeId
}))
{
return evaluator.Evaluate(order, rules.Rule("Price the order")!.Id);
}
Tags are kept exactly as analytics fields are. A tag with the same name as an analytics field replaces the field's value.
What Is Kept
| The value |
Kept as |
| A number |
A number, rounded to 8 decimal places. A number too large for the column (28 digits, 8 of them decimals) is not kept. |
| A text, an enumeration (by its name), true or false, a date or a time |
Text, up to 256 characters |
| Null, an object or a collection |
Not kept |
The values go into the EvaluationValue table, one row per evaluation and name, indexed by name and text value and by name and number value. They are deleted with their evaluations: deleting a whole source object in the Rule Repository removes its evaluations and their values together.
How They Are Used
The evaluation_analyze tool, which the AI Assistant and the MCP server both offer (see AI Assistant vs the MCP Server), works on these values. It:
- Counts evaluations, or totals an analytics value (sum, average, lowest, highest), over a period.
- Groups them by up to two dimensions: the rule, the result, the status, or any analytics value.
- Breaks them down by day, week or month.
- Filters by analytics values.
- Returns totals only, never an evaluation's own values, and caps the answer at 500 groups.
A raw query tool over the database is deliberately not offered: it would bypass the user's permissions and expose personal data.
Choosing Good Fields
- Dimensions are values with a limited number of distinct values that people group by: segment, region, product line, channel, plan, a status. Grouping by a value that is different on every evaluation (an ID, a timestamp) tells nobody anything; use the correlation ID for that.
- Measures are numbers people total or average: an amount, a quantity, a quoted price, a score.
- Keep personal data out. An analytics value is copied into its own table and offered to AI agents for analysis. Do not name members holding names, addresses, tax or account numbers, or anything your data-protection policy keeps out of analysis.
- Keep the list short. Each field adds a row per evaluation to the largest table in the database and a little work to each evaluation. A handful of well-chosen dimensions and measures answers most questions.
- Fields apply from now on. Adding a field later does not fill it in for evaluations already recorded; agents analysing a period that started before the change see the value only on the newer evaluations.
- Several rules, one value. When agents total a value across several rules, each rule's evaluations keep the value as it was when that rule ran. The tool says so in its answer when it mixes rules.