Note di ingegneria Naly: lock del cron della macchina e pipeline di pubblicazione osservabili

Abstract

TL;DRNaly usa il cron della macchina come uno scheduler piccolo ma deliberato: wrapper con timestamp avviano job di pubblicazione e distribuzione, flock impedisce esecuzioni sovrapposte, il bootstrap a runtime minimale rende esplicito l'ambiente, e log esterni più artefatti deterministici trasformano ogni esecuzione in evidenza. La tesi è che una semplice automazione a livello host può essere di livello production quando concorrenza, rieseguibilità e osservabilità sono progettate come output di prima classe anziché come ripensamenti shell.

Il cron della macchina non è un motore di workflow. Non sa se un articolo è stato pubblicato, un blob è stato caricato, una scrittura nel database è stata idempotente o una notifica downstream era sicura da inviare. Il suo compito è più ristretto: svegliarsi a un orario prevedibile ed eseguire un comando. Il design di Naly mantiene piccolo quel contratto e costruisce intorno a esso il livello di affidabilità.

Il pattern utile è schedule -> locked wrapper -> explicit runtime -> observable artifact. Cron fornisce l'orologio. flock fornisce protezione a esecuzione singola su un host. Il wrapper fornisce caricamento dell'ambiente, selezione della modalità, logging e disciplina degli exit code. Lo script applicativo fornisce il comportamento di dominio. La directory degli artefatti fornisce la traccia di audit.

Dove si colloca in Naly

La pipeline quotidiana di pubblicazione di Naly fa parte del sistema di crescita utenti: supporta articoli ricorrenti, controlli di distribuzione e verifica in modalità smoke per attività che dovrebbero creare valore di acquisizione o retention. La pianificazione stessa è intenzionalmente fuori dal percorso di richiesta Next.js. Il rendering di una pagina non dovrebbe essere responsabile di decidere che il job di pubblicazione di oggi esiste.

A livello generale, la pipeline ha cinque confini:

La voce crontab contiene la pianificazione e nomina un wrapper.
Il wrapper crea un run id, sceglie la modalità full o smoke e associa le posizioni di log e artefatti.
flock protegge la sezione critica affinché un'esecuzione lenta non possa sovrapporsi allo slot pianificato successivo.
Il runtime TypeScript esegue il job versionato nel repository con caricamento esplicito dell'ambiente.
Il job scrive artefatti deterministici, stato e log fuori dall'albero runtime del repository.

La scelta della radice esterna dei log conta. Naly mantiene i log runtime fuori dal repo, con NALY_LOG_ROOT=/tmp/logs per impostazione predefinita e /data/logs per gli ambienti persistenti. Questo preserva il repository come sorgente e memoria di progetto durevole, mentre i log vivono in uno spazio operativo progettato per rotazione, retention e ispezione.

La directory deterministica degli artefatti è la seconda metà dell'osservabilità. Una riga di log dice che cosa è successo; un percorso di artefatto dimostra quale output è stato prodotto. Per un job di articolo quotidiano, la directory degli artefatti dovrebbe essere indicizzata per nome del job, etichetta data, slot di pianificazione e run id, quindi contenere metadati iniziali, metadati finali, stdout/stderr, output di contenuto, output smoke e qualunque identificatore di pubblicazione.

Meccanismo tecnico

Il contratto Linux crontab(5) è diretto: un crontab contiene istruzioni per il demone cron affinché esegua un comando a un orario corrispondente. Il manuale documenta anche dettagli che contano in produzione: cron imposta un ambiente scarno come SHELL, HOME, e LOGNAME; CRON_TZ può definire l'interpretazione della pianificazione; i caratteri percentuale nei comandi hanno un comportamento speciale su stdin; le transizioni dell'ora legale possono saltare o duplicare job corrispondenti; e le voci cron richiedono una corretta terminazione con newline.

Per questo Naly tratta le righe cron come launcher stretti anziché come logica applicativa. La parte comando dovrebbe essere noiosa: puntare a un wrapper, non fare TypeScript inline, non fare fragili acrobazie di quoting e lasciare il comportamento applicativo agli script versionati nel repository.

Un modello mentale utile è:

cron tick
  -> wrapper starts with sparse runtime
  -> run_id and artifact_dir are assigned
  -> log files are opened under NALY_LOG_ROOT
  -> local file lock is acquired
  -> environment is loaded explicitly
  -> checked-in TypeScript job runs
  -> manifest, status, outputs, and exit code are finalized

flock(1) è la primitiva di concorrenza. Il suo manuale descrive uno strumento da riga di comando che gestisce lock su file da script shell, avvolgendo l'esecuzione di un altro comando. Supporta lock esclusivi per impostazione predefinita, acquisizione non bloccante con -n, attesa limitata con -w, exit code di conflitto con -E, e propagazione dell'exit code del processo figlio quando il comando avvolto viene eseguito. Questi dettagli bastano a codificare la policy: saltare, attendere o fallire in modo visibile.

Per Naly, la chiave di lock dovrebbe mappare al dominio di idempotenza. Un publisher di articoli quotidiano e un sender di distribuzione possono richiedere lock separati se possono eseguirsi in sicurezza in modo indipendente. Due publisher di articoli che scrivono lo stesso output etichettato per data richiedono lo stesso lock. I nomi dei lock dovrebbero essere stabili e locali alla macchina, non archiviati su percorsi NFS o CIFS, perché il manuale flock segnala comportamenti limitati su alcuni filesystem di rete.

L'osservabilità segue quindi la forma di OpenTelemetry anche quando l'implementazione è più leggera di un collector completo. OpenTelemetry definisce i segnali come output di sistema usati per osservare l'attività sottostante, inclusi trace, metriche, log e baggage. Per la pubblicazione via cron, il trace è il ciclo di vita dell'esecuzione, le metriche sono durate e conteggi, i log sono record di eventi, e il contesto simile a baggage è il run id, la modalità, lo slot di pianificazione, la directory degli artefatti e i metadati di versione portati attraverso ogni passaggio.

Cosa dice la letteratura

Il lavoro recente su arXiv è netto sul rischio dell'automazione in stile cron. L'articolo del 2026 di Agrawal e Jain sulle pipeline ELT resilienti riporta che script di ingestione ad hoc, inclusi job cron, producevano fallimenti silenziosi e lacune nei dati che erodevano la fiducia. Il rimedio proposto è un'orchestrazione DAG più pesante, cronologia raw immutabile e gestione delle dipendenze basata sullo stato. Naly non ha bisogno di tutta quella macchina per ogni job quotidiano di pubblicazione, ma adotta la lezione centrale: una pipeline pianificata deve lasciare stato durevole che renda sospetto il silenzio.

Il lavoro del 2025 di Albuquerque e Correia sui design pattern per tracing e metriche sostiene che i sistemi distribuiti diventano più difficili da diagnosticare quando l'osservabilità si frammenta. Separano tracing distribuito, metriche applicative e metriche infrastrutturali come design pattern distinti. Per i wrapper cron di Naly, questo si traduce in una regola pratica: non lasciare che stdout sia l'unica evidenza. Un'esecuzione di pubblicazione ha bisogno di un trace del run, contatori a livello applicativo e contesto a livello host.

AgentTrace è rilevante perché la pipeline di pubblicazione di Naly include componenti assistiti dall'AI. AlSayyad, Huang e Pal inquadrano il logging strutturato come un livello runtime di accountability per sistemi agentici, catturando comportamento operativo e contestuale affinché l'esecuzione non deterministica possa essere sottoposta ad audit. La versione di Naly dovrebbe evitare di divulgare reasoning privato, ma dovrebbe registrare classe del prompt, identificatori dei set di fonti, metadati modello/runtime, modalità di sicurezza, hash degli artefatti e decisioni di pubblicazione.

OpsAgent, rivisto a maggio 2026, rafforza lo stesso punto operativo dalla gestione degli incidenti: metriche, log e trace diventano più utili quando vengono convertiti in descrizioni strutturate e auditabili. Questo conta anche per una piccola pipeline cron. L'obiettivo non è raccogliere più testo; è rendere la prossima diagnosi più rapida della lettura di una trascrizione terminale.

Trade-off di progettazione

Cron più file lock è deliberatamente modesto. Ha meno parti mobili di una piattaforma di workflow, nessun database centrale dello scheduler, nessuna UI web e nessuna semantica DAG integrata. È un punto di forza quando il job è un publisher quotidiano su singola macchina con un contratto runtime chiaro. È una debolezza quando i job diventano distribuiti, pesanti di dipendenze o richiedono policy di retry ad alta cardinalità.

Anche i file lock sono locali per natura. Sono adatti a un host e un filesystem. Sono un pessimo sostituto di lock advisory sul database, lease di code o stato di orchestrazione se più macchine possono eseguire lo stesso publisher. L'uso attuale di Naly è automazione a livello host; se la pubblicazione diventa multi-runner, il confine di locking dovrebbe spostarsi nello stato durevole condiviso.

I log esterni scambiano comodità con igiene operativa. Scrivere log nel repo rende facile il debugging locale, ma inquina il controllo versione e nasconde i problemi di rotazione. Usare /tmp/logs o /data/logs costringe il sistema a dichiarare quali log sono eliminabili e quali sono persistenti.

La modalità smoke è un altro trade-off. Un'esecuzione smoke deve essere economica e non distruttiva, ma deve esercitare lo stesso wrapper, lock, caricamento dell'ambiente e codice degli artefatti dell'esecuzione full. Se la modalità smoke aggira le parti difficili, diventa un placebo.

Gli artefatti deterministici costano spazio su disco e lavoro di pulizia. Il ritorno è la rieseguibilità: gli operatori possono confrontare due esecuzioni, trovare l'esatto output generato e distinguere un fallimento di pubblicazione da un fallimento di distribuzione senza ricostruire lo stato dalla memoria.

Modalità di fallimento

La prima modalità di fallimento è la sovrapposizione. Un job che di solito richiede tre minuti prima o poi ne richiede trenta, e il tick cron successivo avvia un'altra copia. flock lo impedisce solo se ogni voce usa la stessa chiave di lock, mantiene il lock per tutta la sezione critica e non lascia accidentalmente che processi figli in background continuino fuori dal ciclo di vita protetto.

La seconda modalità di fallimento è una pianificazione fuorviante. Le transizioni dell'ora legale possono saltare o duplicare job. La sintassi field-step può essere interpretata male. I caratteri percentuale possono alterare stdin del comando. Una newline mancante può lasciare un crontab parzialmente rotto. La postura difensiva è pianificazione UTC, testo minimo del comando cron e registrazione dello slot di pianificazione a livello wrapper.

La terza modalità di fallimento è la deriva del runtime scarno. La shell non interattiva di cron potrebbe non avere lo stesso PATH, versione Node, percorso del package manager, secret o locale di una sessione interattiva. Il bootstrap a runtime minimale di Naly lo rende esplicito: carica l'ambiente richiesto nel wrapper, poi esegue script TypeScript versionati nel repository tramite tsx, non codice inline.

La quarta modalità di fallimento è il successo silenzioso. Uno script può uscire con zero pur producendo zero artefatti pubblicabili. Il wrapper dovrebbe trattare conteggi di output attesi, presenza del manifest finale e identificatori di pubblicazione come controlli di completamento. Il successo non è semplicemente assenza di eccezioni; il successo è uno stato finale coerente.

La quinta modalità di fallimento è la pubblicazione parziale. Una riga di database può esistere senza un blob, un blob può esistere senza un articolo pubblico, oppure un messaggio di distribuzione può fare riferimento a un URL non pubblicato. I manifest deterministici aiutano separando stati preparati, committed, pubblicati e distribuiti.

La sesta modalità di fallimento è il fallimento dell'osservabilità stessa. Se la radice dei log manca, è piena o non è scrivibile, il wrapper dovrebbe fallire prima di lavoro irreversibile. Se la finalizzazione degli artefatti fallisce, dovrebbe essere un run fallito anche se il passaggio di contenuto è riuscito, perché la traccia di audit fa parte della superficie del prodotto.

Note di implementazione

Usa un wrapper per ogni famiglia di job operativi. La voce crontab dovrebbe esprimere pianificazione, fuso orario e percorso del wrapper; il wrapper dovrebbe possedere ogni altra responsabilità. Questo include run_id, mode, artifact_dir, log_path, acquisizione del lock, caricamento dell'ambiente, avvio del runtime e stato finale.

Usa un lock per ogni confine di idempotenza. Un job di articolo quotidiano non dovrebbe condividere un lock con lavoro di manutenzione non correlato, ma ogni percorso che può pubblicare lo stesso articolo quotidiano dovrebbe condividere un lock. Preferisci attese limitate o uscite non bloccanti rispetto ad accodamenti illimitati, poi registra se un'esecuzione è stata eseguita, saltata o è andata in timeout.

Rendi deterministiche le directory degli artefatti. Una forma pratica è job/YYYY-MM-DD/schedule-slot/run-id/. Metti started.json all'inizio e finished.json alla fine. Includi modalità, etichetta data, commit o identificatore di build quando disponibile, famiglia package/runtime, durata, exit code, conteggi di output e identificatori di pubblicazione.

Mantieni le modalità smoke e full sullo stesso binario. La modalità smoke può scrivere in uno spazio dei nomi dry-run e sopprimere la distribuzione pubblica, ma dovrebbe comunque acquisire il lock, caricare l'ambiente, inizializzare l'accesso Drizzle o Neon quando necessario, verificare le assunzioni di scrittura blob quando rilevante e renderizzare markdown attraverso lo stesso percorso di contenuto.

Usa log strutturati anche quando scrivi file plain. Ogni evento importante dovrebbe includere job, run id, modalità, slot di pianificazione, directory degli artefatti, durata o timestamp e risultato. Questo rende i file di log interrogabili in seguito e mantiene il design compatibile con ingestion in stile OpenTelemetry se Naly aggiungerà più avanti un collector.

Lo stack runtime attuale si adatta a questo pattern. tsx e TypeScript supportano script operativi versionati nel repository. Drizzle ORM e Neon supportano stato durevole nel database. Vercel Blob supporta artefatti di pubblicazione durevoli. marked supporta percorsi di rendering markdown. Next.js e React presentano il risultato, ma cron dovrebbe restare fuori dal ciclo di vita della richiesta.

La lezione più ampia è che cron è sicuro solo quando non gli si chiede di ricordare. Naly fa svegliare il sistema a cron, flock serializzare la regione rischiosa, e agli artefatti ricordare che cosa è successo.