Audit
Audit is the Code Effects library that records how your rules are used in production. Every time your application evaluates the live version of a Rule Repository rule, Audit keeps a record of that evaluation: which rule and which version ran, against which version of the source object, what the rule decided, which branch it took, the values it read, what it set, how long it took, who it ran for and the business case it belonged to. The records go into the Rule Repository's database, where people and AI agents can look at them later.
Audit is a separate library (CodeEffects.Rule.Audit, .NET Standard 2.0), licensed separately from the Rule Repository and the MCP server. This section explains how to add it to an application, how to configure it, and how to keep it healthy in production.
Why You Would Use It
- To answer "why did the system decide this?" Months later, a customer, an auditor or a regulator asks why an order was held or a claim declined. The record names the exact rule version that ran and the values it read, and the Rule Repository replays it step by step: which conditions were true, which branch ran, what it set. Together they give each automated decision full decision explainability: when it was made and for whom, how it was made (the rule and source versions, the evaluation options, the engine), and why (the values it read and the path it took through the conditions).
- To prove what ran. Rule versions are immutable, and a version that has ever been live can no longer be deleted (only the deletion of its whole source object removes it). Together with the record, that is a complete trail from a decision back to the logic that made it.
- To turn real cases into tests. Any recorded evaluation can be saved as a test with one click in the Rule Repository, so the next version of a rule is checked against what really happened.
- To see how rules are used. Success and error counts appear in the Stats tabs and grids of the Rule Repository, and the Live Evaluations grid lists every evaluation with its outcome.
- To let AI analyze production. The AI Assistant and AI agents connected through the MCP server can find, explain, summarize and analyze evaluations, grouped by the business values you choose to keep (analytics fields).
How It Fits in Your System
Rule Repository library Rule Repository database Audit library
(where people author rules) ----> rules, versions, live versions <---- loads live versions
evaluation records <---- writes records
(in your evaluating application)
- The rules get into the database only through the Rule Repository. Audit never writes rules. It reads the live versions and writes evaluation records, and nothing else.
- Audit runs where your application evaluates rules. That can be the same web application that hosts the Rule Repository, or a different one: an order service, a background worker, a Windows service, a function app. The Rule Repository, the evaluating application and the database may each run on a different server, as long as the evaluating application can reach the database.
- Audit plugs into the Rule Engine. You do not call a different evaluator. You load the rules through Audit, attach Audit to the engine's
EvaluationParameters once, and evaluate as you always do. An application that does not attach Audit pays nothing for it.
- Recording never slows a decision down by default. A record is appended to a local journal file in microseconds, and a background thread moves it into the database. If the database is down, records wait in the journal and are moved when it comes back. A strict mode that writes each record before the evaluation returns is available when a decision must not be acted on unless it is recorded (see Audit Settings).
What a Record Holds
| Recorded |
Details |
| The rule, the rule version and the source version |
The live versions at the time the rules were loaded. A reusable rule or an inline rule the evaluated rule called is part of the same record, with its own version. |
| The result |
True or false, or the error. If the rule threw an exception, its message is recorded and the exception is rethrown to your code unchanged. |
| The branch that ran |
For an execution rule: the THEN, which ELSE IF, the ELSE, or none. |
| The values the rule read |
Each member of the source object the engine actually read, with the value it got, including the collection items it read. Optionally every field the source declares (see Audit Settings). |
| What the rule set |
The values the branch that ran wrote through its setters. |
| Method calls |
The return value of every in-rule method call and the arguments of every action call. |
| The evaluation's options |
Precision, rounding, scope and short-circuit, the culture, the runtime and the engine's version. |
| Who and what for |
The correlation ID (your own ID of the business case, such as an order number), the user it ran for, and any tags you add (see Recording Evaluations). |
| Analytics values |
The values of the members you named as analytics fields, kept in a table of their own for analysis. |
| When and how long |
The time the evaluation ran and its duration. |
Audit does not record:
- Rules that were not loaded through Audit's
GetRules(..). An application that records with Audit loads every rule it evaluates through Audit.
- Evaluators over a FlexSource.
- Tests run in the Rule Repository. Tests have their own records.
Where People See the Records
- The Live Evaluations grid in the Rule Repository lists every recorded evaluation, newest first, with filters by correlation ID, rule, source object, status (ran or error), result, the user it ran for and the date.
- The Evaluation dialog opens one record and replays it through the same rule version, with the engine's tracer on, so people see every condition's result without the production run ever having paid for a trace.
- Save as Test... turns an evaluation into a test of the same rule version. It needs a permission of its own, because a test made this way copies production data.
- The Stats tabs of source objects, source versions, rules and rule versions show production success and error counts and an evaluations-over-time chart.
- The AI Assistant and the MCP server can find evaluations, explain one, summarize counts over time and analyze the analytics values.
The user guide's Audit section describes all of this from the user's side.
Requirements
- The Rule Repository's database, SQL Server 2012 or later, or PostgreSQL 14 or later, at the schema version this release of Audit needs. Audit uses the same database as the Rule Repository and the same scripts create it (see The Database).
- The Rule Repository, somewhere, to author the rules and make versions live. The application that records with Audit does not need to host the Rule Repository's user interface or reference its library.
- Any .NET application that can use .NET Standard 2.0 libraries: .NET 8 or later, or .NET Framework 4.7.2 or later. The packages are
CodeEffects.Rule.Audit, CodeEffects.Rule.Engine and the database provider package for your database (CodeEffects.Rule.Connection.SqlServer or CodeEffects.Rule.Connection.Postgres).
- A writable local folder for the journal (with the default settings). In containers, mount a volume for it.
Rules That Are Not Evaluated Through Audit
If your application evaluates rules from the repository but does not need records, load them with the Rule Repository's Context.GetRules(..) instead. It returns the same live versions as one ruleset, with no recording. See Rule Storage in Rule Repository and Live Versions and Approvals.
In This Section
- Recording Evaluations: the recorder, loading rules, attaching it to the engine, scopes, flushing and shutting down.
- Audit Settings: how records reach the database, the journal, what a record holds.
- Analytics Fields: choosing the business values agents can analyze.
- Problems and Monitoring: problem reports, statistics, the database check, moving a journal from another process, error codes.
The API reference for every type is in the CodeEffects.Rule.Audit namespace.