jaylog 0.2.8__tar.gz → 0.3.0a0__tar.gz

{jaylog-0.2.8 → jaylog-0.3.0a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: jaylog
-Version: 0.2.8
+Version: 0.3.0a0
 Summary: Customized Python logging library with file rotation and HTTP forwarding
 Author: Gpocas
 Author-email: Gpocas <gpocas01@gmail.com>
@@ -45,7 +45,16 @@ As variáveis usam o prefixo `JAYLOG_`. Podem ser definidas no ambiente do siste
 | `JAYLOG_LOG_HTTP_ENDPOINT`      | NÃO          | `null`    | URL do endpoint que receberá os logs                                    |
 | `JAYLOG_LOG_HTTP_API_KEY`       | NÃO          | `null`    | Chave de autenticação enviada no header `x-api-key`                     |
 | `JAYLOG_LOG_HTTP_PROXY`         | NÃO          | `null`    | URL do proxy para o envio HTTP (ex: `http:\\user:password@server:port`) |
+| `JAYLOG_LOG_HTTP_VERIFY`        | NÃO          | `false`   | `true` ou caminho para o bundle de CA usado para validar TLS            |
 | `JAYLOG_LOG_SCREENSHOT_ENABLED` | NÃO          | `false`   | Captura screenshot no momento do log (`true`/`false`, apenas Windows)   |
+| `JAYLOG_HOST_REPORT_ENABLED`    | NÃO          | `true`    | Envia uma fotografia do ambiente no startup                             |
+| `JAYLOG_HOST_HTTP_ENDPOINT`     | NÃO          | derivado  | Override para o endpoint de host; por padrão `/logs/add` vira `/logs/host` |
+| `JAYLOG_HOST_REPORT_TIMEOUT`    | NÃO          | `2 × HTTP_TIMEOUT` | Timeout do POST de ambiente                                     |
+| `JAYLOG_HOST_GIT_ENABLED`       | NÃO          | `true`    | Coleta metadados do repositório Git                                     |
+| `JAYLOG_HOST_GIT_DIRTY_ENABLED` | NÃO          | `true`    | Coleta se há arquivos alterados                                         |
+| `JAYLOG_HOST_GIT_REMOTE_ENABLED`| NÃO          | `true`    | Coleta a URL remota sem credenciais                                     |
+| `JAYLOG_HOST_GIT_TIMEOUT`       | NÃO          | `3.0`     | Timeout, em segundos, de cada chamada ao Git                            |
+| `JAYLOG_HOST_GIT_DIR`           | NÃO          | `null`    | Diretório inicial para localizar o repositório                          |
 
 
 ## Como usar?
@@ -121,6 +130,7 @@ from jaylog import get_logger
 
 logger = get_logger()
 
+
 def parse_csv():
     logger.info("Múltiplos Arquivos - parse.py")
 ```
@@ -138,12 +148,12 @@ __*main.py*__
 ```python
 from jaylog import JaylogSettings, configure, get_logger
 
-settings_order   = JaylogSettings(app_name="ORDER-PROCESSOR")
+settings_order = JaylogSettings(app_name="ORDER-PROCESSOR")
 settings_billing = JaylogSettings(app_name="BILLING")
 
 configure([settings_order, settings_billing])
 
-logger         = get_logger("ORDER-PROCESSOR")  # ou get_logger() — retorna o primeiro registrado
+logger = get_logger("ORDER-PROCESSOR")  # ou get_logger() — retorna o primeiro registrado
 billing_logger = get_logger("BILLING")
 
 logger.info("Pedido recebido")
@@ -191,7 +201,7 @@ __*main.py*__
 ```python
 from jaylog import JaylogSettings, configure, get_logger
 
-configure(JaylogSettings(_env_file='development.env'))
+configure(JaylogSettings(_env_file="development.env"))
 logger = get_logger()
 
 logger.info("Alterando Caminho padrão do .env")
@@ -200,6 +210,32 @@ logger.info("Alterando Caminho padrão do .env")
 
 ## Preparando para produção
 
+## Registro do ambiente
+
+Na versão 0.3, `configure()` inicia em segundo plano um único `POST` JSON para
+o endpoint de host por serviço. O corpo dos logs continua compatível com a
+linha 0.2.x; apenas os headers `x-jaylog-protocol: 2` e `x-jaylog-run-id` são
+adicionados. O `run_id` permite ao backend ligar os logs à execução que os
+produziu.
+
+O endpoint é derivado automaticamente trocando o último segmento de
+`JAYLOG_LOG_HTTP_ENDPOINT`: `https://api.example/logs/add` vira
+`https://api.example/logs/host`. Use `JAYLOG_HOST_HTTP_ENDPOINT` somente quando
+o backend publicar a rota em outro endereço.
+
+O registro inclui sistema operacional, modo de execução, Python, virtualenv,
+Git e diretórios de execução. A URL remota do Git tem sempre a credencial
+embutida removida antes de sair da máquina. Falhas de coleta ou de rede não
+interrompem a aplicação: o envio tenta novamente com backoff. Se o backend
+aceitar um log mas devolver `x-jaylog-host-required: 1`, o jaylog reenvia o
+registro de host com debounce de 30 segundos; o log já foi aceito e não é
+reenviado.
+
+`JAYLOG_LOG_HTTP_VERIFY=false` continua sendo o padrão desta versão para não
+interromper instalações atrás de proxies corporativos. Para validar TLS, use
+`JAYLOG_LOG_HTTP_VERIFY=true` ou informe o caminho do CA bundle corporativo.
+O padrão passará a `true` na 0.4.0.
+
 > [!IMPORTANT]
 > **HTTP_ENDPOINT** e **HTTP_API_KEY** (opcionais) 📢
 >
@@ -232,10 +268,7 @@ __*main.py*__
 ```python
 from jaylog import JaylogSettings, configure, get_logger
 
-configure(JaylogSettings(
-    _env_file='prodution.env',
-    _secrets_dir='/foo/bar/secrets/'
-))
+configure(JaylogSettings(_env_file="prodution.env", _secrets_dir="/foo/bar/secrets/"))
 logger = get_logger()
 
 logger.info("Mensagem de log")
@@ -256,7 +289,7 @@ from jaylog import JaylogSettings, configure, get_logger
 
 # nesse caso é necessário usar a função de classe `reload_secrets`
 # pois o diretorio dos secrets foi passado via variável de ambiente
-configure(JaylogSettings(_env_file='prodution.env').reload_secrets())
+configure(JaylogSettings(_env_file="prodution.env").reload_secrets())
 logger = get_logger()
 
 logger.info("Mensagem de log")
@@ -265,7 +298,7 @@ logger.info("Mensagem de log")
 `reload_secrets()` devolve uma **nova** instância preservando tudo que foi passado explicitamente no construtor, então dá para combinar configuração em código com secrets em disco:
 
 ```python
-settings = JaylogSettings(app_name='meu-bot', log_level='DEBUG').reload_secrets()
+settings = JaylogSettings(app_name="meu-bot", log_level="DEBUG").reload_secrets()
 configure(settings)  # app_name e log_level mantidos; endpoint/api_key vêm dos secrets
 ```
 
@@ -277,10 +310,10 @@ configure(settings)  # app_name e log_level mantidos; endpoint/api_key vêm dos
 `reconfigure()` recria a configuração com os mesmos argumentos do construtor, aplicando apenas os overrides informados. Vale tanto para campos quanto para os argumentos de configuração do pydantic-settings (`_env_file`, `_secrets_dir`, `_case_sensitive`, `_env_prefix`, ...):
 
 ```python
-base = JaylogSettings(app_name='meu-bot', log_level='DEBUG')
+base = JaylogSettings(app_name="meu-bot", log_level="DEBUG")
 
-homolog = base.reconfigure(_env_file='homolog.env')
-prod    = base.reconfigure(_env_file='producao.env', log_level='WARNING')
+homolog = base.reconfigure(_env_file="homolog.env")
+prod = base.reconfigure(_env_file="producao.env", log_level="WARNING")
 # app_name preservado nos dois; só o que foi informado muda
 ```
 

{jaylog-0.2.8 → jaylog-0.3.0a0}/README.md

@@ -26,7 +26,16 @@ As variáveis usam o prefixo `JAYLOG_`. Podem ser definidas no ambiente do siste
 | `JAYLOG_LOG_HTTP_ENDPOINT`      | NÃO          | `null`    | URL do endpoint que receberá os logs                                    |
 | `JAYLOG_LOG_HTTP_API_KEY`       | NÃO          | `null`    | Chave de autenticação enviada no header `x-api-key`                     |
 | `JAYLOG_LOG_HTTP_PROXY`         | NÃO          | `null`    | URL do proxy para o envio HTTP (ex: `http:\\user:password@server:port`) |
+| `JAYLOG_LOG_HTTP_VERIFY`        | NÃO          | `false`   | `true` ou caminho para o bundle de CA usado para validar TLS            |
 | `JAYLOG_LOG_SCREENSHOT_ENABLED` | NÃO          | `false`   | Captura screenshot no momento do log (`true`/`false`, apenas Windows)   |
+| `JAYLOG_HOST_REPORT_ENABLED`    | NÃO          | `true`    | Envia uma fotografia do ambiente no startup                             |
+| `JAYLOG_HOST_HTTP_ENDPOINT`     | NÃO          | derivado  | Override para o endpoint de host; por padrão `/logs/add` vira `/logs/host` |
+| `JAYLOG_HOST_REPORT_TIMEOUT`    | NÃO          | `2 × HTTP_TIMEOUT` | Timeout do POST de ambiente                                     |
+| `JAYLOG_HOST_GIT_ENABLED`       | NÃO          | `true`    | Coleta metadados do repositório Git                                     |
+| `JAYLOG_HOST_GIT_DIRTY_ENABLED` | NÃO          | `true`    | Coleta se há arquivos alterados                                         |
+| `JAYLOG_HOST_GIT_REMOTE_ENABLED`| NÃO          | `true`    | Coleta a URL remota sem credenciais                                     |
+| `JAYLOG_HOST_GIT_TIMEOUT`       | NÃO          | `3.0`     | Timeout, em segundos, de cada chamada ao Git                            |
+| `JAYLOG_HOST_GIT_DIR`           | NÃO          | `null`    | Diretório inicial para localizar o repositório                          |
 
 
 ## Como usar?
@@ -102,6 +111,7 @@ from jaylog import get_logger
 
 logger = get_logger()
 
+
 def parse_csv():
     logger.info("Múltiplos Arquivos - parse.py")
 ```
@@ -119,12 +129,12 @@ __*main.py*__
 ```python
 from jaylog import JaylogSettings, configure, get_logger
 
-settings_order   = JaylogSettings(app_name="ORDER-PROCESSOR")
+settings_order = JaylogSettings(app_name="ORDER-PROCESSOR")
 settings_billing = JaylogSettings(app_name="BILLING")
 
 configure([settings_order, settings_billing])
 
-logger         = get_logger("ORDER-PROCESSOR")  # ou get_logger() — retorna o primeiro registrado
+logger = get_logger("ORDER-PROCESSOR")  # ou get_logger() — retorna o primeiro registrado
 billing_logger = get_logger("BILLING")
 
 logger.info("Pedido recebido")
@@ -172,7 +182,7 @@ __*main.py*__
 ```python
 from jaylog import JaylogSettings, configure, get_logger
 
-configure(JaylogSettings(_env_file='development.env'))
+configure(JaylogSettings(_env_file="development.env"))
 logger = get_logger()
 
 logger.info("Alterando Caminho padrão do .env")
@@ -181,6 +191,32 @@ logger.info("Alterando Caminho padrão do .env")
 
 ## Preparando para produção
 
+## Registro do ambiente
+
+Na versão 0.3, `configure()` inicia em segundo plano um único `POST` JSON para
+o endpoint de host por serviço. O corpo dos logs continua compatível com a
+linha 0.2.x; apenas os headers `x-jaylog-protocol: 2` e `x-jaylog-run-id` são
+adicionados. O `run_id` permite ao backend ligar os logs à execução que os
+produziu.
+
+O endpoint é derivado automaticamente trocando o último segmento de
+`JAYLOG_LOG_HTTP_ENDPOINT`: `https://api.example/logs/add` vira
+`https://api.example/logs/host`. Use `JAYLOG_HOST_HTTP_ENDPOINT` somente quando
+o backend publicar a rota em outro endereço.
+
+O registro inclui sistema operacional, modo de execução, Python, virtualenv,
+Git e diretórios de execução. A URL remota do Git tem sempre a credencial
+embutida removida antes de sair da máquina. Falhas de coleta ou de rede não
+interrompem a aplicação: o envio tenta novamente com backoff. Se o backend
+aceitar um log mas devolver `x-jaylog-host-required: 1`, o jaylog reenvia o
+registro de host com debounce de 30 segundos; o log já foi aceito e não é
+reenviado.
+
+`JAYLOG_LOG_HTTP_VERIFY=false` continua sendo o padrão desta versão para não
+interromper instalações atrás de proxies corporativos. Para validar TLS, use
+`JAYLOG_LOG_HTTP_VERIFY=true` ou informe o caminho do CA bundle corporativo.
+O padrão passará a `true` na 0.4.0.
+
 > [!IMPORTANT]
 > **HTTP_ENDPOINT** e **HTTP_API_KEY** (opcionais) 📢
 >
@@ -213,10 +249,7 @@ __*main.py*__
 ```python
 from jaylog import JaylogSettings, configure, get_logger
 
-configure(JaylogSettings(
-    _env_file='prodution.env',
-    _secrets_dir='/foo/bar/secrets/'
-))
+configure(JaylogSettings(_env_file="prodution.env", _secrets_dir="/foo/bar/secrets/"))
 logger = get_logger()
 
 logger.info("Mensagem de log")
@@ -237,7 +270,7 @@ from jaylog import JaylogSettings, configure, get_logger
 
 # nesse caso é necessário usar a função de classe `reload_secrets`
 # pois o diretorio dos secrets foi passado via variável de ambiente
-configure(JaylogSettings(_env_file='prodution.env').reload_secrets())
+configure(JaylogSettings(_env_file="prodution.env").reload_secrets())
 logger = get_logger()
 
 logger.info("Mensagem de log")
@@ -246,7 +279,7 @@ logger.info("Mensagem de log")
 `reload_secrets()` devolve uma **nova** instância preservando tudo que foi passado explicitamente no construtor, então dá para combinar configuração em código com secrets em disco:
 
 ```python
-settings = JaylogSettings(app_name='meu-bot', log_level='DEBUG').reload_secrets()
+settings = JaylogSettings(app_name="meu-bot", log_level="DEBUG").reload_secrets()
 configure(settings)  # app_name e log_level mantidos; endpoint/api_key vêm dos secrets
 ```
 
@@ -258,10 +291,10 @@ configure(settings)  # app_name e log_level mantidos; endpoint/api_key vêm dos
 `reconfigure()` recria a configuração com os mesmos argumentos do construtor, aplicando apenas os overrides informados. Vale tanto para campos quanto para os argumentos de configuração do pydantic-settings (`_env_file`, `_secrets_dir`, `_case_sensitive`, `_env_prefix`, ...):
 
 ```python
-base = JaylogSettings(app_name='meu-bot', log_level='DEBUG')
+base = JaylogSettings(app_name="meu-bot", log_level="DEBUG")
 
-homolog = base.reconfigure(_env_file='homolog.env')
-prod    = base.reconfigure(_env_file='producao.env', log_level='WARNING')
+homolog = base.reconfigure(_env_file="homolog.env")
+prod = base.reconfigure(_env_file="producao.env", log_level="WARNING")
 # app_name preservado nos dois; só o que foi informado muda
 ```
 

{jaylog-0.2.8 → jaylog-0.3.0a0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jaylog"
-version = "0.2.8"
+version = "0.3.0a0"
 description = "Customized Python logging library with file rotation and HTTP forwarding"
 readme = "README.md"
 authors = [
@@ -26,6 +26,24 @@ dependencies = [
 repository = "https://github.com/Gpocas/jaylog"
 "Bug Tracker" = "https://github.com/Gpocas/jaylog/issues"
 
+[dependency-groups]
+dev = [
+    "pytest>=8,<9",
+    "ruff>=0.6",
+]
+
 [build-system]
 requires = ["uv_build>=0.10.8,<0.11.0"]
 build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

jaylog-0.3.0a0/src/jaylog/__init__.py

@@ -0,0 +1,37 @@
+from jaylog._version import PROTOCOL_VERSION, __version__
+from jaylog.logger import configure, get_logger, shutdown
+from jaylog.settings import JaylogSettings
+
+__all__ = [
+    "configure",
+    "get_logger",
+    "shutdown",
+    "JaylogSettings",
+    "__version__",
+    "PROTOCOL_VERSION",
+]
+
+_DEPRECATED = {"LogEntry"}
+
+
+def __getattr__(name: str):
+    # `jaylog.models.LogEntry` era código morto — nunca foi construído, e o tipo
+    # declarado nem batia com o que o handler HTTP envia. Fica acessível por um
+    # release para não quebrar `from jaylog import LogEntry` em código de bot.
+    if name in _DEPRECATED:
+        import warnings
+
+        warnings.warn(
+            f"jaylog.{name} está depreciado e será removido na 0.4.0; "
+            "o modelo nunca foi usado pela biblioteca.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from jaylog import _compat
+
+        return getattr(_compat, name)
+    raise AttributeError(f"module 'jaylog' has no attribute '{name}'")
+
+
+def __dir__() -> list[str]:
+    return sorted([*__all__, *_DEPRECATED])

jaylog-0.3.0a0/src/jaylog/_compat.py

@@ -0,0 +1,29 @@
+"""
+Shim de depreciação de ``jaylog.models``.
+
+``LogEntry`` era código morto: nunca foi construído em lugar nenhum, e o tipo
+declarado (``log_img: Optional[str]``) nem batia com os ``bytes`` que o handler
+HTTP envia. Fica acessível por mais um release via ``jaylog.LogEntry``, que
+emite ``DeprecationWarning``. Remover na 0.4.0.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class LogEntry(BaseModel):
+    log_timestamp: datetime
+    log_level: str
+    is_exception: bool
+    log_message: str
+    service: str
+    username: str
+    hostname: str
+    ipv4: str
+    service_path: str
+    line_number: int
+    log_img: str | None = None
+
+
+__all__ = ["LogEntry"]

jaylog-0.3.0a0/src/jaylog/_version.py

@@ -0,0 +1,19 @@
+"""
+Versão do pacote e versão do protocolo de ingestão.
+
+Lookup único de ``importlib.metadata``: o valor era recalculado em
+``handlers/http_handler.py`` e voltaria a ser recalculado no reporter de host.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+#: Versão do contrato cliente <-> backend. Vai no header ``x-jaylog-protocol``
+#: e no payload de host. Mede o rollout; não dirige lógica no backend.
+PROTOCOL_VERSION = 2
+
+try:
+    __version__ = version("jaylog")
+except PackageNotFoundError:  # rodando do fonte, sem instalação
+    __version__ = "unknown"
+
+__all__ = ["__version__", "PROTOCOL_VERSION"]

jaylog-0.3.0a0/src/jaylog/context.py

@@ -0,0 +1,93 @@
+"""
+Enriquecimento do ``LogRecord``, memoizado **no próprio record**.
+
+O problema que isto resolve: ``build_log_entry_dict()`` é chamado uma vez por
+handler downstream (arquivo, console, HTTP) e mais uma vez dentro do
+``PlainTextFormatter``. Com screenshot ligado, o mesmo erro capturava a tela até
+três vezes — três ``ImageGrab.grab()`` sequenciais, cada um na casa das centenas
+de milissegundos, para produzir três imagens quase idênticas das quais duas eram
+descartadas. Memoizar no record resolve porque o record é exatamente o escopo do
+"uma vez por evento de log".
+
+O screenshot saiu do caminho compartilhado: ``record_screenshot()`` é chamado só
+pelo ``JaylogHttpHandler``, que é o único com para onde mandá-lo.
+
+.. warning::
+   Este enriquecimento tem que continuar **downstream da fila**.
+   ``QueueHandler.prepare()`` já faz ``record.msg = self.format(record)`` e zera
+   ``exc_info``; por isso, aqui embaixo, ``record.exc_info`` é sempre ``None`` e
+   o traceback sobrevive apenas por já estar embutido em ``getMessage()``. Mover
+   o enriquecimento para antes da fila (um ``Filter`` no ``QueueHandler``, por
+   exemplo) duplicaria o traceback — e ainda rodaria na thread do chamador.
+   Há um teste de regressão travando isso.
+"""
+
+import logging
+import traceback
+from datetime import datetime, timezone
+
+from jaylog.host import identity
+from jaylog.screenshot import capture_screenshot
+
+_ENTRY_ATTR = "_jaylog_entry"
+_SCREENSHOT_ATTR = "_jaylog_screenshot"
+
+
+def build_log_entry_dict(record: logging.LogRecord) -> dict:
+    """
+    Campos do log, sem ``log_img``.
+
+    ``hostname``/``username``/``ipv4`` continuam no corpo de todo log — a
+    tabela ``logs`` os mantém desnormalizados de forma permanente, então não há
+    o que migrar.
+    """
+    is_exception = getattr(record, "is_exception", False)
+
+    log_message = record.getMessage()
+    if is_exception and record.exc_info:
+        tb = "".join(traceback.format_exception(*record.exc_info)).strip()
+        log_message = f"{log_message}\n{tb}"
+
+    return {
+        "log_timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+        "log_level": "EXCEPTION" if is_exception else record.levelname,
+        "is_exception": is_exception,
+        "log_message": log_message,
+        "service": record.name,
+        "username": identity.username(),
+        "hostname": identity.hostname(),
+        "ipv4": identity.ipv4(),
+        "service_path": record.pathname,
+        "line_number": record.lineno,
+    }
+
+
+def record_entry(record: logging.LogRecord) -> dict:
+    """``build_log_entry_dict`` com o resultado guardado no record."""
+    entry = getattr(record, _ENTRY_ATTR, None)
+    if entry is None:
+        entry = build_log_entry_dict(record)
+        setattr(record, _ENTRY_ATTR, entry)
+    return entry
+
+
+def wants_screenshot(record: logging.LogRecord) -> bool:
+    return record.levelno >= logging.ERROR or bool(getattr(record, "is_exception", False))
+
+
+def record_screenshot(record: logging.LogRecord) -> bytes | None:
+    """
+    Screenshot do evento, capturado no máximo uma vez por record.
+
+    O sentinela guardado no record distingue "ainda não tentamos" de "tentamos e
+    não veio nada" — sem ele, um ``None`` legítimo faria a próxima chamada
+    capturar de novo.
+    """
+    if _SCREENSHOT_ATTR in record.__dict__:
+        return record.__dict__[_SCREENSHOT_ATTR]
+    image = capture_screenshot() if wants_screenshot(record) else None
+    record.__dict__[_SCREENSHOT_ATTR] = image
+    return image
+
+
+__all__ = ["build_log_entry_dict", "record_entry", "record_screenshot", "wants_screenshot"]

jaylog-0.3.0a0/src/jaylog/endpoints.py

@@ -0,0 +1,26 @@
+"""
+Derivação da URL do endpoint de host a partir da URL do endpoint de log.
+
+Deploys existentes já configuram ``JAYLOG_LOG_HTTP_ENDPOINT``; trocar o último
+segmento do path (``/logs/add`` -> ``/logs/host``) evita exigir uma variável
+nova de todo mundo. Quem precisar de outro caminho usa
+``JAYLOG_HOST_HTTP_ENDPOINT``.
+"""
+
+from urllib.parse import urlsplit, urlunsplit
+
+
+def derive_host_endpoint(log_endpoint: str) -> str:
+    """
+    ``https://api/logs/add`` -> ``https://api/logs/host``.
+
+    Query string e fragmento são preservados; barra final é ignorada. Uma URL
+    sem path (``https://api``) vira ``https://api/host``.
+    """
+    parts = urlsplit(log_endpoint)
+    head, sep, _last = parts.path.rstrip("/").rpartition("/")
+    path = f"{head}/host" if sep else "/host"
+    return urlunsplit((parts.scheme, parts.netloc, path, parts.query, parts.fragment))
+
+
+__all__ = ["derive_host_endpoint"]

jaylog-0.3.0a0/src/jaylog/formatters.py

@@ -0,0 +1,33 @@
+"""
+Formatação legível para arquivo.
+
+O módulo encolheu: identidade da máquina foi para ``host/identity.py`` (lazy),
+screenshot para ``screenshot.py`` e a montagem do dicionário de log para
+``context.py``. ``build_log_entry_dict`` continua reexportado aqui por compat —
+remover na 0.4.0.
+"""
+
+import logging
+from datetime import datetime
+
+from jaylog.context import build_log_entry_dict, record_entry
+from jaylog.screenshot import configure_screenshot
+
+__all__ = ["PlainTextFormatter", "build_log_entry_dict", "configure_screenshot"]
+
+
+class PlainTextFormatter(logging.Formatter):
+    """Human-readable single-line formatter for .log files."""
+
+    def __init__(self, show_service: bool = True) -> None:
+        super().__init__()
+        self.show_service = show_service
+
+    def format(self, record: logging.LogRecord) -> str:
+        entry = record_entry(record)
+        log_timestamp = (
+            datetime.fromisoformat(entry["log_timestamp"]).astimezone().strftime("%d/%m/%Y %X")
+        )
+        log_level = f"[{entry['log_level']}]"
+        service_segment = f"[{entry['service']}] | " if self.show_service else ""
+        return f"{log_timestamp} {log_level.ljust(11)} | {service_segment}{entry['log_message']}"

{jaylog-0.2.8 → jaylog-0.3.0a0}/src/jaylog/handlers/console_handler.py

@@ -4,7 +4,7 @@ from datetime import datetime
 from typing import IO
 
 from jaylog.colors import BLUE, GREEN, PURPLE, RED, RESET, YELLOW, supports_color
-from jaylog.formatters import build_log_entry_dict
+from jaylog.context import record_entry
 
 _LEVEL_COLORS = {
     "DEBUG": PURPLE,
@@ -37,12 +37,14 @@ class ConsoleFormatter(logging.Formatter):
         return f"{color}{text}{RESET}"
 
     def format(self, record: logging.LogRecord) -> str:
-        entry = build_log_entry_dict(record)
-        log_timestamp = datetime.fromisoformat(entry["log_timestamp"]).astimezone().strftime("%d/%m/%Y %X")
-        log_level = f'[{entry["log_level"]}]'
+        entry = record_entry(record)
+        log_timestamp = (
+            datetime.fromisoformat(entry["log_timestamp"]).astimezone().strftime("%d/%m/%Y %X")
+        )
+        log_level = f"[{entry['log_level']}]"
         colored_timestamp = self._paint(log_timestamp, GREEN)
-        colored_level = self._paint(log_level.ljust(11), _level_color(entry['log_level']))
-        service_segment = f'[{entry["service"]}] | ' if self.show_service else ''
+        colored_level = self._paint(log_level.ljust(11), _level_color(entry["log_level"]))
+        service_segment = f"[{entry['service']}] | " if self.show_service else ""
         return f"{colored_timestamp} {colored_level} | {service_segment}{entry['log_message']}"
 
 

jaylog-0.3.0a0/src/jaylog/handlers/http_handler.py

@@ -0,0 +1,102 @@
+import json
+import logging
+import os
+import warnings
+
+import requests
+import urllib3
+
+from jaylog._version import PROTOCOL_VERSION, __version__
+from jaylog.context import record_entry, record_screenshot
+from jaylog.host import reporter
+from jaylog.runtime import RUN_ID
+
+#: O backend sinaliza por header que não conhece este `run_id` — normalmente
+#: porque o log correu na frente do POST de host. Ver `reporter.request_resend`.
+HOST_REQUIRED_HEADER = "x-jaylog-host-required"
+
+
+def _to_multipart(fields: dict) -> dict:
+    result = {}
+    for key, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, bytes):
+            result[key] = ("screenshot.jpg", value, "image/jpeg")
+        elif isinstance(value, bool):
+            result[key] = (None, "true" if value else "false")
+        elif not isinstance(value, str):
+            result[key] = (None, json.dumps(value))
+        else:
+            result[key] = (None, value)
+    return result
+
+
+class JaylogHttpHandler(logging.Handler):
+    """
+    HTTP handler that POSTs log records as multipart/form-data to a remote endpoint.
+
+    Non-blocking behaviour is guaranteed by the QueueListener that drives this
+    handler — emit() runs in the listener's background thread.
+
+    O **corpo** do POST é byte-a-byte o mesmo da 0.2.x: ``logs`` mantém
+    ``hostname``/``username``/``ipv4`` desnormalizados de forma permanente, então
+    não há campo a remover. O que muda são dois headers novos
+    (``x-jaylog-protocol`` e ``x-jaylog-run-id``); um backend antigo simplesmente
+    os ignora.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str,
+        timeout: float = 5.0,
+        proxy: str | None = None,
+        verify: bool | str = False,
+    ) -> None:
+        super().__init__()
+        self.endpoint = endpoint
+        self.timeout = timeout
+        self.verify = verify
+        self.proxy = {"http": proxy, "https": proxy} if proxy else None
+        self._session = requests.Session()
+        self._session.headers["x-api-key"] = api_key
+        self._session.headers["x-jaylog-version"] = __version__
+        self._session.headers["x-jaylog-protocol"] = str(PROTOCOL_VERSION)
+        self._session.headers["x-jaylog-run-id"] = RUN_ID
+
+    def mapLogRecord(self, record: logging.LogRecord) -> dict:
+        # Único ponto do programa que pede screenshot: é o único com para onde
+        # mandá-la. Console e arquivo não capturam mais nada.
+        entry = dict(record_entry(record))
+        entry["log_img"] = record_screenshot(record)
+        return entry
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            if self.proxy:
+                self._session.proxies.update(self.proxy)
+
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", urllib3.exceptions.InsecureRequestWarning)
+                response = self._session.post(
+                    self.endpoint,
+                    files=_to_multipart(self.mapLogRecord(record)),
+                    timeout=self.timeout,
+                    verify=self.verify,
+                )
+                if os.getenv("JAYLOG_HTTP_DEBUG") == "1":
+                    print(response.status_code)
+                    print(response.content)
+
+            if response.headers.get(HOST_REQUIRED_HEADER) == "1":
+                # O log foi aceito (202) — não há nada a reenviar aqui. O que
+                # falta é o registro de ambiente, que o reporter reenvia (com
+                # debounce, porque o header vem em toda linha afetada).
+                reporter.request_resend(record.name)
+        except Exception:
+            # `handleError` respeita `logging.raiseExceptions`: barulho em dev,
+            # silêncio em produção. O `except: pass` anterior era um buraco
+            # negro — era por causa dele que ninguém descobria que o caminho
+            # HTTP estava falhando.
+            self.handleError(record)

jaylog-0.3.0a0/src/jaylog/host/__init__.py

@@ -0,0 +1,6 @@
+# Intencionalmente vazio.
+#
+# `settings.py` precisa de `host.identity` sem arrastar `requests` (via
+# `reporter`) nem `subprocess` (via `detect_git`). Re-exportar os submódulos
+# aqui recriaria esse acoplamento no import. Importe sempre o submódulo
+# explícito: `from jaylog.host import identity`.