ドキュメントの障害のトラブルシューティングにはログが必要ですが、全文を記録する必要はありません。

文書翻訳の失敗のトラブルシューティングにはログが必要ですが、ログには契約書の全文、ID 番号、ダウンロード トークンが含まれている必要はありません。この記事では、顧客の文書をログにコピーせずに、「どのタスクがどのステップで失敗したか、そしてその理由」をログに回答する方法を説明します。

適切な読者は、ドキュメント翻訳サービス、ドッキング翻訳インターフェイス、またはバックグラウンド ログの保守を担当する開発者および運用保守担当者です。読み取り後、一連のホワイトリスト フィールドを設計し、ログが元のテキストを取り出していないことを確認し、トラブルシューティングのための保存期間とアクセス範囲を設定できます。

この例では、処理方法を示すために合成サンプルを使用しており、コードは隔離された環境でチェックされていますが、これはすべての実際のファイルや製品のパフォーマンスを保証するものではありません。重要な書類を処理する前に、原本を保管し、以下の範囲および受領事項に従って確認してください。

トラブルシューティング ログには何を記録する必要がありますか?一文の結論

ログには、タスク ID、ステージ、エラー カテゴリ、時間消費などの許可されたフィールドのみが記録され、ドキュメントの内容や資格情報は記録されません。

記録が許可されているフィールドから開始します

ブラックリストでは、新しい機密フィールドが簡単に見落とされる可能性があります。より賢明なアプローチは、次のように、設計されたフィールドのみを出力することです。

• 内部タスクID
• 加工段階
• エラーカテゴリ
• 時間がかかる

以下の合成例では、入力内のフルテキストとトークンがログに入力されないように、ホワイトリスト投影を使用しています。

検証ログでは元のテキストが表示されませんでした。

import io
import json
import logging

ALLOWED = ("job_id", "stage", "error_code", "elapsed_ms")
def log_record(data):
    return {key: data[key] for key in ALLOWED if key in data}

stream = io.StringIO()
logger = logging.getLogger("synthetic-document-job")
logger.handlers.clear()
logger.propagate = False
logger.setLevel(logging.INFO)
handler = logging.StreamHandler(stream)
logger.addHandler(handler)
event = {"job_id": "demo-12", "stage": "parse", "error_code": "BAD_CONTAINER",
         "elapsed_ms": 42, "document_text": "synthetic confidential clause",
         "access_token": "synthetic-secret"}
logger.info(json.dumps(log_record(event), sort_keys=True))
logged = json.loads(stream.getvalue())
assert logged["error_code"] == "BAD_CONTAINER"
assert "document_text" not in logged
assert "synthetic-secret" not in stream.getvalue()
assert set(logged) <= set(ALLOWED)
logger.removeHandler(handler)

この例では、自己名前付きデモ ロガーのみを変更します。ビジネス ライブラリ内のアプリケーション グローバル ハンドラーをクリアすることはお勧めできません。フィールド値の長さと型を検証する必要があります。ユーザーの全文を error_code に詰め込んだ場合、ホワイトリスト名だけでは救われません。

機密コンテンツの代わりに関連付け ID を使用

次の表に、トラブルシューティング時の一般的な要件と、推奨される記録と非推奨される記録を示します。

保存期間はアクセス範囲と同様に重要です

ログにテキストがない場合でも、タスク時間、言語、ファイル サイズの組み合わせによってビジネス情報が明らかになる可能性があります。ログには、アクセス制御、保存期間、削除手順を伴う必要があります。

トラブルシューティングを行うときは、運用環境でデバッグ モードが長時間放置されることを避けるために、一時的にログ レベルを上げ、いつ復元するかを明確にしてください。

翻訳統合では、明確で抑制されたログを保持することもできます

OmniDoc (製品ポータル)に接続するときは、ローカル タスクとリモート タスク間の関連付けを記録するだけで済みます。トラブルシューティングの便宜上、ユーザーがアップロードしたファイルをログにコピーしないでください。

適切な問題レポートは、障害の段階と再発状況を説明し、顧客のドキュメントは許可された処理パスのみで流れるようにします。

参考：Python logging。

📊 コアの比較

🎯 どの方法があなたに適していますか?

翻訳タスクを見つける必要がある場合

完全なユーザー ファイル名やパスを記録するのではなく、ランダムな内部タスク ID と障害段階を記録します。

上流インターフェイスによって報告されたエラーを処理する場合

認証ヘッダーを含む完全なリクエストをログに記録するのではなく、正規化されたエラー クラスをログに記録します。

オンラインの問題のトラブルシューティングを行う場合

一時的にログ レベルを上げ、トラブルシューティングの直後にログ レベルを復元します。

ログフィールドを設計したい場合

ホワイトリストを優先し、フィールド値の長さとタイプを確認してください。

❓ よくある質問 (FAQ)

1. ユーザーの完全なファイル名をログに記録できますか?

お勧めしません。完全なファイル名とパスを記録することはお勧めできません。代わりに、ランダムな内部タスク ID の関連付けを使用できます。

2. 機密フィールドをフィルタリングするためにブラックリストを使用することが推奨されないのはなぜですか?

ブラックリストは新しく出現した機密フィールドを簡単に見逃しますが、ホワイトリストは設計されたフィールドのみを出力するため、より安全です。

3. 管理する必要があるのはタスク時間とファイル サイズだけですか?

必要。この情報を組み合わせるとビジネス情報が明らかになる可能性もあり、ログにはアクセス制御、保存期間、削除手順を伴う必要があります。

4. トラブルシューティングの際、デバッグ ログを長時間オンにすることはできますか?

お勧めしません。一時的にログ レベルを上げた後、実稼働環境でデバッグ モードが長時間放置されることを避けるために、ログ レベルをいつ復元するかを把握する必要があります。

5. ビジネス ライブラリでグローバル ハンドラーをクリアできますか?

お勧めしません。この例では、自己名前付きデモ ロガーのみを変更します。ビジネス ライブラリでアプリケーション グローバル ハンドラーをクリアしないでください。

📝 概要

翻訳失敗のトラブルシューティングを行う場合は、文書の内容を保存するのではなく、ログにタスク、段階、および理由が記録される必要があります。ホワイトリスト フィールド、制御された参照、および明確な保存期間を使用して、トラブルシューティングの効率とドキュメントのセキュリティのバランスを保ちます。

今すぐ試してみましょう: ドキュメントをアップロードして、元のレイアウトを保持したまま翻訳を開始します