Журналы необходимы для устранения неполадок с документами, но нет необходимости записывать полный текст.

Основные положения этой статьи

— Журналы должны отвечать на вопрос, какая задача, на каком этапе и почему она не удалась, а не сохранять полный текст или конфиденциальную информацию.

• Рекомендуется использовать поля белого списка и выводить только разработанные поля, такие как внутренний идентификатор задачи, этап, категория ошибки и затраты времени.
• Черный список легко пропускает новые чувствительные поля, а проекция белого списка более надежна.

— Значения полей по-прежнему необходимо проверять на длину и тип, иначе полный текст будет вбит не в то поле категории, и имена белых списков его не сохранят.

• Журналы должны быть оснащены контролем доступа, сроком хранения и процессом удаления, а уровень журнала должен быть восстановлен вовремя после устранения неполадок.

Журналы необходимы для устранения ошибок перевода документов, но журналы не обязательно должны содержать полный текст контракта, идентификационный номер или токен загрузки. В этой статье объясняется, как сделать так, чтобы журнал отвечал «какая задача на каком этапе не удалась и почему», не копируя в журнал документы клиента.

Подходящими читателями являются разработчики, а также персонал по эксплуатации и техническому обслуживанию, отвечающий за услуги перевода документов, стыковку интерфейсов перевода или ведение фоновых журналов. После прочтения вы можете создать набор полей белого списка, убедиться, что в журнале не отображается исходный текст, а также установить период хранения и область доступа для устранения неполадок.

В примерах используются синтетические образцы для демонстрации методов обработки, а код проверен в изолированной среде, но это не является гарантией работоспособности всех реальных файлов или продукта. Перед обработкой важных документов сохраните оригиналы и проверьте их в соответствии с границами и пунктами приема, указанными ниже.

Что следует записывать в журнал устранения неполадок? Вывод в одно предложение

В журнале записываются только разрешенные поля, такие как идентификатор задачи, этап, категория ошибки и затраты времени, но не записывается содержимое документа и учетные данные.

Начните с полей, в которых разрешена запись

Черный список может легко пропустить новые конфиденциальные поля. Более разумный подход — выводить только заданные поля, например:

• Внутренний идентификатор задачи
• Стадия обработки
• категория ошибки
• отнимает много времени

В приведенном ниже примере синтеза используется проекция белого списка, поэтому полный текст и токены на входе не вводятся в журнал.

Журнал проверки не выдал исходный текст.

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, одно только имя белого списка вас не спасет.

Идентификатор ассоциации вместо конфиденциального контента

В следующей таблице перечислены общие требования при устранении неполадок, а также рекомендуемые и нерекомендуемые записи.

Срок хранения так же важен, как и область доступа

Даже если в журнале нет текста, сочетание времени выполнения задачи, языка и размера файла может раскрыть бизнес-информацию. Журналы должны сопровождаться контролем доступа, сроками хранения и процедурами удаления.

При устранении неполадок временно повышайте уровень журнала и поясняйте, когда следует восстанавливать, чтобы не выходить из режима отладки в производственной среде на долгое время.

Интеграция перевода также может иметь четкие и ограниченные журналы

При подключении к OmniDoc (портал продуктов) вам нужно только записать связь между локальными и удаленными задачами. Файлы, загруженные пользователями, не должны копироваться в журнал для удобства устранения неполадок.

Хороший отчет о проблеме описывает стадии сбоя и условия повторения, сохраняя при этом поток документов клиента только по авторизованным путям обработки.

Источники: Python logging.

📊 Сравнение ядра

🎯 Какой метод подходит вам?

Если вам нужно найти задачу перевода

Регистрация случайных внутренних идентификаторов задач и стадий сбоя, а не полных имен файлов или путей пользователей.

Если вы хотите обрабатывать ошибки, сообщаемые вышестоящим интерфейсом

Регистрация нормализованных классов ошибок, а не регистрация полных запросов с заголовками аутентификации.

Если вы устраняете проблемы с Интернетом

Временно увеличьте уровень журнала и восстановите его сразу после устранения неполадок.

Если вы хотите создать поля журнала

Предпочитайте белый список и проверьте длину и тип значений полей.

❓ Часто задаваемые вопросы (FAQ)

1. Можно ли записать в журнал полное имя файла пользователя?

Не рекомендуется. Полное имя файла и путь не рекомендуется записывать, вместо этого можно использовать случайную внутреннюю корреляцию идентификаторов задач.

2. Почему не рекомендуется использовать черный список для фильтрации конфиденциальных полей?

Черный список легко пропускает вновь появившиеся конфиденциальные поля, тогда как белый список выводит только разработанные поля, что более безопасно.

3. Необходимо управлять только временем выполнения задачи и размером файла?

нуждаться. Комбинация этой информации может также раскрыть деловую информацию, и журналы должны сопровождаться контролем доступа, сроками хранения и процедурами удаления.

###4. Можно ли включать журналы отладки на длительное время при устранении неполадок? Не рекомендуется. После временного повышения уровня журнала необходимо знать, когда его восстанавливать, чтобы не выходить из режима отладки в производственной среде на длительное время.

5. Можно ли очистить глобальный обработчик в бизнес-библиотеке?

Не рекомендуется. В примере изменяется только одноименный демо-регистратор, а глобальный обработчик приложения не следует очищать в бизнес-библиотеке.

📝 Резюме

При устранении ошибок перевода журналы должны отражать задачи, этапы и причины, а не сохранять содержимое документа. Используйте поля белого списка, контролируемые ссылки и четкие сроки хранения, чтобы сбалансировать эффективность устранения неполадок и безопасность документов.

Попробуйте сейчас: загрузите документ, чтобы начать перевод, сохранив исходный макет.