Beta — under active development (
0.9.0). The tool works and its test suite runs green, but it has not reached a stable release: the configuration schema, the event shape and the CLI contract may still change between versions. Pin the version you deploy, and read the release notes before upgrading.
A cross-platform CLI tool that monitors business rules over data: it runs SQL against a database, evaluates an expression over the result, and emits an already-resolved event —matched or not, with severity and value— that an external observability stack consumes.
Atalaya evaluates business logic in SQL (where the relational model lives) and emits clean events instead of raw rows. It does not notify by itself: the alerting and visualization live in the external stack.
Supported engines: SQL Server and PostgreSQL. (MySQL and Oracle: extension points.)
Packaged as a .NET global tool. It is not published to a public package feed yet, so build it from source:
git clone https://github.com/dmonza/sincrum-atalaya.git
cd sincrum-atalaya
dotnet pack src/SincrumAtalaya.Cli -c Release -o ./artifacts
dotnet tool install -g --add-source ./artifacts SincrumAtalaya.Cli
The command is then available as atalaya. Building requires the .NET 10 SDK (pinned in
global.json); running the installed tool requires the .NET 10 runtime.
Each CI run also attaches the built .nupkg as a workflow artifact, so
dotnet tool install -g --add-source <folder> SincrumAtalaya.Cli works from a download too,
without building.
atalaya # one-shot: one cycle and exits (default)
atalaya --config other.yaml # use that file instead of default.yaml
atalaya --loop # continuous loop, as a service (alias: --continuous)
atalaya --loop --interval 30 # loop with ticks every 30s (default 60)
atalaya --help # -h / -? are aliases
atalaya --version # prints the version only, no banner
Without --config, it looks up default.yaml (or .yml) in the current directory.
- One-shot (default): meant for an external scheduler —system cron, systemd timer, Windows Task Scheduler— to invoke it periodically (typically every minute). Runs a cycle and exits; the exit code reflects the result.
- Loop (
--loop): the process stays alive as a service (systemd, Windows Service, or a container handling signals as PID 1). A runtime failure does not take it down: it is emitted and the cycle continues. OnSIGINT/SIGTERMit shuts down in order and exits with0.
One process per configuration file. Two processes over the same config —e.g. the external scheduler firing a run while a
--loopis still alive— overwrite the state file and cause double execution. The atomic write prevents a corrupt file, not double execution.
YAML. See samples/default.example.yaml for a complete,
commented example. Copy it to default.yaml and adjust it.
Structure: the data store identifier, the connection, emission destinations (appenders),
rules (rules), and optionally healthCheck and errors.
Beyond query, matchExpression, tracePattern, cron, and traceLevel, every rule requires
persistResults (true/false): whether the rows the rule's query returned are written to its
state file on each run. There is no default — omitting it is a validation error, so decide
explicitly per rule. See samples/default.example.yaml
for the full field list in context.
How the tool reaches the database is the highest-leverage security decision in the whole configuration. Two rules, both enforced or strongly recommended by the tool:
Atalaya executes the SQL you put in each rule's query field, verbatim, against the connection
you give it. Point it at a user that can only read. A read-only user bounds the blast
radius: a mistake in a rule's SQL, or a rule that someone did not vet, cannot modify or delete
data. Grant only SELECT on the tables the rules need, nothing more.
This also matches what the tool is for — it is a monitor, not a mutator. As a backstop, a
statement that returns no result set (a typical update, insert, or DDL) is rejected at
runtime as a configuration mistake. This is not a guarantee against a mutating statement
that does return a result set (e.g. an update ... output or ... returning clause) — the
tool does not parse the SQL to check that it is a select. The actual protection against data
mutation is the read-only database user above, which is why it is the first recommendation in
this section, not the runtime check.
The connection string supports environment-variable substitution with ${VARIABLE} syntax.
Put the password (and anything else sensitive) in a variable, not in the file:
dataStore:
dbms: sqlserver
connectionString: "Server=host,1433;Database=KB;User Id=atalaya_ro;Password=${ATALAYA_DB_PASSWORD};TrustServerCertificate=True;"# Linux / macOS
export ATALAYA_DB_PASSWORD='...'
# Windows (PowerShell)
$env:ATALAYA_DB_PASSWORD = '...'
- The committed file (
samples/default.example.yaml) carries no real secret, and the realdefault.yamlis gitignored. - An undefined variable is a validation error that names it — the tool does not start
with an empty password and does not fall back silently. This surfaces the mistake as "export
ATALAYA_DB_PASSWORD" instead of a confusing "login failed" later. - Never pass a secret as a CLI argument: arguments are visible in the process list and survive in shell history.
- Be mindful of what you emit: the
tracePatternis emitted verbatim, so a${result[0].password}ends up in the destination in plain text. The tool cannot tell a sensitive column from an ordinary one.
- Match (boolean, decides whether to emit) and metric (the value): variables bound
directly, without
${}. E.g.matchExpression: "metric > 10". - tracePattern (the message): interpolates with
${...}. E.g."There are ${metric} items". - Text literals: double quotes. The syntax is C#-like, where single quotes are a
single-character literal. Write
result[0].col != "text", and quote the whole expression in YAML with single quotes so it needs no escaping:'result[0].col != "text"'. - Columns by name:
result[0].kbName, orresult[0]["odd name"]for names that are not valid identifiers. There is no positional access (reordering the SQL must not silently change what the rule evaluates).
Quote dubious strings. YAML reads no, off, yes as booleans and unquoted versions as
numbers. In text fields (SQL, names) this does not bite because the target is a string, but it
is good practice.
${count} over a select * forces materializing every row. For large tables, write
select count(*) as c and use ${result[0].c} — and note that a select * over a table that
outgrows the rule's maxRows stops being a slow rule and becomes a failing one, by design.
Metric rules (always-true match) emit on every run: schedule them with a more spaced cron than alerts, because of volume in the external stack.
The healthCheck section emits a liveness heartbeat. It reports status, not just presence:
with checkConnection: true, a failed ping reports db_unreachable at error level.
Its interval defines the absence-detection window in the external stack: if it beats every 5 minutes, the absence (flatline) rule should shout if it does not see a heartbeat in ~12-15 min. Without a health check, a dead Atalaya looks identical to a quiet one.
The heartbeat also carries the process's own vitals, if you give it a tracePattern:
| Variable | Meaning |
|---|---|
status |
ok or db_unreachable |
uptime |
Seconds since the process started |
ticks |
Cycles completed since it started |
lastTickDuration |
Duration of the last completed cycle, in milliseconds |
managedMemory / workingSet |
What the tool allocated / everything the process holds, in bytes |
rulesOutOfService |
Rules that cannot run at all (see below) |
Without a tracePattern the beat keeps its previous wording exactly, so nothing downstream
changes for a deployment that does not ask for this.
ticks and lastTickDuration describe completed cycles — the beat runs inside a cycle, so
a process's first beat reports 0 for both.
Atalaya in --loop mode is meant to be a service. Four settings decide whether it is still
healthy on day ninety:
- Rotate your logs.
samples/log4net.configrolls by size with a bounded number of backups. Atalaya does not inspect your logging configuration and will not warn you if you remove the limits — a plain appending file grows until the disk is full. - Bound each rule with
maxRows(default10000) andqueryTimeout(defaults toconnectionTimeout). A rule's cost should be decided by you, not by how much the table has grown since you wrote it. - Size
--intervalagainst the arithmetic. A cycle's worst case is the sum of thequeryTimeouts of the rules due in it. Rules run one at a time, on purpose: running them concurrently would multiply load on the data store exactly when it is slow. - Watch the heartbeat's vitals. A
uptimethat keeps resetting means the process is crashing and being restarted; alastTickDurationcreeping toward your--intervalmeans cycles are about to stop keeping up; aworkingSetthat only ever grows is a leak.
A rule can fall out of service: its recorded last execution is in the future (the clock moved backwards, or a state file was copied from another machine), or its cron parses but the calendar never reaches it. Such a rule is skipped on every cycle — it has silently stopped watching, and to the external stack it looks exactly like a rule that simply never matched.
Atalaya reports it through the errors channel, with the scheduling phase, at the
cadence of that rule's own cron — an hourly rule is reported hourly, not on every cycle. It
is also counted in the heartbeat's rulesOutOfService for as long as it lasts, so the
condition stays visible even if a report is lost.
Returning to service emits nothing: the count simply drops. And because such a rule was skipped rather than run, it never affects the exit code.
errors defines where failures go (database down, bad SQL, evaluation error, emission
failure). Recommended in loop mode, where errors do not set an exit code — without it, a
failure only stays in the local diagnostic log and the external stack never learns of it.
Give it a different destination than the rules': if the business destination goes down, an emission failure still has a way out. If both point to the same broken destination, the failure falls to the diagnostic log.
Events are routed to named destinations (appenders). The supported type, log4net, writes
one line of text per event (suitable for Logstash + grok).
- The Atalaya appender delegates to a log4net logger (
config.logger). The real wiring of that logger —where it writes, in what format— lives in alog4net.configfile in the CLI's working directory. Seesamples/log4net.config. Without that file, log4net writes nowhere and Atalaya warns on the console. - File paths in the XML: a relative
<file>path is written to the working directory (next tolog4net.config) — Atalaya rebases it there, since log4net on its own would resolve it against the binary's installation directory. Absolute paths,${ENV}substitutions andlog4net.Util.PatternStringvalues are honored as written.
Part of the CLI contract:
| Code | Meaning |
|---|---|
0 |
Success (everything due ran without error; or ordered shutdown in loop). |
1 |
Configuration file not found. |
2 |
Configuration unreadable (syntactically broken YAML). |
3 |
Configuration invalid (content: duplicate ids, invalid cron/level/engine, mistyped section or key, undefined environment variable, invalid expression, etc.). |
4 |
Runtime error in at least one rule (SQL, evaluation, emission). |
5 |
Connection error to the data store. |
64 |
Argument-usage error (--interval without --loop, unknown flag). |
In one-shot, the code reflects the worst failure of the cycle (5 outranks 4). In
loop, runtime errors do not set a code; validations (1-3) still run at startup and, if
they fail, it exits without entering the cycle.
dotnet build
dotnet test tests/SincrumAtalaya.Domain.Tests # unit (no database)
dotnet test tests/SincrumAtalaya.Cli.Tests # CLI contract
dotnet test tests/SincrumAtalaya.IntegrationTests # requires Docker (SQL Server + PostgreSQL)
The integration tests spin up the engines in throwaway containers and run on Linux only.
MIT. See LICENSE.