4.4 ログ・ファイルを使用したモニタリング

SQLclデーモンには、ジョブ実行イベント、スケジューラ・ライフサイクル・イベントおよび構成の問題に関する、組込みのレポート・システムが含まれています。これにより、スケジュール済ジョブのデバッグとモニターに役立つように主要なイベントおよびエラーがログ・ファイルに記録されます。

ログ形式、ログ・ファイルの場所、およびその説明について学習します。

4.4.1 ログ形式

ログ・ファイルは半構造化形式になっており、読みやすく解析しやすいように、各ログ行に、複数のトークンが、'[]'で囲み' - ' (スペースで囲まれたハイフン)で区切って含まれています。

ログは、情報エントリ用に1つとエラー・エントリ用にもう1つという、2つの基本形式で生成されます。ただし、ジョブ・スケジューリングやジョブ完了などの主要イベントには、固有の専用形式があります。

  • 情報メッセージ: この形式は、一般的なメッセージ(ジョブ開始、スケジューラ開始など)用に使用されます。 
    [timestamp] - [STATUS] - [MESSAGE: <message>]
  • エラー・レポート: この形式は、エラー・メッセージ(ジョブ失敗、スケジューラ起動失敗など)用に使用されます。 
    [timestamp] - [STATUS] - [ERROR: <error-message>]

    前述の形式では、STATUSフィールドによってログ・イベントのタイプが分類され、MESSAGEまたはERRORフィールドで詳細が提供されます。

  • 主要イベント用の特殊な形式。
    • ジョブ・スケジューリング(SCHEDULE_JOB): この形式は、ジョブの実行が正常にスケジュールされたことを示すために使用されます。 
      [timestamp] - [SCHEDULE_JOB] - [JOB: <job-name>] - [JOB_LOG: <full-log-file-path>]
    • ジョブ完了(COMPLETED): この形式は、ジョブの実行が正常に完了したことを示すために使用されます。 
      [timestamp] - [COMPLETED] - [JOB_RESULT: <output returned by running the job>]

      出力が複数の行にまたがる場合は、次のように折り返されます:

      [timestamp] - [COMPLETED] - [JOB_RESULT:
    line 1 of output
    line 2 of output
]
    • スケジュール・ファイル・イベント: この形式は、スケジュール・ファイル(scheduler.yaml)に対して発生する可能性がある変更点(SCHEDULE_FILE_LOADED、SCHEDULE_FILE_VALIDATED、SCHEDULE_FILE_ERRORなど)を示すために使用されます。 
      [timestamp] - [STATUS] - [SCHEDULE_FILE: <schedule-file-path>]

4.4.2 ログ・ファイルの場所

データベース・ツール(dbtools)のホーム・ディレクトリにログ・ファイルが含まれています。

ログ・ファイルのパス:

${HOME}/.dbtools/schedules/

SQLclデーモンでは、ログ・ファイル用に次のディレクトリ構造が使用されます:

~/.dbtools/schedules
├── logs
│   ├── job-<job-name>.log
│   └── jobs.log
├── pid
├── scheduler.log
└── scheduler.yaml

4.4.3 ログ・ファイルの説明

SQLclデーモンの各ログ・ファイルに、個別の目的があります。たとえば、あるファイルではデーモンのライフサイクル・ログが記録され、別のファイルでは、ジョブのスケジューリング・ログが取得されます。

デーモンには次のログファイルが含まれています:

ノート:

ログ・ローテーションはサポートされていません。そのため、これらのログ・ファイルは時間の経過とともに増大する場合があります。

4.4.3.1 デーモンのライフ・サイクルに関するログ(scheduler.log)

scheduler.logファイルには、デーモンのライフ・サイクル(起動、停止、失敗など)に関連するおおまかなイベントが記録されます。

表4-1 ライフ・サイクル・ログでレポートされるステータス

ステータス 説明 例

STARTED

スケジューラが正常に起動され、ジョブのスケジューリングを開始する準備ができていることを示しています。

 
[2025-05-06 09:00:00] - [STARTED] - [MESSAGE: SQLcl daemon started]

STOPPED

スケジューラが停止され、ジョブ・スケジューリングが停止されたことを示しています。

 
[2025-05-06 09:00:00] - [STOPPED] - [MESSAGE: SQLcl daemon stopped]

STARTUP_FAILED

スケジューラの起動に失敗したことを示しています。このメッセージでは理由が示されます。

 
[2025-05-06 09:00:00] - [STARTUP_FAILED] - [ERROR: <error-message>]

SHUTDOWN_FAILED

スケジューラの正常な停止に失敗したことを示しています。このメッセージでは理由が示されます。

 
[2025-05-06 18:35:00] - [SHUTDOWN_FAILED] - [ERROR: <error-message>]

4.4.3.2 共有されるジョブ・スケジューリングに関するログ(jobs.log)

jobs.logファイルには、すべてのジョブに影響するイベント(スケジュール・ファイルの更新、検証、ジョブ・スケジューリング・アクションなど)がログ記録されます。

表4-2 共有されるジョブ・スケジューリングに関するログでレポートされるステータス

ステータス 説明 例

SCHEDULE_FILE_LOADED

スケジュール・ファイルが正常にロードおよびシリアライズされ、ジョブをスケジュール可能であることを示しています。

 
[2025-05-06 10:00:00] - [SCHEDULE_FILE_LOADED] - [SCHEDULE_FILE: /Users/<username>/.dbtools/schedules/scheduler.yaml]

SCHEDULE_FILE_ERROR

フィールドが不足しているかコンテンツの形式が正しくないことが原因でスケジュール・ファイルが無効であることを示しています。

 
[2025-05-06 10:00:00] - [SCHEDULE_FILE_ERROR] - [ERROR: <error-message>]

SCHEDULE_FILE_VALIDATED

スケジュール・ファイルが有効であり、システムがジョブのスケジュールに進めることを示しています。

 
[2025-05-06 10:00:00] - [SCHEDULE_FILE_VALIDATED] - [SCHEDULE_FILE: /Users/<username>/.dbtools/schedules/scheduler.yaml]

SCHEDULE_JOB

ジョブが正常にスケジュールされたことを示しています。このログでは、ジョブの名前とそれ専用のログ・ファイルのパスが示されます。

 
[2025-05-06 18:35:00] - [SCHEDULE_JOB] - [JOB: test] - [JOB_LOG: /Users/<username>/.dbtools/schedules/logs/job-test.log]

JOB_SCHEDULE_FAILED

無効なcron式や内部エラーが原因でジョブのスケジュールに失敗したことを示しています。

 
[2025-05-06 18:35:00] - [JOB_SCHEDULE_FAILED] - [ERROR: <error-message>]

4.4.3.3 ジョブごとの実行に関するログ(job-<job-name>.log)

各ジョブにはそれ固有のログ・ファイルがあり、そのジョブのアクティビティのみが記録されます。これにより、ジョブ固有の動作の分離とデバッグが容易になります。

表4-3 個々のジョブのログでレポートされるステータス

ステータス 説明 例

RUNNING

ジョブの実行が開始されたことを示しています。

これにより、ジョブの予定時刻に達したことと、それを実行するためにリソースが割り当てられたことが裏付られます。

 
[2025-05-06 10:00:00] - [RUNNING] - [MESSAGE: Job execution started]

COMPLETED

ジョブが正常に完了したことを示しています。ジョブの出力がこのログに含まれています。

 
[2025-05-06 10:00:00] - [COMPLETED] - [RESULT:
Name                      Null?             Type
------------           --------        ------------
COUNTRY_ID             NOT NULL        CHAR(2)
COUNTRY_NAME                           VARCHAR2(40)
REGION_ID                              NUMBER
]

FAILED

接続の欠落やスクリプトの失敗などのエラーが原因でジョブが完了しなかったことを示しています。その理由はこのログに含まれています。

 
[2025-05-06 10:00:00] - [FAILED] - [ERROR: Unknown connection test]