CI call-site validation (scailog-ci)
scailog-ci is a build-time linter for your ScaiLog call sites. It statically
scans your source, checks that every call_site_id is constant, unique, and
well-formed, that messages carry no interpolated variables, and that every
pi() marker is accompanied by a subject — then fails the build if any of those
rules is violated. It can also push a call-site manifest to the server so drift
(a site emitting PI it never declared) shows up in operations.
scailog-ci ships with the base SDK and is zero-dependency: it uses only the
standard library (ast for extraction, argparse for the CLI, urllib for the
push), so it is available wherever pip install scailog has run — no extra
needed.
What it checks#
The extractor AST-scans Python source (*.py, recursively through directories)
for emit calls on a ScaiLog logger — log/Logger(...)/default_logger()
receivers, so plain stdlib logging calls are ignored — and the pi() markers
inside them. The validator (spec §11.2) then enforces these rules; each violation
is a build error unless noted:
| Code | Rule |
|---|---|
SITE_NON_CONSTANT |
call_site_id must be a string constant, never computed from runtime data |
SITE_INVALID |
call_site_id must match ^[A-Z0-9]+(-[A-Z0-9]+){2,}$ |
SITE_RESERVED |
call_site_id must not use the reserved SCAILOG- / AUTO- prefixes |
SITE_DUPLICATE |
call_site_id must be unique within the scanned service |
MESSAGE_INTERPOLATED |
the message must be a constant template — no f-string, %, or .format(); put variable data in fields |
PI_WITHOUT_SUBJECT |
a pi() marker requires subject= at the call site |
PI_NESTED |
a pi() value must be a scalar or flat list, not a nested structure |
check — fail the build#
Run check in your pipeline over the directories that contain call sites. It
prints each finding and exits non-zero if any error is present:
1 | |
1 2 | |
manifest — emit the call-site manifest#
manifest produces the JSON registry of your call sites for a given service and
version — each site with the PI types it declares and its source locations —
without contacting the server. Use it to inspect what would be pushed, or to
commit the manifest as an artifact:
1 | |
Add --owner <team> to stamp an owner on the sites. With no -o, the manifest
is printed to stdout.
push — upload the manifest to the server#
push validates first (unless you pass --no-check), then uploads the manifest
to POST /v1/sites/manifest:
1 | |
It refuses to push if validation finds errors. The server URL and API key are
resolved from SCAILOG_SERVER / SCAILOG_API_KEY, falling back to server_url
/ api_key in ~/.config/scailog/config.toml (override the config path with
SCAILOG_CONFIG); the default server is http://127.0.0.1:8080. Once pushed,
scailog sites --diff flags drift — sites observed emitting PI they never
declared, and AUTO-* sites that were never registered.