Os logs são necessários para solucionar falhas de documentos, mas não há necessidade de registrar o texto completo.

Os logs são necessários para solucionar falhas de tradução de documentos, mas os logs não precisam conter o texto completo do contrato, número de identificação ou token de download. Este artigo explica como fazer com que o log responda "qual tarefa falhou em qual etapa e por quê" sem copiar os documentos do cliente no log.

Leitores adequados são desenvolvedores e pessoal de operação e manutenção responsáveis pelos serviços de tradução de documentos, acoplamento de interfaces de tradução ou manutenção de registros em segundo plano. Após a leitura, você pode criar um conjunto de campos da lista de permissões, verificar se o log não traz o texto original e definir o período de retenção e o escopo de acesso para solução de problemas.

Os exemplos usam amostras sintéticas para demonstrar métodos de processamento, e o código foi verificado em um ambiente isolado, mas isso não representa uma garantia de todos os arquivos reais ou do desempenho do produto. Antes de processar documentos importantes, guarde os originais e revise-os de acordo com os limites e itens de aceitação abaixo.

O que deve ser registrado no log de solução de problemas? Conclusão de uma frase

O log registra apenas campos permitidos, como ID da tarefa, estágio, categoria de erro e consumo de tempo, mas não registra o conteúdo e as credenciais do documento.

Comece com os campos que têm permissão para registrar

A lista negra pode facilmente perder novos campos confidenciais. Uma abordagem mais prudente é gerar apenas os campos projetados, por exemplo:

• ID da tarefa interna
• Estágio de processamento
• categoria de erro
• demorado

O exemplo de síntese abaixo usa uma projeção de lista de permissões para que o texto completo e os tokens da entrada não sejam inseridos no log.

O log de verificação não revelou o texto original.

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)

O exemplo modifica apenas o registrador demo autodenominado. Não é recomendado limpar o manipulador global do aplicativo na biblioteca comercial. Os valores dos campos ainda precisam ser verificados quanto ao comprimento e tipo. Se você inserir o texto completo do usuário em error_code, o nome da lista de permissões por si só não o salvará.

ID de associação no lugar de conteúdo confidencial

A tabela a seguir lista os requisitos comuns durante a solução de problemas, bem como os registros recomendados e não recomendados.

O período de retenção é tão importante quanto o escopo de acesso

Mesmo que não haja texto no log, a combinação de tempo de tarefa, idioma e tamanho do arquivo pode revelar informações comerciais. Os registos devem ser acompanhados de controlos de acesso, períodos de retenção e procedimentos de eliminação.

Ao solucionar problemas, aumente temporariamente o nível de log e deixe claro quando restaurar para evitar deixar o modo de depuração no ambiente de produção por um longo período.

A integração da tradução também pode ter registros claros e restritos

Ao conectar-se ao OmniDoc (portal de produtos), você só precisa registrar a associação entre tarefas locais e tarefas remotas. Os arquivos carregados pelos usuários não devem ser copiados no log para facilitar a solução de problemas.

Um bom relatório de problemas descreve o estágio da falha e as condições de recorrência, ao mesmo tempo em que mantém o fluxo dos documentos do cliente apenas nos caminhos de processamento autorizados.

Referências: Python logging.

📊 Comparação principal

🎯 Qual método é adequado para você?

Se você precisar localizar uma tarefa de tradução

Registrando IDs de tarefas internas aleatórias e estágios de falha, não registrando nomes de arquivos ou caminhos completos do usuário.

Se você deseja lidar com erros relatados pela interface upstream

Registrando classes de erro normalizadas, não registrando solicitações completas com cabeçalhos de autenticação.

Se você estiver solucionando problemas on-line

Aumente temporariamente o nível de log e restaure-o imediatamente após a solução de problemas.

Se você deseja criar campos de log

Prefira a lista de permissões e verifique o comprimento e o tipo dos valores dos campos.

❓ Perguntas frequentes (FAQ)

1. O nome completo do arquivo do usuário pode ser registrado no log?

Não recomendado. O nome completo do arquivo e o caminho não são recomendados para serem registrados e, em vez disso, a correlação interna aleatória de ID de tarefa pode ser usada.

2. Por que não é recomendado usar a lista negra para filtrar campos confidenciais?

A lista negra facilmente ignora campos confidenciais recém-surgidos, enquanto a lista branca gera apenas campos projetados, o que é mais seguro.

3. Somente o tempo da tarefa e o tamanho do arquivo precisam ser gerenciados?

precisar. A combinação dessas informações também pode revelar informações comerciais, e os registros devem ser acompanhados de controles de acesso, períodos de retenção e procedimentos de exclusão.

4. Os logs de depuração podem ficar ativados por um longo período durante a solução de problemas?

Não recomendado. Após aumentar temporariamente o nível de log, é necessário saber quando restaurá-lo para evitar deixar o modo de depuração no ambiente de produção por muito tempo.

5. O manipulador global pode ser limpo na biblioteca de negócios?

Não recomendado. O exemplo modifica apenas o registrador de demonstração autodenominado e o manipulador global do aplicativo não deve ser limpo na biblioteca de negócios.

📝 Resumo

Ao solucionar falhas de tradução, os logs devem responder às tarefas, etapas e motivos, em vez de salvar o conteúdo do documento. Use campos da lista de permissões, referências controladas e períodos de retenção claros para equilibrar a eficiência da solução de problemas e a segurança dos documentos.

Experimente agora: carregue o documento para iniciar a tradução, mantendo o layout original