Skip to content

About

Cross-platform .NET CLI that monitors business rules over SQL data — runs your query, evaluates an expression over the result, and emits an already-resolved event (match, severity, metric) for your observability stack. SQL Server and PostgreSQL.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Sincrum Atalaya

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.)

Installation

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.

Usage

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.

Two deployment modes

  • 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. On SIGINT/SIGTERM it shuts down in order and exits with 0.

One process per configuration file. Two processes over the same config —e.g. the external scheduler firing a run while a --loop is still alive— overwrite the state file and cause double execution. The atomic write prevents a corrupt file, not double execution.

Configuration

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.

Rules — required fields

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.

Database access — best practices

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:

Use a read-only database user

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.

Keep credentials out of the config file — use environment variables

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 real default.yaml is 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 tracePattern is 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.

Expressions

  • 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, or result[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).

YAML quoting

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.

Efficiency note

${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.

Health check

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.

Running for days — what to configure

Atalaya in --loop mode is meant to be a service. Four settings decide whether it is still healthy on day ninety:

  1. Rotate your logs. samples/log4net.config rolls 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.
  2. Bound each rule with maxRows (default 10000) and queryTimeout (defaults to connectionTimeout). A rule's cost should be decided by you, not by how much the table has grown since you wrote it.
  3. Size --interval against the arithmetic. A cycle's worst case is the sum of the queryTimeouts 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.
  4. Watch the heartbeat's vitals. A uptime that keeps resetting means the process is crashing and being restarted; a lastTickDuration creeping toward your --interval means cycles are about to stop keeping up; a workingSet that only ever grows is a leak.

Rules that stop being scheduled

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 section

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.

Emission (log4net)

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 a log4net.config file in the CLI's working directory. See samples/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 to log4net.config) — Atalaya rebases it there, since log4net on its own would resolve it against the binary's installation directory. Absolute paths, ${ENV} substitutions and log4net.Util.PatternString values are honored as written.

Exit codes

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.

Development

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.

License

MIT. See LICENSE.

About

Cross-platform .NET CLI that monitors business rules over SQL data — runs your query, evaluates an expression over the result, and emits an already-resolved event (match, severity, metric) for your observability stack. SQL Server and PostgreSQL.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages