メインコンテンツまでスキップ

付録 A. 実装者向けガイドライン

本付録は、syslog プロトコルの実装者に非規範的な指針を提供する。

A.1. BSD Syslog との関係​

RFC 3164 は、長年にわたって広く展開されてきた BSD syslog プロトコルを記述した。本書は RFC 3164 を廃止するが、重要な互換性を維持している。

主な相違点:

  • VERSION フィールド: 本仕様は明示的な VERSION フィールドを追加する。旧来の実装はこのフィールドを認識しない。
  • TIMESTAMP 形式: 本仕様は完全な日付、タイムゾーン、任意の小数秒を含む RFC 3339 時刻印を使用する。RFC 3164 は年およびタイムゾーンを含まないより単純な形式を用いた。
  • STRUCTURED-DATA: 本仕様は構造化データ要素を導入する。RFC 3164 には同等の機構がない。
  • MSG 形式: RFC 3164 の TAG フィールドは、HEADER 内の APP-NAME、PROCID、MSGID の各フィールドへ分割された。

相互運用性の考慮事項:

RFC 3164 システムと通信する場合:

  • 旧来システムへの送信: 受信者が本仕様をサポートしない場合、RFC 3164 に従ってメッセージを整形する。転送送信者は、受信者の能力を検出するか、設定を可能にするべきである。
  • 旧来システムからの受信: 本仕様に準拠する受信者は、RFC 3164 メッセージを解析できるべきである。受信者は、メッセージを本書で定義する形式へ変換してよい。
  • リレーの動作: リレーは形式間でメッセージを変換する必要が生じる場合がある。本仕様から RFC 3164 へ変換する場合:
    • VERSION フィールドを削除する。
    • TIMESTAMP を MMM DD HH:MM:SS 形式に変換する。
    • タイムゾーンおよび年の情報を捨てる。
    • STRUCTURED-DATA を削除するか MSG に追加する。
    • APP-NAME と PROCID から TAG を再構成する。
  • RFC 3164 から本仕様への変換:
    • VERSION を 1 に設定する。
    • 時刻印に現在の年を追加する。
    • リレーのタイムゾーンまたは UTC を用いる。
    • TAG を APP-NAME と PROCID に解析する（可能な範囲で）。
    • 決定できない場合は MSGID を NILVALUE に設定する。

A.2. メッセージ長​

受信者に求められる最小容量 480 オクテットには、実用上の意味がある。

なぜ 480 オクテットか?

  • 多くのネットワークでフラグメント化なしの単一 UDP パケットに収まる。
  • 劣化したネットワークで配達される可能性が高い。
  • 制約のある実装と互換性がある。

影響:

  • 重大メッセージ: セキュリティ警報および運用上の緊急事態は 480 オクテット以内に収めるべきである。
  • トラブルシューティングデータ: 診断メッセージを簡潔に保つ。
  • 重要データを先に置く: 重要な情報をメッセージの先頭側に配置する。

より大きなメッセージ:

多くの現代的な展開は、はるかに大きいメッセージをサポートする。

  • TLS 転送では通常、数十または数百キロバイトを許容する。
  • TCP 転送には実用上のサイズ上限がない。
  • 現代的な実装はしばしば 2048、8192、またはそれ以上のメッセージをサポートする。

推奨事項:

  • 展開要件に基づいて最大メッセージサイズを設定する。
  • 重要なメタデータには STRUCTURED-DATA を使用する（メッセージ長に数える）。
  • 使用する環境で最大メッセージサイズを試験する。
  • 過大なメッセージを適切に扱う処理（切詰めまたは拒否）を実装する。
  • 収集器で切り詰められたメッセージを監視する。

UTF-8 に関する考慮事項:

メッセージ長は文字数ではなくオクテット数で測定する。非 ASCII 文字を含む 1000 文字の UTF-8 文字列は、3000 オクテット以上になる場合がある。実装者はメッセージサイズを決めるときにこれを考慮しなければならない。

A.3. Severity 値​

Severity 値を適切に用いると、メッセージの有用性が向上する。

指針:

  • Emergency (0): 真の緊急事態に限って控えめに使用する。
    • システムが完全に使用不能である。
    • 重要なハードウェアの障害が差し迫っている。
    • データ損失が発生している。
  • Alert (1): 即時の対応が必要である。
    • サービス停止。
    • セキュリティ侵害を検出した。
    • 重要リソースの枯渇が差し迫っている。
  • Critical (2): 重大な状態。
    • ハードドライブ障害。
    • 主ネットワーク接続の喪失。
    • アプリケーションのクラッシュ。
  • Error (3): エラー状態。
    • 重大ではないサービス障害。
    • 回復可能なエラー。
    • 接続タイムアウト。
  • Warning (4): 警告状態。
    • リソース使用量が上限に近づいている。
    • 非推奨機能の使用。
    • 構成上の問題。
  • Notice (5): 通常だが重要な状態。
    • サービスの開始／停止。
    • 構成変更。
    • セキュリティに関連する通常イベント。
  • Informational (6): 情報メッセージ。
    • 通常運用。
    • 状態メッセージ。
    • 接続確立。
  • Debug (7): デバッグレベルのメッセージ。
    • 詳細な診断情報。
    • 開発者向けメッセージ。
    • 本番環境では無効にすべきである。

構成上の考慮事項:

管理者が次を実行できるようにする。

  • 展開要件ごとに Severity の割当てを調整する。
  • Severity によってメッセージをフィルタする。
  • Severity を異なる収集器へルーティングする。
  • 特定のメッセージ種別の Severity を上書きする。

Severity の乱用を避ける:

  • すべてのメッセージを Emergency として記録しない。
  • 本番イベントに Debug の Severity を使用しない。
  • 運用者の警報疲れを考慮する。

A.4. TIME-SECFRAC の精度​

TIMESTAMP フィールドは、最大 6 桁（マイクロ秒）の小数秒をサポートする。

よくある誤り:

先行するゼロを落とすこと:

誤: 2003-10-11T22:13:14.3      （300ms に見える）
正: 2003-10-11T22:13:14.003    （実際は 3ms）

精度に関する推奨事項:

  • 多くのアプリケーションではミリ秒（3 桁）を使用する。
  • 高精度の時刻測定にはマイクロ秒（6 桁）を使用する。
  • サブ秒精度が不要なら小数秒を省略する。
  • 時刻同期（NTP）が必要な精度をサポートすることを確保する。

実装上の注意:

すべてのシステムがマイクロ秒精度を提供できるわけではない。次の処理は許容される。

  • 6 桁より少ない精度を提供する。
  • 利用可能な精度に丸めるか切り捨てる。
  • 精度を利用できない場合は TIME-SECFRAC 全体を省略する。

A.5. 名前の大文字小文字規約​

本書は SD-ID および PARAM-NAME に「lower camel case」を使用する。

規約:

  • 最初の文字は小文字。
  • 後続する各単語の先頭文字は大文字。
  • ハイフンおよびアンダースコアは使用しない。

例:

  • timeQuality
  • syncAccuracy
  • enterpriseId
  • myCompanyName

利点:

  • 実装間の一貫性。
  • 可読性。
  • 多様なプログラミング言語との互換性。

推奨事項:

次の名前にはこの規約を使用する。

  • 新しい SD-ID
  • PARAM-NAME
  • 拡張識別子

私用実装は別の規約を使用してもよいが、一貫性が推奨される。

A.6. 時刻を認識しない Syslog アプリケーション​

6.2.3 節は、時刻が不明な場合に TIMESTAMP として NILVALUE を許可する。

TIMESTAMP に NILVALUE を使用する場合:

  • リアルタイムクロックを持たない組込みシステム。
  • 時刻同期前の起動時メッセージ。
  • 時刻取得に失敗したシステム。

NILVALUE を使用しない場合:

  • OS が時刻関数を提供する場合。
  • 実装を簡略化するために時刻処理を避けようとする場合。
  • 時刻は利用可能だが取得が不便なだけの場合。

推奨事項:

  • 可能な限り有効な TIMESTAMP を出力する。
  • 時刻の取得が真に不可能な場合だけ NILVALUE を使用する。
  • タイムゾーンと精度のトレードオフを考慮する。
  • 実装における時刻処理を文書化する。

リレーの処理:

NILVALUE TIMESTAMP を持つメッセージを受信したリレーは、次のいずれかを行ってよい。

  • 変更せずに転送する。
  • リレーの現在時刻に置換する。
  • メッセージを捨てる（ポリシーが時刻印を必要とする場合）。

構成でこの動作を制御するべきである。

A.7. timeQuality SD-ID に関する注意​

timeQuality SD-ID は、時刻印の正確さに関する有益なメタデータを提供する。

tzKnown パラメータ:

次の場合を除き、既定値は 0（不明）にすべきである。

  • 管理者がタイムゾーンを明示的に設定している。
  • OS が信頼できるタイムゾーン情報を提供する。
  • システムが外部ソースに対してタイムゾーンを検証している。

isSynced パラメータ:

次の場合だけ 1 に設定する。

  • NTP または他の時刻同期が有効である。
  • 同期の成功を検証済みである。
  • 時刻ソースが信頼できる。

syncAccuracy パラメータ:

次の場合だけ提供する。

  • 実際の精度が既知である（NTP 統計から得る）。
  • 管理者が期待精度を設定している。
  • 測定データがその主張を裏付ける。

精度を過大に主張しない:

誤った精度はログへの信頼を損なう。不確かな場合は、次の方法がよりよい。

  • timeQuality を完全に省略する。
  • 控えめな精度推定を提供する。
  • 精度に関する主張を文書化する。

A.8. UTF-8 符号化と BOM​

BOM（Byte Order Mark）は、MSG フィールドにおける UTF-8 符号化を示す。

BOM の詳細:

  • バイト列: 0xEF 0xBB 0xBF
  • MSG フィールドの先頭に置く。
  • 後続が UTF-8 符号化であることを示す。

BOM を含める場合:

  • MSG が UTF-8 符号化テキストを含む場合。
  • UTF-8 符号化であることが確実な場合。
  • 組織のポリシーとの一貫性のため。

BOM を省略する場合:

  • MSG の符号化が未知または不確かな場合。
  • MSG がバイナリデータを含む場合。
  • BOM を扱えないシステムとの後方互換性のため。

受信者の処理:

受信者は次を行うべきである。

  • BOM の存在を検出する。
  • それに応じて UTF-8 を処理する。
  • BOM のないメッセージを扱う（符号化は未知と仮定する）。
  • エンドユーザーへ BOM を表示しない。

リレーの処理:

メッセージを転送するリレーは次を行うべきである。

  • 存在する BOM を保持する。
  • UTF-8 へトランスコードする場合を除き BOM を追加しない。
  • 別の符号化へトランスコードする場合を除き BOM を削除しない。
に最終更新