OmniDoc문서 오류 문제를 해결하려면 로그가 필요하지만, 전체 텍스트를 로그할 필요는 없습니다.
번역 실패를 찾으려면 로그가 필요하지만 전체 계약서, ID 번호 또는 다운로드 토큰을 인쇄할 필요는 없습니다. 로그는 권한 관리가 부족한 두 번째 문서 라이브러리가 되기보다는 "어떤 작업, 어느 단계에서 실패했는지"에 대해 대답해야 합니다.
문서 번역 실패 문제를 해결하려면 로그가 필요하지만 계약서, ID 번호 또는 다운로드 토큰의 전체 텍스트가 로그에 포함될 필요는 없습니다. 이 문서에서는 고객 문서를 로그에 복사하지 않고 "어떤 작업이 어떤 단계에서 실패했고 이유"에 대한 로그 응답을 만드는 방법을 설명합니다.
적합한 독자는 문서 번역 서비스, 도킹 번역 인터페이스 또는 배경 로그 유지 관리를 담당하는 개발자와 운영 및 유지 관리 담당자입니다. 읽은 후 화이트리스트 필드 세트를 설계하고, 로그가 원본 텍스트를 가져오지 않는지 확인하고, 문제 해결을 위해 보존 기간과 액세스 범위를 설정할 수 있습니다.
예제에서는 처리 방법을 설명하기 위해 합성 샘플을 사용했으며 코드는 격리된 환경에서 확인되었지만 이것이 모든 실제 파일이나 제품 성능을 보장하지는 않습니다. 중요한 서류를 처리하기 전, 원본을 보관하시고 아래의 범위 및 접수사항에 따라 검토하시기 바랍니다.
문제 해결 로그에 무엇을 기록해야 합니까? 한 문장 결론
로그에는 작업 ID, 단계, 오류 범주, 시간 소비 등 허용된 필드만 기록되며 문서 내용 및 자격 증명은 기록되지 않습니다.
| 당신의 상황 | 권장 사례 | 이유 |
|---|---|---|
| 어떤 작업이 실패했는지 알아야 함 | 임의의 내부 작업 ID 로깅 | 사용자 파일 이름이나 경로를 노출하지 않고 문제를 찾는 기능 |
| 카드가 어느 단계에 있는지 확인해야 함 | 무대명과 소요시간을 기록한다 | 각각의 원문과 번역이 필요하지 않습니다. |
| 업스트림에서 요청을 거부했습니다. | 로그 정규화된 오류 카테고리 | 인증 1등급 완전한 요청 내용을 로그에 입력하면 안 됩니다. |
| 문제 해결을 위해 원본으로 돌아가야 함 | 제어 시스템 내에서 참조 사용 | 영구적으로 공개적으로 다운로드할 수 있는 링크는 유출될 위험이 있습니다. |
녹음이 허용된 필드부터 시작하세요.
블랙리스트는 새로운 민감한 필드를 쉽게 놓칠 수 있습니다. 보다 신중한 접근 방식은 설계된 필드만 출력하는 것입니다. 예를 들면 다음과 같습니다.
- 내부 작업 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
다음 표에는 문제 해결 중 일반적인 요구 사항과 권장 및 비권장 기록이 나와 있습니다.
| 조사하고 싶은 질문들 | 추천 음반 | 이 내용을 녹화하는 것은 권장하지 않습니다 |
|---|---|---|
| 실패한 임무 | 랜덤 내부 작업 ID | 사용자의 전체 파일명과 경로 |
| 어느 단계가 시간이 걸리는지요 | 단계와 시간 소모 | 각 단락의 원문 및 번역 |
| 왜 Upstream은 거부하나요? | 오류 범주 표준화 | 인증 헤더가 포함된 완전한 요청 |
| 원본을 찾는 방법 | 제어 시스템 내 참조 | 상시 공개 다운로드 가능한 링크 |
보존 기간은 접근 범위만큼이나 중요합니다
로그에 본문이 없더라도, 작업 시간, 언어, 파일 크기의 조합으로 비즈니스 정보를 얻을 수 있습니다. 로그에는 접근 제어, 보존 기간, 삭제 절차가 함께 제공되어야 합니다.
문제 해결 중에는 로그 레벨을 일시적으로 올리고, 언제 작업을 재개해야 하는지 명확히 하며, 디버깅 모드가 생산 환경에 너무 오래 머무르지 않도록 하세요.
번역 통합은 명확하고 절제된 로그를 제공합니다
OmniDoc (제품 입력)와 통합할 때는 로컬 및 원격 작업 간의 연관성만 기록되며, 사용자가 업로드한 파일은 더 쉬운 문제 해결을 위해 로그에 복사하지 않아야 합니다.
좋은 문제 보고서는 실패 단계와 재발 조건을 설명할 수 있으며, 고객 문서가 승인된 처리 경로 내에서만 진행되도록 보장합니다.
참고: Python logging.
📊 핵심 비교
| 방법 | 장점 | 위험 |
|---|---|---|
| 블랙리스트 | 글쓰기 방법은 직관적이고 배우기 쉽습니다 | 쉽게 보이는 민감한 필드는 놓치게 됩니다 |
| 화이트리스트 | 명확한 경계가 있는 설계된 필드만 출력됩니다 | 필드를 미리 계획하고 필드 값의 길이와 유형을 검증하는 것이 필요합니다 |
🎯 어떤 방법이 당신에게 맞나요?
번역 작업을 찾아야 한다면
사용자의 전체 파일 이름이나 경로를 기록하지 않고 무작위로 내부 작업 ID와 실패 단계를 기록합니다.
상류 인터페이스 오류를 처리하고 싶다면
표준화된 오류 범주를 기록하되, 인증 헤더가 포함된 완전한 요청을 기록하지 마세요.
온라인 문제를 해결하고 있다면
일시적으로 통나무 높이를 올리고 점검 직후 즉시 복원하세요.
로그 필드를 설계하고 싶다면
화이트리스트 우선순위를 두고 필드 값의 길이와 유형을 확인하세요.
❓ 자주 묻는 질문 (FAQ)
1. 로그에 사용자의 전체 파일 이름을 기록할 수 있나요?
추천하지 않습니다. 전체 파일 이름과 경로는 녹화에 권장되지 않습니다; 대신 무작위 내부 작업 ID를 사용해 연관시킬 수 있습니다.
2. 왜 민감한 필드를 필터링하기 위해 블랙리스트를 사용하는 것이 권장되지 않나요?
블랙리스트는 새로 등장한 민감 필드를 놓치는 경향이 있지만, 화이트리스트는 설계된 필드만 출력하여 더 신뢰할 수 있습니다.
3. 작업 시간과 파일 크기만 관리하면 되나요?
네. 이 정보가 함께 제공되면 비즈니스 세부사항도 드러날 수 있으며, 로그에는 접근 제어, 보존 기간, 삭제 절차가 함께 제공되어야 합니다.
4. 문제 해결 중에 디버그 로그를 오랫동안 열어둘 수 있나요?
추천하지 않습니다. 로그 레벨을 일시적으로 업그레이드한 후에는 디버깅 모드를 언제 재개할지 명시하여 디버깅 모드를 운영 환경에 너무 오래 머무르지 않도록 하는 것이 중요합니다.
5. 비즈니스 데이터베이스에서 글로벌 핸들러를 지울 수 있나요?
추천하지 않습니다. 예시는 본인이 직접 이름 붙인 데모 로거만 수정합니다; 비즈니스 라이브러리에서 글로벌 핸들러 애플리케이션을 비워서는 안 됩니다.
📝 요약
번역 실패를 문제 해결할 때, 로그는 문서 내용을 저장하는 대신 작업, 단계, 이유를 답해야 합니다. 화이트리스트 필드, 통제된 인용, 명확한 보존 기간을 사용하는 것은 문제 해결 효율성과 문서 보안을 균형 있게 유지하는 데 필수적입니다.
