Nalyエンジニアリングノート：マシンcronロックと観測可能な公開パイプライン

要旨

TL;DRNalyはマシンcronを小さくも意図的なスケジューラとして使う。タイムスタンプ付きラッパーが公開と配信のジョブを起動し、 flock 重複実行を防ぎ、簡素化したランタイム起動処理で環境を明示し、外部ログと決定論的アーティファクトによってすべての実行を証拠に変える。中心的な主張は、同時実行性、再実行可能性、観測可能性をシェルの後付けではなく第一級の出力として設計すれば、単純なホストレベルの自動化も本番グレードになり得るということだ。

マシンcronはワークフローエンジンではない。記事が公開されたか、blobがアップロードされたか、データベース書き込みが冪等だったか、下流通知を安全に送れたかは知らない。役割はもっと狭い。予測可能な時刻に起き、コマンドを実行することだ。Nalyの設計はその契約を小さく保ち、その周囲に信頼性レイヤーを構築する。

有用なパターンは schedule -> locked wrapper -> explicit runtime -> observable artifact。Cronは時計を提供する。 flock は単一ホスト上の単一実行保護を提供する。ラッパーは環境読み込み、モード選択、ログ、終了コード規律を提供する。アプリケーションスクリプトはドメイン動作を提供する。アーティファクトディレクトリは監査証跡を提供する。

Naly内での位置づけ

Nalyの日次公開パイプラインはユーザー成長システムの一部だ。継続記事、配信チェック、スモークモード検証を支え、獲得またはリテンション価値を生むべき作業を扱う。スケジュール自体は意図的にNext.jsのリクエスト経路の外に置かれている。ページレンダリングが、今日の公開ジョブの存在を判断する責任を負うべきではない。

大まかに言えば、このパイプラインには5つの境界がある。

crontabエントリはスケジュールを含み、1つのラッパーを指定する。
ラッパーはrun idを作成し、fullまたはsmokeモードを選び、ログとアーティファクトの場所を結び付ける。
flock はクリティカルセクションを保護し、遅い実行が次の予定スロットと重ならないようにする。
TypeScriptランタイムは、明示的な環境読み込みとともに、チェックイン済みジョブを実行する。
ジョブは決定論的アーティファクト、ステータス、ログをリポジトリのランタイムツリーの外に書き込む。

外部ログルートの選択は重要だ。Nalyはランタイムログをリポジトリ外に置き、 NALY_LOG_ROOT=/tmp/logs をデフォルトとし、 /data/logs を永続環境向けに使う。これによりリポジトリはソースと永続的なプロジェクトメモリとして保たれ、ログはローテーション、保持、検査を前提にした運用名前空間に置かれる。

決定論的アーティファクトディレクトリは観測可能性のもう半分だ。ログ行は何が起きたかを示し、アーティファクトパスはどの出力が生成されたかを証明する。日次記事ジョブでは、アーティファクトディレクトリをジョブ名、日付ラベル、スケジュールスロット、run idでキー付けし、開始メタデータ、最終メタデータ、stdout/stderr、コンテンツ出力、スモーク出力、公開識別子を含めるべきだ。

技術的メカニズム

Linuxの crontab(5) 契約は直接的だ。crontabはcronデーモンに対し、一致する時刻にコマンドを実行させる指示を含む。マニュアルは本番で重要になる詳細も記している。cronは SHELL、 HOME、および LOGNAMEのような疎な環境を設定する。 CRON_TZ はスケジュール解釈を定義できる。コマンド内のパーセント文字はstdinに関する特別な挙動を持つ。夏時間の切り替わりは一致するジョブをスキップまたは重複させ得る。そしてcronエントリには正しい改行終端が必要だ。

だからこそNalyは、cron行をアプリケーションロジックではなく狭いランチャーとして扱う。コマンド部分は退屈であるべきだ。ラッパーを指し、インラインTypeScriptを使わず、壊れやすい引用符の曲芸をせず、アプリケーション動作はチェックイン済みスクリプトに任せる。

有用なメンタルモデルは次のとおり。

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) は同時実行プリミティブだ。マニュアルでは、シェルスクリプトからファイルロックを管理し、別コマンドの実行をラップするコマンドラインツールとして説明されている。デフォルトで排他ロックをサポートし、 -nでノンブロッキング取得、 -wで上限付き待機、 -Eで競合時終了コード、ラップされたコマンドの実行時には子プロセスの終了コード伝播をサポートする。これらの詳細だけで、スキップ、待機、または目に見える失敗というポリシーを符号化できる。

Nalyでは、ロックキーは冪等性ドメインに対応すべきだ。日次記事公開器と配信送信器が安全に独立実行できるなら、別々のロックが必要かもしれない。同じ日付ラベル付き出力を書き込む2つの記事公開器には同じロックが必要だ。ロック名は安定していてマシンローカルであるべきで、NFSやCIFSパスに保存すべきではない。 flock マニュアルが一部ネットワークファイルシステムでの限定的な挙動を指摘しているためだ。

その後の観測可能性は、実装が完全なコレクターより軽量であってもOpenTelemetryの形に従う。OpenTelemetryは、トレース、メトリクス、ログ、バゲージを含む、基盤活動を観測するために使われるシステム出力としてシグナルを定義している。cron公開では、トレースは実行ライフサイクル、メトリクスは所要時間と件数、ログはイベント記録、バゲージのようなコンテキストは各ステップに引き継がれるrun id、モード、スケジュールスロット、アーティファクトディレクトリ、バージョンメタデータだ。

文献が示すこと

最近のarXiv研究は、cron型自動化のリスクについて率直だ。AgrawalとJainによる2026年のレジリエントなELTパイプラインに関する論文は、cronジョブを含む場当たり的な取り込みスクリプトが、信頼を損なうサイレント障害とデータ欠落を生んだと報告している。彼らが提案する対処法は、より重いDAGオーケストレーション、不変の生履歴、状態ベースの依存関係管理だ。Nalyはすべての日次公開ジョブにその機構すべてを必要とはしないが、中心的な教訓は採用する。スケジュールされたパイプラインは、沈黙を疑わしくする永続状態を残さなければならない。

AlbuquerqueとCorreiaによる2025年のトレーシングとメトリクス設計パターンに関する研究は、観測可能性が断片化するほど分散システムの診断が難しくなると論じている。彼らは分散トレーシング、アプリケーションメトリクス、インフラメトリクスを別個の設計パターンとして分けている。Nalyのcronラッパーでは、それは実務的なルールに置き換わる。stdoutを唯一の証拠にしてはならない。公開実行には、実行トレース、アプリケーションレベルのカウンター、ホストレベルのコンテキストが必要だ。

Nalyの公開パイプラインにはAI支援コンポーネントが含まれるため、AgentTraceは関連性がある。AlSayyad、Huang、Palは、構造化ログをエージェントシステムのランタイム説明責任レイヤーとして位置づけ、非決定論的な実行を監査できるように運用上および文脈上の挙動を捕捉する。Naly版では私的な推論の漏えいを避けるべきだが、プロンプトクラス、ソースセット識別子、モデル/ランタイムメタデータ、安全モード、アーティファクトハッシュ、公開判断は記録すべきだ。

2026年5月に改訂されたOpsAgentは、インシデント管理の観点から同じ運用上の論点を補強している。メトリクス、ログ、トレースは、構造化され監査可能な記述に変換されると、より有用になる。これは小さなcronパイプラインにも当てはまる。目標はテキストをもっと集めることではない。次の診断をターミナルの記録を読むより速くすることだ。

設計上のトレードオフ

cronとファイルロックの組み合わせは意図的に控えめだ。ワークフロープラットフォームより可動部分が少なく、中央スケジューラデータベースもWeb UIも組み込みのDAGセマンティクスもない。ジョブが明確なランタイム契約を持つ単一マシンの日次公開器である場合、それは強みだ。ジョブが分散化し、依存関係が重くなり、高カーディナリティのリトライポリシーを必要とする場合、それは弱みになる。

ファイルロックも本質的にローカルだ。1つのホストと1つのファイルシステムにはよく合う。複数のマシンが同じ公開器を実行できる場合、データベースアドバイザリロック、キューリース、またはオーケストレーション状態の代替にはならない。Nalyの現在の用途はホストレベル自動化だ。公開がマルチランナーになるなら、ロック境界は共有された永続状態へ移すべきだ。

外部ログは利便性と運用衛生を交換する。ログをリポジトリに書き込むとローカルデバッグは簡単に感じるが、ソース管理を汚し、ローテーション問題を見えにくくする。 /tmp/logs または /data/logs を使うことで、どのログが使い捨てで、どのログが永続的かをシステムに宣言させる。

スモークモードも別のトレードオフだ。スモーク実行は安価で非破壊的でなければならないが、full実行と同じラッパー、ロック、環境読み込み、アーティファクトコードを通す必要がある。スモークモードが難しい部分を迂回するなら、それはプラセボになる。

決定論的アーティファクトにはディスク容量とクリーンアップ作業のコストがある。見返りは再実行可能性だ。オペレーターは2つの実行を比較し、正確な生成出力を見つけ、記憶から状態を再構築せずに、公開失敗と配信失敗を区別できる。

障害モード

最初の障害モードは重複だ。通常は3分で終わるジョブがやがて30分かかり、次のcron tickが別コピーを起動する。 flock がそれを防げるのは、すべてのエントリが同じロックキーを使い、クリティカルセクション全体にわたってロックを保持し、バックグラウンドの子プロセスが保護されたライフサイクルの外で継続しない場合だけだ。

2つ目の障害モードは誤解を招くスケジュールだ。夏時間の切り替わりはジョブをスキップまたは重複させ得る。フィールドステップ構文は読み間違えられ得る。パーセント文字はコマンドのstdinを変えることがある。改行の欠落はcrontabを部分的に壊すことがある。防御姿勢は、UTCスケジューリング、最小限のcronコマンドテキスト、ラッパーレベルのスケジュールスロット記録だ。

3つ目の障害モードは疎なランタイムのドリフトだ。cronの非対話シェルには、対話セッションと同じ PATH、Nodeバージョン、パッケージマネージャーパス、シークレット、ロケールがないかもしれない。Nalyの簡素化したランタイム起動処理はそれを明示する。必要な環境をラッパーで読み込み、その後チェックイン済みTypeScriptスクリプトを tsx経由で実行し、インラインコードは使わない。

4つ目の障害モードはサイレント成功だ。スクリプトは公開可能なアーティファクトをゼロ個しか生成していなくても、ゼロで終了できる。ラッパーは期待出力数、最終マニフェストの存在、公開識別子を完了チェックとして扱うべきだ。成功とは単に例外がないことではない。成功とは一貫した最終状態だ。

5つ目の障害モードは部分公開だ。データベース行はblobなしで存在し得る。blobは公開記事なしで存在し得る。配信メッセージは未公開URLを参照し得る。決定論的マニフェストは、prepared、committed、published、distributedの各状態を分離することで役立つ。

6つ目の障害モードは観測可能性そのものの失敗だ。ログルートが存在しない、いっぱいである、または書き込み不能である場合、ラッパーは不可逆な作業の前に失敗すべきだ。アーティファクトの最終化が失敗した場合、コンテンツステップが成功していても失敗した実行とすべきだ。監査証跡はプロダクトサーフェスの一部だからだ。

実装メモ

運用ジョブファミリーごとに1つのラッパーを使う。crontabエントリはスケジュール、タイムゾーン、ラッパーパスを表現し、ラッパーが他のすべての関心事を担うべきだ。それには run_id、 mode、 artifact_dir、 log_path、ロック取得、環境読み込み、ランタイム起動、最終ステータスが含まれる。

冪等性境界ごとに1つのロックを使う。日次記事ジョブは無関係な保守作業とロックを共有すべきではないが、同じ日次記事を公開し得るすべての経路は1つのロックを共有すべきだ。無制限のキューイングよりも上限付き待機またはノンブロッキング終了を優先し、その後、実行が実行されたのか、スキップされたのか、タイムアウトしたのかを記録する。

アーティファクトディレクトリを決定論的にする。実用的な形は job/YYYY-MM-DD/schedule-slot/run-id/だ。冒頭に started.json を置き、末尾に finished.json を置く。モード、日付ラベル、利用可能ならcommitまたはbuild識別子、パッケージ/ランタイムファミリー、所要時間、終了コード、出力数、公開識別子を含める。

smokeモードとfullモードを同じレールに乗せておく。smokeモードはdry-run名前空間に書き込み、公開配信を抑制できるが、それでもロックを取得し、環境を読み込み、必要に応じてDrizzleまたはNeonアクセスを初期化し、関連する場合はblob書き込みの前提を検証し、同じコンテンツ経路でmarkdownをレンダリングすべきだ。

プレーンファイルに書く場合でも構造化ログを使う。重要な各イベントには、job、run id、mode、schedule slot、artifact directory、durationまたはtimestamp、resultを含めるべきだ。これによりログファイルは後でクエリ可能になり、Nalyが後にcollectorを追加した場合でもOpenTelemetry型の取り込みと互換性を保てる。

現在のランタイムスタックはこのパターンに合っている。 tsx とTypeScriptはチェックイン済み運用スクリプトを支える。Drizzle ORMとNeonは永続的なデータベース状態を支える。Vercel Blobは永続的な公開アーティファクトを支える。 marked はmarkdownレンダリング経路を支える。Next.jsとReactは結果を表示するが、cronはリクエストライフサイクルの外にとどまるべきだ。

より広い教訓は、cronは記憶を求められない場合に限って安全だということだ。Nalyはcronにシステムを起こさせ、 flock にリスクのある領域を直列化させ、アーティファクトに何が起きたかを記憶させる。