Dzienniki są potrzebne do rozwiązywania problemów z błędami w dokumentach, ale nie ma potrzeby rejestrowania pełnego tekstu.

— Zaleca się używanie pól białej listy i wyświetlanie tylko zaprojektowanych pól, takich jak identyfikator zadania wewnętrznego, etap, kategoria błędu i czasochłonność.

Czarna lista łatwo pomija nowe wrażliwe pola, a projekcja białej listy jest bardziej niezawodna.
Wartości pól nadal wymagają sprawdzenia pod względem długości i typu, w przeciwnym razie pełny tekst zostanie wrzucony do pola niewłaściwej kategorii, a nazwy z białej listy nie zostaną zapisane.
Logi muszą być wyposażone w kontrolę dostępu, okres przechowywania i proces usuwania, a poziom logów powinien zostać przywrócony w odpowiednim czasie po rozwiązaniu problemu.

Dzienniki są wymagane do rozwiązywania problemów z błędami w tłumaczeniu dokumentów, ale nie muszą zawierać pełnego tekstu umowy, numeru identyfikacyjnego ani tokenu pobierania. W tym artykule wyjaśniono, jak utworzyć dziennik z odpowiedzią „które zadanie nie powiodło się, na jakim etapie i dlaczego"bez kopiowania dokumentów klienta do dziennika.

Odpowiednimi czytelnikami są programiści oraz personel operacyjny i konserwacyjny odpowiedzialny za usługi tłumaczenia dokumentów, dokowanie interfejsów tłumaczeniowych lub utrzymywanie dzienników w tle. Po przeczytaniu możesz zaprojektować zestaw pól białej listy, sprawdzić, czy dziennik nie zawiera oryginalnego tekstu, a także ustawić okres przechowywania i zakres dostępu na potrzeby rozwiązywania problemów.

W przykładach wykorzystano próbki syntetyczne w celu zademonstrowania metod przetwarzania, a kod został sprawdzony w izolowanym środowisku, ale nie stanowi to gwarancji działania wszystkich rzeczywistych plików lub produktu. Przed przystąpieniem do przetwarzania ważnych dokumentów prosimy o zachowanie oryginałów i zapoznanie się z nimi zgodnie z poniższymi granicami i punktami akceptacji.

Co należy zapisać w dzienniku rozwiązywania problemów? Wniosek w jednym zdaniu

Dziennik rejestruje tylko dozwolone pola, takie jak identyfikator zadania, etap, kategoria błędu i czasochłonność, ale nie rejestruje treści dokumentu ani poświadczeń.

twoja sytuacja	Zalecane praktyki	powód
Musisz wiedzieć, które zadanie się nie powiodło	Rejestrowanie losowego identyfikatora zadania wewnętrznego	Możliwość lokalizowania problemów bez ujawniania nazw plików i ścieżek użytkownika
Należy określić, na jakim etapie znajduje się karta	Zapisz pseudonim sceniczny i czas	Nie ma potrzeby stosowania każdego tekstu źródłowego i tłumaczenia
Wniosek został odrzucony przez firmę upstream	Rejestruj znormalizowane kategorie błędów	W dzienniku nie należy wprowadzać pełnej treści żądania uwierzytelnienia
Aby rozwiązać problem, trzeba wrócić do oryginału	Korzystanie z referencji w kontrolowanym systemie	Linki, które można trwale pobrać publicznie, są narażone na ryzyko wycieku

Zacznij od pól, które mogą rejestrować

Czarna lista może łatwo pominąć nowe wrażliwe pola. Bardziej ostrożnym podejściem jest wyprowadzanie tylko zaprojektowanych pól, na przykład:

Wewnętrzny identyfikator zadania
Etap przetwarzania
kategoria błędu
czasochłonne

Poniższy przykład syntezy wykorzystuje projekcję białej listy, dzięki czemu pełny tekst i tokeny na wejściu nie są wprowadzane do dziennika.

Dziennik weryfikacji nie zawierał oryginalnego tekstu.

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)

Przykład modyfikuje jedynie rejestrator demonstracyjny o tej samej nazwie. Nie zaleca się czyszczenia globalnej procedury obsługi aplikacji w bibliotece biznesowej. Wartości pól wymagają jeszcze weryfikacji pod względem długości i typu. Jeśli umieścisz pełny tekst użytkownika w error_code, sama nazwa na białej liście Cię nie uratuje.

Identyfikator stowarzyszenia zamiast poufnych treści

W poniższej tabeli wymieniono typowe wymagania dotyczące rozwiązywania problemów, a także zalecane i niezalecane zapisy.

Problemy do zbadania	Polecane nagrania	Nagrywanie nie zalecane
Która misja zakończyła się niepowodzeniem	Losowy wewnętrzny identyfikator zadania	Pełna nazwa pliku użytkownika i jego ścieżka
Który etap zajmuje czas	Etapy i czasochłonne	Każdy akapit tekstu źródłowego i tłumaczenia
Dlaczego Upstream odmawia?	Standaryzacja kategorii błędów	Pełne żądanie z nagłówkiem uwierzytelniania
Jak znaleźć oryginał	Odniesienia w systemie sterowanym	Stałe dostępny link do publicznego pobrania

Okres retencji jest równie ważny jak zakres dostępu

Nawet jeśli dziennik nie zawiera tekstu głównego, połączenie czasu zadania, języka i rozmiaru pliku może ujawnić informacje biznesowe. Logi powinny być opatrzone kontrolą dostępu, okresami przechowywania oraz procesami usuwania.

Podczas rozwiązywania problemów tymczasowo podnieś poziom logu, wyjaśnij, kiedy wznowić operacje i unikaj zbyt długiego pozostawania trybu debugowania w środowisku produkcyjnym.

Integracja tłumaczeń zapewnia także jasne i powściągliwe logi

Podczas integracji z OmniDoc (wpis produktu) rejestrowane jest jedynie powiązanie między zadaniami lokalnymi a zdalnymi; pliki przesyłane przez użytkowników nie powinny być kopiowane do logów dla łatwiejszego rozwiązywania problemów.

Dobry raport problemu może wyjaśnić etap awarii i warunki powtarzalności, jednocześnie zapewniając, że dokumenty klienta trafiają wyłącznie w obrębie autoryzowanych ścieżek przetwarzania.

Źródła: Python logging.

📊 Porównanie rdzenia

Metoda	Zalety	Ryzyko
lista	Metoda pisania jest prosta i łatwa do opanowania	Wrażliwe pola, które łatwo się pojawiają, są pomijane
Biała lista	Tylko zaprojektowane pola są wyjściowe, z wyraźnymi granicami	Należy planować pola z wyprzedzeniem oraz weryfikować długość i typ wartości pól

🎯 Która metoda ci odpowiada?

Jeśli potrzebujesz znaleźć zadanie tłumaczeniowe

Rejestruje losowe wewnętrzne identyfikatory zadań i etapy awarii, bez zapisywania pełnej nazwy pliku użytkownika ani ścieżki.

Jeśli chcesz radzić sobie z błędami interfejsu upstream

Rejestruj standaryzowane kategorie błędów, ale nie rejestruj pełnych żądań z nagłówkami uwierzytelniającymi.

Jeśli rozwiązujesz problemy online

Tymczasowo podnieś poziom kłod i przywróć natychmiast po inspekcji.

Jeśli chcesz projektować pola logarytmiczne

Priorytetowo traktuj whitelist i weryfikuj długość oraz typ wartości pól.

❓ Najczęściej zadawane pytania (FAQ)

1. Czy dziennik może rejestrować pełną nazwę pliku użytkownika?

Nie polecam. Pełna nazwa pliku i ścieżka nie są zalecane do nagrywania; możesz użyć losowych wewnętrznych ID zadań do powiązania.

2. Dlaczego nie zaleca się używania czarnej listy do filtrowania wrażliwych pól?

Czarne listy zwykle pomijają nowo powstałe wrażliwe pola, podczas gdy białe listy generują jedynie pola zaprojektowane, co czyni je bardziej wiarygodnymi.

3. Czy wystarczy zarządzać czasem zadania i rozmiarem pliku?

Tak. Razem te informacje mogą również ujawniać szczegóły biznesowe, a logi powinny być uzupełnione kontrolą dostępu, okresami przechowywania oraz procesami usuwania.

4. Czy logi debugowania można długo utrzymywać otwarte podczas rozwiązywania problemów?

Nie polecam. Po tymczasowym ulepszeniu poziomu logu ważne jest, aby określić, kiedy wznowić tryb debugowania, aby nie zostawiać go zbyt długo w środowisku produkcyjnym.

5. Czy możesz usunąć globalny handler z bazy danych firm?

Nie polecam. Przykład modyfikuje tylko demo logger, który sam sobie nazwałeś; biblioteka biznesowa nie powinna być opróżniona z globalnej aplikacji handlera.

📝 Podsumowanie

Podczas rozwiązywania problemów z tłumaczeniem, dziennik powinien odpowiadać na zadanie, fazę i powód, zamiast zapisywać treść dokumentu. Stosowanie pól białej listy, kontrolowanych cytowań i okresów przejrzystości jest niezbędne, aby zrównoważyć efektywność rozwiązywania problemów z bezpieczeństwem dokumentów.

Doświadczenie teraz: Prześlij dokument, aby zacząć tłumaczyć, zachowując oryginalne formatowanie