protoncloud-sdk 5.3.2__tar.gz → 5.4.0__tar.gz

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: protoncloud-sdk
-Version: 5.3.2
+Version: 5.4.0
 Summary: Proton Cloud SDK para Python: execução de automações, ambientes, logs, parâmetros e recursos.
 Project-URL: Homepage, https://protoncloud.com.br
 Author: Atomic Solutions
@@ -230,6 +230,53 @@ set_log(f"url={url} senha={senha}")  # no log: url=•••••• senha=•
   mascarados.
 - Para os logs próprios do script, use `mask_environment_values(texto)`.
 
+## Log da execução
+
+Cada linha do log tem um nível: Informação (`info`, o padrão), Alerta (`warning`),
+Erro (`error`) ou Crítico (`critical`). A tela da execução filtra por nível e
+destaca alertas e erros, e a busca do Proton acha a linha entre execuções.
+
+```python
+from proton.proton_logs import log_error, log_info, log_warning, set_log
+
+log_info("Abrindo a transação BP")
+log_warning("Cadastro já existe: seguindo para o próximo", context={"cnpj": cnpj})
+log_error("Timeout no LoginSAP", context={"tentativa": 3})
+set_log("Mensagem com o nível escolhido", level="critical")
+```
+
+- `context` é um `dict` opcional que vai junto com a linha (o item processado, a
+  tentativa, o código de retorno). Os valores do ambiente saem mascarados nele
+  também.
+- O `logging` do projeto, encaminhado pelo executor de componentes, chega com o
+  nível dele: `warning`, `error` e `critical` viram Alerta, Erro e Crítico.
+- `set_log_from_exception(e)` manda o stack trace inteiro como uma linha de Erro.
+- Numa execução do Proton, cada linha também sai na saída do processo, com a hora
+  e o nível. O runner sobe essa saída como o arquivo de log da execução: acima do
+  limite do log no Proton (10 mil linhas), é nele que o log completo fica.
+
+## Correlation ID
+
+Cada execução tem um Correlation ID, o mesmo que a tela do Proton mostra. O runner
+o entrega em `PROTON_CORRELATION_ID` (runner 5.0.8 em diante), e a biblioteca o
+envia em toda chamada ao Proton (`X-Correlation-Id` e `traceparent`, no formato
+W3C Trace Context).
+
+Para levá-lo às chamadas que a automação faz (SAP, APIs, portais), use
+`correlation_headers()`. Com ele, o log do sistema chamado se acha pelo id da
+execução:
+
+```python
+import requests
+from proton.proton_env import correlation_headers, get_correlation_id
+
+requests.post(url, json=pedido, headers={**correlation_headers(), "Authorization": token})
+log_info(f"Pedido enviado ({get_correlation_id()})")
+```
+
+Fora do Proton, ou com um runner que ainda não entrega o id, `correlation_headers()`
+devolve um dicionário vazio.
+
 ### Categoria do dataset (Proton 4)
 
 No Proton 5 o dataset não tem categoria. `get_dataset_category()` e
@@ -258,12 +305,35 @@ from proton.run_status import RunStatus
 update_run_status(RunStatus.FAILED)
 ```
 
-O Proton 5 aceita `RUNNING`, `PASSED` e `FAILED`. Os status do Proton 4
-(`FAILED_DATA`, `FAILED_ENVIRONMENT` e `IN_PROCESS`) não existem mais: o servidor
-os recusa, e a biblioteca envia `FAILED` no lugar dos dois primeiros e `RUNNING`
-no lugar do último, com um `DeprecationWarning` e uma linha `[proton]` no log na
-primeira vez. Para separar falha de dados de falha de ambiente, registre o
-motivo no log da execução.
+O Proton 5 aceita `RUNNING`, `PASSED` e `FAILED`. Junto com o `FAILED`, o motivo
+diz por que a execução falhou, sem mudar o status:
+
+```python
+from proton.run_status import FailureReason
+
+update_run_status(RunStatus.FAILED, reason=FailureReason.BUSINESS)
+```
+
+| Motivo | Quando |
+|---|---|
+| `FailureReason.BUSINESS` | A regra de negócio não deixou seguir: cadastro que já existe, nota já recusada. Repetir dá o mesmo resultado. |
+| `FailureReason.TECHNICAL` | Qualquer outro erro: elemento que não apareceu, sistema fora do ar, exceção do código. É o padrão. |
+| `FailureReason.ENVIRONMENT` | O ambiente não deixou rodar: dependência que falta, configuração errada. |
+
+Com o executor de componentes, basta lançar `ProtonBusinessError` no passo: ele grava
+a falha com o motivo de negócio. Qualquer outra exceção conta como técnica.
+
+```python
+from proton.run_status import ProtonBusinessError
+
+if cadastro_existe:
+    raise ProtonBusinessError(f"O CNPJ {cnpj} já está cadastrado")
+```
+
+Os status do Proton 4 (`FAILED_DATA`, `FAILED_ENVIRONMENT` e `IN_PROCESS`) não
+existem mais: o servidor os recusa, e a biblioteca envia `FAILED` no lugar dos dois
+primeiros, com o motivo de negócio e de ambiente, e `RUNNING` no lugar do último,
+com um `DeprecationWarning` e uma linha `[proton]` no log na primeira vez.
 
 ## Executor de componentes
 
@@ -299,7 +369,8 @@ A cada passo, o executor:
   para cima (`forward_logs=False` desliga).
 
 No fim, grava `PASSED` quando não sobra passo. Quando um passo falha, grava o
-stack trace no painel de erro, grava `FAILED` e relança a exceção. Execução parada
+stack trace no painel de erro, grava `FAILED` com o motivo (de negócio para
+`ProtonBusinessError`, técnico para o resto) e relança a exceção. Execução parada
 não recebe status por cima.
 
 Um projeto pode cuidar de várias plataformas (SAP, web, API, desktop), cada uma

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/README.md

@@ -209,6 +209,53 @@ set_log(f"url={url} senha={senha}")  # no log: url=•••••• senha=•
   mascarados.
 - Para os logs próprios do script, use `mask_environment_values(texto)`.
 
+## Log da execução
+
+Cada linha do log tem um nível: Informação (`info`, o padrão), Alerta (`warning`),
+Erro (`error`) ou Crítico (`critical`). A tela da execução filtra por nível e
+destaca alertas e erros, e a busca do Proton acha a linha entre execuções.
+
+```python
+from proton.proton_logs import log_error, log_info, log_warning, set_log
+
+log_info("Abrindo a transação BP")
+log_warning("Cadastro já existe: seguindo para o próximo", context={"cnpj": cnpj})
+log_error("Timeout no LoginSAP", context={"tentativa": 3})
+set_log("Mensagem com o nível escolhido", level="critical")
+```
+
+- `context` é um `dict` opcional que vai junto com a linha (o item processado, a
+  tentativa, o código de retorno). Os valores do ambiente saem mascarados nele
+  também.
+- O `logging` do projeto, encaminhado pelo executor de componentes, chega com o
+  nível dele: `warning`, `error` e `critical` viram Alerta, Erro e Crítico.
+- `set_log_from_exception(e)` manda o stack trace inteiro como uma linha de Erro.
+- Numa execução do Proton, cada linha também sai na saída do processo, com a hora
+  e o nível. O runner sobe essa saída como o arquivo de log da execução: acima do
+  limite do log no Proton (10 mil linhas), é nele que o log completo fica.
+
+## Correlation ID
+
+Cada execução tem um Correlation ID, o mesmo que a tela do Proton mostra. O runner
+o entrega em `PROTON_CORRELATION_ID` (runner 5.0.8 em diante), e a biblioteca o
+envia em toda chamada ao Proton (`X-Correlation-Id` e `traceparent`, no formato
+W3C Trace Context).
+
+Para levá-lo às chamadas que a automação faz (SAP, APIs, portais), use
+`correlation_headers()`. Com ele, o log do sistema chamado se acha pelo id da
+execução:
+
+```python
+import requests
+from proton.proton_env import correlation_headers, get_correlation_id
+
+requests.post(url, json=pedido, headers={**correlation_headers(), "Authorization": token})
+log_info(f"Pedido enviado ({get_correlation_id()})")
+```
+
+Fora do Proton, ou com um runner que ainda não entrega o id, `correlation_headers()`
+devolve um dicionário vazio.
+
 ### Categoria do dataset (Proton 4)
 
 No Proton 5 o dataset não tem categoria. `get_dataset_category()` e
@@ -237,12 +284,35 @@ from proton.run_status import RunStatus
 update_run_status(RunStatus.FAILED)
 ```
 
-O Proton 5 aceita `RUNNING`, `PASSED` e `FAILED`. Os status do Proton 4
-(`FAILED_DATA`, `FAILED_ENVIRONMENT` e `IN_PROCESS`) não existem mais: o servidor
-os recusa, e a biblioteca envia `FAILED` no lugar dos dois primeiros e `RUNNING`
-no lugar do último, com um `DeprecationWarning` e uma linha `[proton]` no log na
-primeira vez. Para separar falha de dados de falha de ambiente, registre o
-motivo no log da execução.
+O Proton 5 aceita `RUNNING`, `PASSED` e `FAILED`. Junto com o `FAILED`, o motivo
+diz por que a execução falhou, sem mudar o status:
+
+```python
+from proton.run_status import FailureReason
+
+update_run_status(RunStatus.FAILED, reason=FailureReason.BUSINESS)
+```
+
+| Motivo | Quando |
+|---|---|
+| `FailureReason.BUSINESS` | A regra de negócio não deixou seguir: cadastro que já existe, nota já recusada. Repetir dá o mesmo resultado. |
+| `FailureReason.TECHNICAL` | Qualquer outro erro: elemento que não apareceu, sistema fora do ar, exceção do código. É o padrão. |
+| `FailureReason.ENVIRONMENT` | O ambiente não deixou rodar: dependência que falta, configuração errada. |
+
+Com o executor de componentes, basta lançar `ProtonBusinessError` no passo: ele grava
+a falha com o motivo de negócio. Qualquer outra exceção conta como técnica.
+
+```python
+from proton.run_status import ProtonBusinessError
+
+if cadastro_existe:
+    raise ProtonBusinessError(f"O CNPJ {cnpj} já está cadastrado")
+```
+
+Os status do Proton 4 (`FAILED_DATA`, `FAILED_ENVIRONMENT` e `IN_PROCESS`) não
+existem mais: o servidor os recusa, e a biblioteca envia `FAILED` no lugar dos dois
+primeiros, com o motivo de negócio e de ambiente, e `RUNNING` no lugar do último,
+com um `DeprecationWarning` e uma linha `[proton]` no log na primeira vez.
 
 ## Executor de componentes
 
@@ -278,7 +348,8 @@ A cada passo, o executor:
   para cima (`forward_logs=False` desliga).
 
 No fim, grava `PASSED` quando não sobra passo. Quando um passo falha, grava o
-stack trace no painel de erro, grava `FAILED` e relança a exceção. Execução parada
+stack trace no painel de erro, grava `FAILED` com o motivo (de negócio para
+`ProtonBusinessError`, técnico para o resto) e relança a exceção. Execução parada
 não recebe status por cima.
 
 Um projeto pode cuidar de várias plataformas (SAP, web, API, desktop), cada uma

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "protoncloud-sdk"
-version = "5.3.2"
+version = "5.4.0"
 description = "Proton Cloud SDK para Python: execução de automações, ambientes, logs, parâmetros e recursos."
 readme = "README.md"
 requires-python = ">=3.10"

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/src/proton/component_runner.py

@@ -39,7 +39,7 @@ from typing import Callable, Optional, Union
 
 from proton import proton_automation, proton_files_and_resources, proton_logs, proton_parameter
 from proton.proton_env import is_proton_execution
-from proton.run_status import RunStatus
+from proton.run_status import FailureReason, ProtonBusinessError, RunStatus
 
 Passo = Callable[[dict], Optional[Mapping]]
 """Um passo: recebe os parâmetros do componente e devolve as saídas (ou `None`)."""
@@ -63,7 +63,15 @@ class ProtonRunError(RuntimeError):
 class ProtonLogHandler(logging.Handler):
     """Manda cada registro do `logging` para o log da execução no Proton."""
 
-    _PREFIXOS = {logging.WARNING: "Aviso: ", logging.ERROR: "Erro: ", logging.CRITICAL: "Erro: "}
+    @staticmethod
+    def _nivel(levelno):
+        if levelno >= logging.CRITICAL:
+            return "critical"
+        if levelno >= logging.ERROR:
+            return "error"
+        if levelno >= logging.WARNING:
+            return "warning"
+        return "info"
 
     def __init__(self, level=logging.INFO):
         super().__init__(level)
@@ -77,7 +85,7 @@ class ProtonLogHandler(logging.Handler):
 
         self._enviando.ativo = True
         try:
-            proton_logs.set_log(self._PREFIXOS.get(record.levelno, "") + self.format(record))
+            proton_logs.set_log(self.format(record), level=self._nivel(record.levelno))
         except Exception:
             self.handleError(record)
         finally:
@@ -195,6 +203,7 @@ def _executar_passo(nome, passo, erro_ao_localizar, evidence_dir):
         raise ProtonRunError(f'O Proton não iniciou o passo "{nome}".')
 
     antes = _arquivos(evidence_dir)
+    passou = False
 
     try:
         logger.info("Passo %s: %s", progresso.get("order", "?"), nome)
@@ -209,6 +218,7 @@ def _executar_passo(nome, passo, erro_ao_localizar, evidence_dir):
 
         saidas = passo(_parametros_do_passo(progresso, nome))
         _gravar_saidas(nome, saidas)
+        passou = True
 
     finally:
         try:
@@ -216,7 +226,10 @@ def _executar_passo(nome, passo, erro_ao_localizar, evidence_dir):
         except Exception:
             logger.exception("Falha ao enviar as evidências do passo %s", nome)
 
-        proton_automation.end_component()
+        # O passo que falhou fica aberto: o Failed da execução (`_registrar_falha`) o fecha
+        # como Failed. O Proton marca como Passed o passo que recebe o fim.
+        if passou:
+            proton_automation.end_component()
 
 
 def _parametros_do_passo(progresso, nome):
@@ -302,7 +315,9 @@ def _registrar_falha(erro):
             return
 
         proton_logs.set_error_log("".join(traceback.format_exception(type(erro), erro, erro.__traceback__)))
-        proton_automation.update_run_status(RunStatus.FAILED)
+        # A regra de negócio que não deixou seguir é uma falha à parte: repetir dá o mesmo.
+        motivo = FailureReason.BUSINESS if isinstance(erro, ProtonBusinessError) else FailureReason.TECHNICAL
+        proton_automation.update_run_status(RunStatus.FAILED, reason=motivo)
     except Exception:
         # A falha original é a que importa: um erro ao registrá-la não pode escondê-la.
         logger.exception("Falha ao registrar o erro da execução no Proton")

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/src/proton/proton_automation.py

@@ -4,7 +4,7 @@ import warnings
 import requests
 from proton.proton_env import get_api_url, get_auth_header, get_host, get_id_dataset_run, is_proton_execution
 from proton.proton_environment import ProtonEnvironmentError, load_environment, mask_environment_values
-from proton.run_status import STATUS_DO_PROTON_4, RunStatus
+from proton.run_status import MOTIVO_DO_PROTON_4, STATUS_DO_PROTON_4, FailureReason, RunStatus
 
 
 def _get_dataset_run_url():
@@ -79,17 +79,24 @@ def end_component():
 _status_avisados = set()
 
 
-def update_run_status(status:RunStatus):
+def update_run_status(status:RunStatus, reason=None):
     """
     Atualiza o status da execução.
 
+    `reason`, só com o `FAILED`: por que falhou (`FailureReason.BUSINESS`, `TECHNICAL` ou
+    `ENVIRONMENT`, ou o texto deles). Sem motivo, o Proton conta a falha como técnica.
+
     Os status do Proton 4 (`FAILED_DATA`, `FAILED_ENVIRONMENT` e `IN_PROCESS`) não existem
     no Proton 5, que os recusa com HTTP 400. A biblioteca envia "Failed" no lugar dos dois
-    primeiros e "Running" no lugar do último, com `DeprecationWarning` e, na primeira vez,
-    uma linha `[proton]` no log.
+    primeiros, com o motivo de negócio e de ambiente, e "Running" no lugar do último, com
+    `DeprecationWarning` e, na primeira vez, uma linha `[proton]` no log.
     """
     if is_proton_execution():
         status_value = status.value if isinstance(status, RunStatus) else str(status)
+        motivo = reason.value if isinstance(reason, FailureReason) else (str(reason) if reason else None)
+
+        if motivo is None and status_value in MOTIVO_DO_PROTON_4:
+            motivo = MOTIVO_DO_PROTON_4[status_value]
 
         if status_value in STATUS_DO_PROTON_4:
             novo = STATUS_DO_PROTON_4[status_value]
@@ -102,7 +109,12 @@ def update_run_status(status:RunStatus):
 
             status_value = novo
 
-        _request_json("PUT", f"{_get_dataset_run_url()}/update-status", body={"status": status_value})
+        corpo = {"status": status_value}
+
+        if motivo and status_value == RunStatus.FAILED.value:
+            corpo["reason"] = motivo
+
+        _request_json("PUT", f"{_get_dataset_run_url()}/update-status", body=corpo)
 
 def get_current_component_system():
     """

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/src/proton/proton_env.py

@@ -1,5 +1,7 @@
 from configparser import ConfigParser
 import os
+import re
+import secrets
 
 
 def _is_localhost(host):
@@ -153,6 +155,49 @@ def get_api_url(path):
     """
     return f"{get_host().rstrip('/')}/{str(path).lstrip('/')}"
 
+_ID_VALIDO = re.compile(r'^[A-Za-z0-9-]{8,64}$')
+
+
+def get_correlation_id():
+    """
+    O Correlation ID da execução: o mesmo id que a tela do Proton mostra, que o runner
+    entrega em `PROTON_CORRELATION_ID` (runner 5.0.8 em diante).
+
+    Returns:
+        str: O id, ou string vazia fora do Proton ou com um runner que ainda não o entrega.
+    """
+    valor = (os.getenv('PROTON_CORRELATION_ID') or '').strip()
+    return valor if _ID_VALIDO.match(valor) else ''
+
+
+def correlation_headers():
+    """
+    Os cabeçalhos que levam o Correlation ID às chamadas que a automação faz (SAP, APIs,
+    portais): `X-Correlation-Id` e `traceparent` (W3C Trace Context, com o UUID da execução
+    como trace-id). Com eles, o log do sistema chamado se acha pelo mesmo id da execução.
+
+        import requests
+        from proton.proton_env import correlation_headers
+
+        requests.post(url, json=pedido, headers={**correlation_headers(), 'Authorization': token})
+
+    Returns:
+        dict: Os cabeçalhos, ou um dicionário vazio quando não há Correlation ID.
+    """
+    correlation_id = get_correlation_id()
+
+    if not correlation_id:
+        return {}
+
+    cabecalhos = {'X-Correlation-Id': correlation_id}
+    trace_id = correlation_id.replace('-', '').lower()
+
+    if len(trace_id) == 32 and all(letra in '0123456789abcdef' for letra in trace_id):
+        cabecalhos['traceparent'] = f'00-{trace_id}-{secrets.token_hex(8)}-01'
+
+    return cabecalhos
+
+
 def get_auth_header():
     """
     Gera o cabeçalho de autenticação para requisições HTTP, baseado no token do Proton.
@@ -171,7 +216,8 @@ def get_auth_header():
     if token.lower().startswith('bearer '):
         token = token[len('bearer '):].strip()
 
-    return {'Authorization': f'Bearer {token}'}
+    # O Correlation ID vai junto: o log do Proton acha a requisição pelo id da execução.
+    return {'Authorization': f'Bearer {token}', **correlation_headers()}
 
 def get_id_dataset_run():
     """

protoncloud_sdk-5.4.0/src/proton/proton_logs.py

@@ -0,0 +1,138 @@
+import json
+import traceback
+from datetime import datetime
+
+import requests
+
+from proton.proton_env import get_auth_header, get_host, get_id_dataset_run, is_proton_execution
+from proton.proton_environment import mask_environment_values
+
+LEVELS = ("info", "warning", "error", "critical")
+"""Os níveis do log da execução: Informação, Alerta, Erro e Crítico."""
+
+_APELIDOS = {"warn": "warning", "fatal": "critical", "debug": "info", "err": "error"}
+
+
+def _nivel(level):
+    nivel = str(level or "info").strip().lower()
+    nivel = _APELIDOS.get(nivel, nivel)
+    return nivel if nivel in LEVELS else "info"
+
+
+def _contexto(context):
+    """O contexto como objeto JSON, com os valores do ambiente mascarados; `None` quando não serve."""
+    if not isinstance(context, dict) or not context:
+        return None
+
+    try:
+        texto = mask_environment_values(json.dumps(context, ensure_ascii=False, default=str))
+        return json.loads(texto)
+    except (TypeError, ValueError):
+        return {"masked": True}
+
+
+def _ecoar(log_message, nivel):
+    """
+    Escreve a linha na saída do processo, com a hora e o nível. O runner sobe essa saída
+    como o arquivo de log da execução: acima do limite do log no Proton, é nele que o
+    log completo fica.
+    """
+    agora = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+    print(f"{agora} [{nivel.upper()}] {log_message}", flush=True)
+
+
+def set_log(log_message, disable_date_time=False, level="info", context=None):
+    """
+    Envia uma entrada de log.
+
+    Args:
+        log_message: O texto da linha.
+        disable_date_time: Sem a data na frente, no texto do log (para blocos em Markdown).
+        level: O nível: "info" (padrão), "warning", "error" ou "critical". Aceita também os
+            nomes do `logging` ("WARN", "FATAL").
+        context: Um `dict` opcional que vai junto com a linha (o item processado, a
+            tentativa, o código de retorno). A tela mostra ao abrir a linha.
+
+    Os valores do ambiente da execução saem mascarados (`••••••`), no log do Proton, no
+    contexto e no print (ver `mask_environment_values`). Numa execução do Proton, a linha
+    também sai na saída do processo, com a hora e o nível.
+    """
+    log_message = mask_environment_values(log_message)
+    nivel = _nivel(level)
+
+    if is_proton_execution():
+        dataset_run_id = get_id_dataset_run()
+
+        if dataset_run_id is not None:
+            _ecoar(log_message, nivel)
+            url = f"{get_host()}/dataset-run-log/{dataset_run_id}"
+
+            body = {
+                "idDatasetRun": dataset_run_id,
+                "log": log_message,
+                "disableDateTime": disable_date_time,
+                "level": nivel,
+            }
+
+            contexto = _contexto(context)
+            if contexto:
+                body["context"] = contexto
+
+            return requests.put(url, json=body, headers=get_auth_header())
+    else:
+        print(log_message)
+
+    return None
+
+
+def log_info(log_message, context=None):
+    """Uma linha de Informação no log da execução."""
+    return set_log(log_message, level="info", context=context)
+
+
+def log_warning(log_message, context=None):
+    """Uma linha de Alerta: algo fora do esperado que não parou a execução."""
+    return set_log(log_message, level="warning", context=context)
+
+
+def log_error(log_message, context=None):
+    """Uma linha de Erro."""
+    return set_log(log_message, level="error", context=context)
+
+
+def log_critical(log_message, context=None):
+    """Uma linha Crítica: o que precisa de atenção imediata."""
+    return set_log(log_message, level="critical", context=context)
+
+
+def set_error_log(error_message):
+    """
+    Envia um log de erro estruturado para o Proton.
+
+    Os valores do ambiente da execução saem mascarados (`••••••`), como em `set_log`.
+    """
+    error_message = mask_environment_values(error_message)
+
+    if is_proton_execution():
+        dataset_run_id = get_id_dataset_run()
+
+        if dataset_run_id is not None:
+            url = f"{get_host()}/dataset-run/{dataset_run_id}/error"
+            body = {
+                "idDatasetRun": dataset_run_id,
+                "error": error_message,
+            }
+
+            return requests.put(url, json=body, headers=get_auth_header())
+    else:
+        print(error_message)
+
+    return None
+
+# ATENÇÃO -----------------
+def set_log_from_exception(e):
+    """Envia o stack trace da exceção como uma linha de Erro do log."""
+    stack_trace = "".join(traceback.format_exception(type(e), e, e.__traceback__))
+    # Mascara o stack trace inteiro de uma vez: um valor com quebra de linha (uma chave,
+    # por exemplo) escaparia da máscara linha a linha.
+    set_log(mask_environment_values(stack_trace).rstrip(), level="error")

protoncloud_sdk-5.4.0/src/proton/run_status.py

@@ -0,0 +1,60 @@
+from enum import Enum
+
+class RunStatus(Enum):
+    RUNNING = "Running"
+    PASSED = "Passed"
+    FAILED = "Failed"
+
+    # Status do Proton 4. O Proton 5 não os tem e responde 400 (invalidRunStatus);
+    # `update_run_status` envia "Failed" no lugar dos dois primeiros e "Running" no
+    # lugar do último, com um aviso de obsolescência.
+    FAILED_DATA = "Failed (Dados)"
+    FAILED_ENVIRONMENT = "Failed (Ambiente)"
+    IN_PROCESS = "In Process"
+
+
+STATUS_DO_PROTON_4 = {
+    RunStatus.FAILED_DATA.value: RunStatus.FAILED.value,
+    RunStatus.FAILED_ENVIRONMENT.value: RunStatus.FAILED.value,
+    RunStatus.IN_PROCESS.value: RunStatus.RUNNING.value,
+}
+"""Status do Proton 4 e o status do Proton 5 que a biblioteca envia no lugar."""
+
+
+class FailureReason(Enum):
+    """
+    Por que a execução falhou, junto com o "Failed". O status continua o mesmo; o motivo
+    é um campo à parte, que a tela e os painéis usam para separar a falha do robô da falha
+    por regra de negócio.
+    """
+
+    BUSINESS = "business_error"
+    """A regra de negócio não deixou seguir: cadastro já existe, nota já recusada."""
+
+    TECHNICAL = "technical_error"
+    """Qualquer outro erro: elemento que não apareceu, sistema fora do ar, exceção do código."""
+
+    ENVIRONMENT = "environment_error"
+    """O ambiente não deixou rodar: projeto que não prepara, dependência que falta."""
+
+
+MOTIVO_DO_PROTON_4 = {
+    RunStatus.FAILED_DATA.value: FailureReason.BUSINESS.value,
+    RunStatus.FAILED_ENVIRONMENT.value: FailureReason.ENVIRONMENT.value,
+}
+"""Os "Failed" do Proton 4 viram o motivo no Proton 5: o que separavam continua separado."""
+
+
+class ProtonBusinessError(Exception):
+    """
+    Falha de negócio: a regra não deixou seguir, e repetir dá o mesmo resultado (cadastro
+    que já existe, nota já recusada, saldo insuficiente). Lance no passo:
+
+        from proton.run_status import ProtonBusinessError
+
+        if cadastro_existe:
+            raise ProtonBusinessError(f"O CNPJ {cnpj} já está cadastrado")
+
+    O executor de componentes grava a execução como Falhou com o motivo de negócio. Qualquer
+    outra exceção conta como falha técnica.
+    """

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/tests/test_component_runner.py

@@ -10,7 +10,7 @@ import pytest
 
 from proton import component_runner, proton_automation, proton_files_and_resources, proton_logs, proton_parameter
 from proton.component_runner import ProtonRunError, run_components
-from proton.run_status import RunStatus
+from proton.run_status import FailureReason, ProtonBusinessError, RunStatus
 
 
 class ProtonFalso:
@@ -25,11 +25,14 @@ class ProtonFalso:
         self.eventos = []
         self.saidas = []
         self.logs = []
+        self.niveis = []
+        self.motivo = None
         self.erros = []
         self.imagens = []
         self.arquivos = []
         self.saidas_fora_do_passo = set()
         self.inicio_falha = False
+        self.status_dos_passos = []
 
     def _pendente(self):
         return self.passos[self.atual] if self.atual < len(self.passos) else None
@@ -55,7 +58,9 @@ class ProtonFalso:
         return {"id": 100 + self.atual, "order": passo["ordem"], "component": passo["nome"]}
 
     def finalizar(self):
+        # Como no Proton: o passo que recebe o fim fica Passed.
         self.chamadas.append("end")
+        self.status_dos_passos.append((self.aberto["nome"], "Passed"))
         self.aberto = None
         return 2
 
@@ -66,6 +71,10 @@ class ProtonFalso:
             for p in self.passos
         ]
 
+    def registrar_log(self, mensagem, disable_date_time=False, level="info", context=None):
+        self.logs.append(mensagem)
+        self.niveis.append((mensagem, level))
+
     def gravar_saida(self, parametro, valor):
         if parametro in self.saidas_fora_do_passo:
             return 404
@@ -73,10 +82,16 @@ class ProtonFalso:
         self.saidas.append((self.aberto["nome"], parametro, valor))
         return 200
 
-    def atualizar_status(self, status):
+    def atualizar_status(self, status, reason=None):
         self.status = status.value
+        self.motivo = reason
         self.eventos.append(f"status {status.value}")
 
+        # Como no Proton: a execução que falha (ou para) fecha o passo aberto com o mesmo status.
+        if status.value in ("Failed", "Stopped") and self.aberto:
+            self.status_dos_passos.append((self.aberto["nome"], status.value))
+            self.aberto = None
+
 
 @pytest.fixture
 def proton(monkeypatch):
@@ -92,7 +107,7 @@ def proton(monkeypatch):
         monkeypatch.setattr(proton_automation, "get_dataset_run_status", lambda *a: falso.status)
         monkeypatch.setattr(proton_parameter, "get_proton_all_component_parameters", falso.parametros)
         monkeypatch.setattr(proton_parameter, "set_proton_value", falso.gravar_saida)
-        monkeypatch.setattr(proton_logs, "set_log", falso.logs.append)
+        monkeypatch.setattr(proton_logs, "set_log", falso.registrar_log)
         monkeypatch.setattr(proton_logs, "set_error_log", falso.erros.append)
         monkeypatch.setattr(proton_files_and_resources, "upload_image", falso.imagens.append)
         monkeypatch.setattr(proton_files_and_resources, "upload_file_resource", falso.arquivos.append)
@@ -125,6 +140,7 @@ def test_roda_os_passos_na_ordem_com_os_parametros_de_cada_um(proton):
         ("AdicionarAoCarrinho", {"in_produto": "Mochila", "out_preco": ""}),
     ]
     assert falso.chamadas == ["start", "end", "start", "end"]
+    assert falso.status_dos_passos == [("FazerLogin", "Passed"), ("AdicionarAoCarrinho", "Passed")]
     assert falso.saidas == [("AdicionarAoCarrinho", "out_preco", "29.99")]
     assert falso.status == RunStatus.PASSED.value
 
@@ -149,7 +165,7 @@ def test_o_mesmo_componente_duas_vezes_recebe_os_parametros_da_sua_posicao(proto
     assert produtos == ["Mochila", "Lanterna"]
 
 
-def test_passo_que_falha_fecha_o_passo_grava_o_erro_real_e_para(proton):
+def test_passo_que_falha_fica_failed_grava_o_erro_real_e_para(proton):
     falso = proton([
         {"nome": "FazerLogin", "ordem": 1},
         {"nome": "FinalizarCompra", "ordem": 2},
@@ -161,12 +177,51 @@ def test_passo_que_falha_fecha_o_passo_grava_o_erro_real_e_para(proton):
     with pytest.raises(AssertionError, match="login recusado"):
         run_components({"FazerLogin": login_recusado, "FinalizarCompra": lambda p: None})
 
-    assert falso.chamadas == ["start", "end"]
+    # Sem o fim do passo, que o Proton gravaria como Passed: o Failed da execução o fecha.
+    assert falso.chamadas == ["start"]
+    assert falso.status_dos_passos == [("FazerLogin", "Failed")]
     assert falso.status == RunStatus.FAILED.value
     assert len(falso.erros) == 1
     # O stack trace é o do passo, e não o da maquinaria de chamada.
     assert "login_recusado" in falso.erros[0]
     assert "AssertionError: login recusado" in falso.erros[0]
+    # Erro qualquer é falha técnica.
+    assert falso.motivo == FailureReason.TECHNICAL
+
+
+def test_falha_de_negocio_vai_com_o_motivo_de_negocio(proton):
+    falso = proton([{"nome": "CadastrarFornecedor", "ordem": 1}])
+
+    def cadastro_existente(params):
+        raise ProtonBusinessError("O CNPJ 12.345.678/0001-90 já está cadastrado")
+
+    with pytest.raises(ProtonBusinessError):
+        run_components({"CadastrarFornecedor": cadastro_existente})
+
+    assert falso.status == RunStatus.FAILED.value
+    assert falso.motivo == FailureReason.BUSINESS
+    assert "já está cadastrado" in falso.erros[0]
+
+
+def test_o_nivel_do_logging_vira_o_nivel_do_log(proton):
+    falso = proton([{"nome": "FazerLogin", "ordem": 1}])
+    log = logging.getLogger("automacao")
+
+    def passo(params):
+        log.info("abrindo")
+        log.warning("demorou")
+        log.error("falhou a primeira vez")
+        log.critical("sem sistema")
+
+    run_components({"FazerLogin": passo})
+
+    niveis = dict(falso.niveis)
+    assert niveis["abrindo"] == "info"
+    assert niveis["demorou"] == "warning"
+    assert niveis["falhou a primeira vez"] == "error"
+    assert niveis["sem sistema"] == "critical"
+    # Sem o prefixo de antes: o nível vai à parte.
+    assert "Aviso: demorou" not in falso.logs
 
 
 def test_componente_que_nao_existe_no_projeto(proton):
@@ -175,7 +230,8 @@ def test_componente_que_nao_existe_no_projeto(proton):
     with pytest.raises(ProtonRunError, match='"Inexistente" não existe'):
         run_components({})
 
-    assert falso.chamadas == ["start", "end"]
+    assert falso.chamadas == ["start"]
+    assert falso.status_dos_passos == [("Inexistente", "Failed")]
     assert falso.status == RunStatus.FAILED.value
 
 
@@ -232,7 +288,8 @@ def test_componente_que_falta_no_mesmo_sistema_falha_em_vez_de_devolver_ao_runne
     with pytest.raises(ProtonRunError, match='"Esquecido" não existe'):
         run_components({"FazerLogin": lambda p: None})
 
-    assert falso.chamadas == ["start", "end", "start", "end"]
+    assert falso.chamadas == ["start", "end", "start"]
+    assert falso.status_dos_passos == [("FazerLogin", "Passed"), ("Esquecido", "Failed")]
     assert falso.status == RunStatus.FAILED.value
 
 
@@ -245,7 +302,8 @@ def test_erro_ao_procurar_o_componente_marca_o_passo_e_falha(proton):
     with pytest.raises(ImportError, match="biblioteca do SAP"):
         run_components(localizar)
 
-    assert falso.chamadas == ["start", "end"]
+    assert falso.chamadas == ["start"]
+    assert falso.status_dos_passos == [("FazerLogin", "Failed")]
     assert falso.status == RunStatus.FAILED.value
 
 
@@ -276,7 +334,7 @@ def test_saida_fora_do_passo_avisa_sem_falhar(proton, caplog):
     run_components({"FinalizarCompra": lambda p: {"out_total": "32.39"}})
 
     assert falso.status == RunStatus.PASSED.value
-    assert any("out_total" in log and log.startswith("Aviso: ") for log in falso.logs)
+    assert any("out_total" in log and nivel == "warning" for log, nivel in falso.niveis)
 
 
 def test_saida_que_nao_e_dict_falha(proton):

protoncloud_sdk-5.4.0/tests/test_observabilidade.py

@@ -0,0 +1,135 @@
+"""
+Observabilidade da execução (Proton 5, migration 01054): o nível e o contexto de cada
+linha do log, a linha na saída do processo, o motivo da falha e o Correlation ID.
+"""
+
+import json
+
+import pytest
+
+from proton import proton_automation, proton_env, proton_logs
+from proton.run_status import FailureReason, RunStatus
+
+
+class Resposta:
+    status_code = 200
+    text = "{}"
+    url = "https://proton.test/api/x"
+
+    def json(self):
+        return {}
+
+
+@pytest.fixture
+def execucao(monkeypatch):
+    """Uma execução do Proton, com o token e o Correlation ID que o runner entrega."""
+    monkeypatch.setenv("idDatasetRun", "42")
+    monkeypatch.setenv("PROTON_HOST", "https://proton.test/api")
+    monkeypatch.setenv("PROTON_TOKEN", "proton_run_teste")
+    monkeypatch.setenv("PROTON_CORRELATION_ID", "3f2a9c1e-5b7d-4e0a-9c11-2d3e4f5a6b7c")
+    monkeypatch.setattr(proton_logs, "is_proton_execution", lambda: True)
+    monkeypatch.setattr(proton_automation, "is_proton_execution", lambda: True)
+    monkeypatch.setattr(proton_env, "is_proton_execution", lambda: True)
+    chamadas = []
+
+    def put(url, json=None, headers=None):
+        chamadas.append({"url": url, "json": json, "headers": headers})
+        return Resposta()
+
+    def request(method, url, params=None, json=None, headers=None):
+        chamadas.append({"method": method, "url": url, "json": json, "headers": headers})
+        return Resposta()
+
+    monkeypatch.setattr(proton_logs.requests, "put", put)
+    monkeypatch.setattr(proton_automation.requests, "request", request)
+    return chamadas
+
+
+def test_a_linha_vai_com_o_nivel_e_o_contexto(execucao):
+    proton_logs.set_log("Cadastro já existe", level="WARN", context={"cnpj": "12.345.678/0001-90"})
+
+    corpo = execucao[0]["json"]
+    assert corpo["level"] == "warning"
+    assert corpo["context"] == {"cnpj": "12.345.678/0001-90"}
+    assert corpo["log"] == "Cadastro já existe"
+
+
+def test_sem_nivel_e_informacao_e_os_atalhos_dao_o_nivel(execucao):
+    proton_logs.set_log("abrindo")
+    proton_logs.log_warning("demorou")
+    proton_logs.log_error("falhou")
+    proton_logs.log_critical("sem sistema", context={"tentativas": 3})
+
+    assert [chamada["json"]["level"] for chamada in execucao] == ["info", "warning", "error", "critical"]
+    assert execucao[3]["json"]["context"] == {"tentativas": 3}
+    assert "context" not in execucao[0]["json"]
+
+
+def test_a_linha_tambem_sai_na_saida_do_processo_com_hora_e_nivel(execucao, capsys):
+    proton_logs.log_error("Timeout no LoginSAP")
+
+    saida = capsys.readouterr().out
+    assert "[ERROR] Timeout no LoginSAP" in saida
+
+
+def test_o_segredo_do_ambiente_sai_mascarado_tambem_no_contexto(execucao, monkeypatch):
+    monkeypatch.setattr(proton_logs, "mask_environment_values", lambda texto: texto.replace("senha123", "••••••"))
+
+    proton_logs.set_log("login com senha123", context={"senha": "senha123"})
+
+    corpo = execucao[0]["json"]
+    assert "senha123" not in corpo["log"]
+    assert "senha123" not in json.dumps(corpo["context"], ensure_ascii=False)
+
+
+def test_o_stack_trace_vai_numa_linha_so_de_erro(execucao):
+    try:
+        raise ValueError("valor inválido")
+    except ValueError as erro:
+        proton_logs.set_log_from_exception(erro)
+
+    assert len(execucao) == 1
+    assert execucao[0]["json"]["level"] == "error"
+    assert "ValueError: valor inválido" in execucao[0]["json"]["log"]
+
+
+def test_o_motivo_da_falha_vai_junto_do_failed(execucao):
+    proton_automation.update_run_status(RunStatus.FAILED, reason=FailureReason.BUSINESS)
+    proton_automation.update_run_status(RunStatus.PASSED, reason=FailureReason.BUSINESS)
+    proton_automation.update_run_status(RunStatus.FAILED)
+
+    assert execucao[0]["json"] == {"status": "Failed", "reason": "business_error"}
+    assert execucao[1]["json"] == {"status": "Passed"}, "o motivo só vale para o Failed"
+    assert execucao[2]["json"] == {"status": "Failed"}
+
+
+def test_os_failed_do_proton_4_viram_o_motivo(execucao):
+    with pytest.warns(DeprecationWarning):
+        proton_automation.update_run_status(RunStatus.FAILED_DATA)
+    with pytest.warns(DeprecationWarning):
+        proton_automation.update_run_status(RunStatus.FAILED_ENVIRONMENT)
+
+    assert execucao[0]["json"] == {"status": "Failed", "reason": "business_error"}
+    assert execucao[1]["json"] == {"status": "Failed", "reason": "environment_error"}
+
+
+def test_o_correlation_id_vai_em_toda_chamada_ao_proton(execucao):
+    proton_logs.set_log("abrindo")
+
+    cabecalhos = execucao[0]["headers"]
+    assert cabecalhos["X-Correlation-Id"] == "3f2a9c1e-5b7d-4e0a-9c11-2d3e4f5a6b7c"
+    versao, trace_id, span_id, flags = cabecalhos["traceparent"].split("-")
+    assert (versao, trace_id, flags) == ("00", "3f2a9c1e5b7d4e0a9c112d3e4f5a6b7c", "01")
+    assert len(span_id) == 16
+
+
+def test_correlation_headers_para_as_chamadas_da_automacao(monkeypatch):
+    monkeypatch.setenv("PROTON_CORRELATION_ID", "3f2a9c1e-5b7d-4e0a-9c11-2d3e4f5a6b7c")
+    assert proton_env.correlation_headers()["X-Correlation-Id"] == "3f2a9c1e-5b7d-4e0a-9c11-2d3e4f5a6b7c"
+
+    monkeypatch.setenv("PROTON_CORRELATION_ID", "<script>")
+    assert proton_env.correlation_headers() == {}
+
+    monkeypatch.delenv("PROTON_CORRELATION_ID")
+    assert proton_env.get_correlation_id() == ""
+    assert proton_env.correlation_headers() == {}

{protoncloud_sdk-5.3.2 → protoncloud_sdk-5.4.0}/tests/test_run_status.py

@@ -52,19 +52,20 @@ def test_status_do_proton_5_vai_como_veio(enviados, recwarn, status, esperado):
 
 
 @pytest.mark.parametrize(
-    "status, esperado",
+    "status, esperado, motivo",
     [
-        (RunStatus.FAILED_DATA, "Failed"),
-        (RunStatus.FAILED_ENVIRONMENT, "Failed"),
-        (RunStatus.IN_PROCESS, "Running"),
-        ("Failed (Dados)", "Failed"),
+        (RunStatus.FAILED_DATA, "Failed", "business_error"),
+        (RunStatus.FAILED_ENVIRONMENT, "Failed", "environment_error"),
+        (RunStatus.IN_PROCESS, "Running", None),
+        ("Failed (Dados)", "Failed", "business_error"),
     ],
 )
-def test_status_do_proton_4_vira_o_do_proton_5(enviados, capsys, status, esperado):
+def test_status_do_proton_4_vira_o_do_proton_5(enviados, capsys, status, esperado, motivo):
     with pytest.warns(DeprecationWarning, match="não existe no Proton 5"):
         proton_automation.update_run_status(status)
 
-    assert enviados[0][2] == {"status": esperado}
+    # O que o Failed do Proton 4 separava (dados, ambiente) segue como o motivo da falha.
+    assert enviados[0][2] == ({"status": esperado, "reason": motivo} if motivo else {"status": esperado})
     assert f'a execução recebe "{esperado}"' in capsys.readouterr().out
 
 
@@ -74,7 +75,7 @@ def test_aviso_no_log_so_na_primeira_vez(enviados, capsys):
         proton_automation.update_run_status(RunStatus.FAILED_DATA)
 
     assert capsys.readouterr().out.count("[proton]") == 1
-    assert [corpo for _, _, corpo in enviados] == [{"status": "Failed"}, {"status": "Failed"}]
+    assert [corpo for _, _, corpo in enviados] == [{"status": "Failed", "reason": "business_error"}] * 2
 
 
 def test_fora_do_proton_nao_envia(monkeypatch, enviados):

protoncloud_sdk-5.3.2/src/proton/proton_logs.py

@@ -1,68 +0,0 @@
-import traceback
-
-import requests
-
-from proton.proton_env import get_auth_header, get_host, get_id_dataset_run, is_proton_execution
-from proton.proton_environment import mask_environment_values
-
-
-def set_log(log_message, disable_date_time=False):
-    """
-    Envia uma entrada de log.
-
-    Os valores do ambiente da execução saem mascarados (`••••••`), no log do Proton e no
-    print de fora dele (ver `mask_environment_values`).
-    """
-    log_message = mask_environment_values(log_message)
-
-    if is_proton_execution():
-        dataset_run_id = get_id_dataset_run()
-
-        if dataset_run_id is not None:
-            url = f"{get_host()}/dataset-run-log/{dataset_run_id}"
-
-            body = {
-                "idDatasetRun": dataset_run_id,
-                "log": log_message,
-                "disableDateTime": disable_date_time,
-            }
-
-            return requests.put(url, json=body, headers=get_auth_header())
-    else:
-        print(log_message)
-
-    return None
-
-
-def set_error_log(error_message):
-    """
-    Envia um log de erro estruturado para o Proton.
-
-    Os valores do ambiente da execução saem mascarados (`••••••`), como em `set_log`.
-    """
-    error_message = mask_environment_values(error_message)
-
-    if is_proton_execution():
-        dataset_run_id = get_id_dataset_run()
-
-        if dataset_run_id is not None:
-            url = f"{get_host()}/dataset-run/{dataset_run_id}/error"
-            body = {
-                "idDatasetRun": dataset_run_id,
-                "error": error_message,
-            }
-
-            return requests.put(url, json=body, headers=get_auth_header())
-    else:
-        print(error_message)
-
-    return None
-
-# ATENÇÃO -----------------
-def set_log_from_exception(e):
-    """Envia um log de exceção formatando o stack trace"""
-    stack_trace = "".join(traceback.format_exception(type(e), e, e.__traceback__))
-    # Mascara o stack trace inteiro antes de quebrar em linhas: um valor com quebra de
-    # linha (uma chave, por exemplo) escaparia da máscara linha a linha.
-    for line in mask_environment_values(stack_trace).splitlines():
-        set_log(line)

protoncloud_sdk-5.3.2/src/proton/run_status.py

@@ -1,21 +0,0 @@
-from enum import Enum
-
-class RunStatus(Enum):
-    RUNNING = "Running"
-    PASSED = "Passed"
-    FAILED = "Failed"
-
-    # Status do Proton 4. O Proton 5 não os tem e responde 400 (invalidRunStatus);
-    # `update_run_status` envia "Failed" no lugar dos dois primeiros e "Running" no
-    # lugar do último, com um aviso de obsolescência.
-    FAILED_DATA = "Failed (Dados)"
-    FAILED_ENVIRONMENT = "Failed (Ambiente)"
-    IN_PROCESS = "In Process"
-
-
-STATUS_DO_PROTON_4 = {
-    RunStatus.FAILED_DATA.value: RunStatus.FAILED.value,
-    RunStatus.FAILED_ENVIRONMENT.value: RunStatus.FAILED.value,
-    RunStatus.IN_PROCESS.value: RunStatus.RUNNING.value,
-}
-"""Status do Proton 4 e o status do Proton 5 que a biblioteca envia no lugar."""