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

付録 A. 実装者ガイドライン (Implementer Guidelines)

この付録は、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. メッセージ長 (Message Length)​

受信者の最小要件である 480 オクテットには実用的な意味があります:

なぜ 480 オクテット?

  • 多くのネットワークでフラグメンテーションなしの単一 UDP パケット
  • 劣化したネットワークでの配信可能性が高い
  • 限定的な実装との互換性

影響:

  • 重要なメッセージ: セキュリティアラートおよび運用上の緊急事態は 480 オクテット以内に収める必要があります
  • トラブルシューティングデータ: 診断メッセージをコンパクトに保つ
  • 重要なデータを先に: 重要な情報をメッセージの早い段階に配置

より大きなメッセージ:

多くの最新の展開ははるかに大きなメッセージをサポートします:

  • TLS トランスポートは通常、数十または数百キロバイトを許可
  • TCP トランスポートには実用的なサイズ制限がない
  • 最新の実装は、2048、8192、またはそれ以上のメッセージをサポートすることが多い

ベストプラクティス:

  • 展開要件に基づいて最大メッセージサイズを構成
  • 重要なメタデータには STRUCTURED-DATA を使用（メッセージ長にカウント）
  • 環境で最大メッセージサイズをテスト
  • 特大メッセージの適切な処理を実装（切り捨てまたは拒否）
  • コレクタで切り捨てられたメッセージを監視

UTF-8 の考慮事項:

メッセージ長はオクテットで測定され、文字ではありません。1000 文字の UTF-8 文字列は、非 ASCII 文字が含まれている場合、3000 オクテット以上になる可能性があります。実装者はメッセージのサイズを決定する際にこれを考慮する必要があります。

A.3. 重大度値 (Severity Values)​

重大度値の適切な使用により、メッセージの有用性が向上します。

ガイドライン:

  • Emergency (0): 真の緊急事態のために控えめに使用

    • システムが完全に使用不能
    • 重要なハードウェアの差し迫った障害
    • データ損失が発生中

  • Alert (1): 即座のアクションが必要

    • サービス停止
    • セキュリティ侵害が検出された
    • 重要なリソースの枯渇が差し迫っている

  • Critical (2): 重大な状態

    • ハードドライブの障害
    • プライマリネットワーク接続の喪失
    • アプリケーションのクラッシュ

  • Error (3): エラー状態

    • 非重要サービスの障害
    • 回復可能なエラー
    • 接続タイムアウト

  • Warning (4): 警告状態

    • リソース使用量が制限に近づいている
    • 非推奨機能の使用
    • 構成の問題

  • Notice (5): 正常だが重要

    • サービスの開始/停止
    • 構成の変更
    • セキュリティ関連の通常イベント

  • Informational (6): 情報メッセージ

    • ルーチン操作
    • ステータスメッセージ
    • 接続の確立

  • Debug (7): デバッグレベルのメッセージ

    • 詳細な診断情報
    • 開発者向けメッセージ
    • 本番環境では無効にする必要があります

構成の考慮事項:

管理者が次のことを行えるようにする:

  • 展開ニーズに応じて重大度の割り当てを調整
  • 重大度でメッセージをフィルタリング
  • 重大度を異なるコレクタにルーティング
  • 特定のメッセージタイプの重大度を上書き

重大度の乱用を避ける:

  • すべてのメッセージを Emergency としてマークしない
  • 本番イベントに Debug 重大度を使用しない
  • オペレータのアラート疲労を考慮

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. 名前の大文字小文字規則 (Case Convention for Names)​

この文書は、SD-ID および PARAM-NAME に「ロワーキャメルケース」を使用します。

規則:

  • 最初の文字は小文字
  • 後続の単語の最初の文字は大文字
  • ハイフンやアンダースコアなし

例:

  • 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（バイトオーダーマーク）は、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 を削除しない
に最終更新