hobots 1.3.5 → 1.3.6

package/docs/concepts.md

@@ -0,0 +1,440 @@
+# Conceitos
+
+Esta página explica **o que cada coisa é** — o vocabulário que as outras páginas usam sem parar: evento, scope, tag, context, extra, breadcrumb, transaction, span, check-in, heartbeat, run, claim, flush, close. As outras páginas mostram **como usar**; aqui está o **por que existe** e **quando você escolhe um em vez do outro**.
+
+Não é preciso ler de ponta a ponta. Se você só quer o mapa, o quadro abaixo resolve; se um termo apareceu numa página e você travou, pule direto para a seção dele.
+
+Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos) e nas [tabelas de opções](./api-reference.md#tabelas-de-opções), em um lugar só.
+
+## Mapa rápido
+
+| Conceito | Em uma frase | Quando você usa |
+| --- | --- | --- |
+| [Evento](#evento) | Uma foto de algo que aconteceu — um erro ou uma mensagem | `captureException` / `captureMessage` |
+| [Level](#level-severity) | A gravidade do evento | Para separar o que acorda alguém do que é só registro |
+| [Fingerprint](#fingerprint) | A chave de agrupamento dos eventos em issues | Quando o agrupamento automático erra |
+| [Scope](#scope) | A mochila de contexto que viaja com todo evento | Você raramente mexe direto; mexe pelos `set*` |
+| [withScope](#withscope) | Um scope temporário e isolado | Contexto que **não** deve vazar para o resto do programa |
+| [Tag](#tag) | Rótulo curto e indexável (`string` → `string`) | Você vai **filtrar** ou **agrupar** por isso |
+| [Context](#context) | Grupo nomeado de dados estruturados | Você vai **ler** isso ao abrir o evento |
+| [Extra](#extra) | Depósito livre, sem estrutura | Não é filtro nem grupo coerente — é anexo |
+| [Breadcrumb](#breadcrumb) | Migalha da trilha que levou até o erro | Marcar cada passo relevante do robô |
+| [Transaction](#transaction) | Unidade de trabalho nomeada, com duração | Medir quanto uma rotina inteira demorou |
+| [Span](#span) | Uma etapa medida dentro da transaction | Descobrir **onde** o tempo foi gasto |
+| [ctx.tx](#transaction-de-run-ctxtx) | A transaction que o SDK já abriu para a run | Medir as etapas de um handler do Manager |
+| [Amostragem](#amostragem-samplerate-e-tracessamplerate) | Enviar só uma fração do que acontece | Volume alto demais para enviar tudo |
+| [Check-in](#check-in) | Par de avisos "comecei" / "terminei" de um job agendado | Cron que precisa ser vigiado |
+| [Heartbeat](#heartbeat) | Batimento "estou vivo" | Saber que o robô está de pé, mesmo parado |
+| [instanceId](#instanceid) | A identidade da instância do robô | Sempre — é obrigatório no `init()` |
+| [Release e environment](#release-e-environment) | Qual versão, em qual ambiente | Separar produção de homologação; achar a versão que quebrou |
+| [Run](#run) | Uma execução solicitada no app | O Manager inteiro gira em volta disso |
+| [Claim](#claim) | O ato de um agente pegar uma run para si | Entender por que dois agentes nunca colidem |
+| [Drain mode](#drain-mode) | O agente acelera o poll enquanto tem trabalho | Entender o ritmo do polling |
+| [Fila, flush e close](#fila-flush-e-close) | Nada é enviado na hora — vai para uma fila | Encerrar o processo sem perder telemetria |
+| [beforeSend](#beforesend) | O último gancho antes do envio | Censurar ou descartar eventos |
+
+> **Nota de manutenção:** esta página é a fonte canônica das explicações de conceito. As outras páginas da doc, o `README.md` do pacote e os tooltips do app parafraseiam daqui — quando um conceito muda, muda aqui primeiro.
+
+---
+
+## Evento
+
+Um **evento** é a foto de um instante que vale a pena registrar: uma exceção que estourou ou uma mensagem que você mandou. É a unidade básica do Monitor.
+
+Quando você chama `captureException` ou `captureMessage`, o SDK monta o evento com o que a exceção traz (tipo, mensagem, stack trace com os frames em ordem) e **anexa tudo que está no [scope](#scope)** naquele momento: tags, usuário, contexts, extras e a trilha de [breadcrumbs](#breadcrumb). Depois disso o evento vai para a [fila](#fila-flush-e-close) e é enviado em lote.
+
+No servidor, eventos parecidos são agrupados numa **issue** — é por isso que 4.000 falhas do mesmo timeout não viram 4.000 linhas na sua tela. Quem decide o que é "parecido" é o [fingerprint](#fingerprint).
+
+```js
+Hobots.captureException(error);
+Hobots.captureMessage('Lote processado com sucesso', 'info');
+```
+
+As duas devolvem o `event_id` (um uuid), útil para você logar junto e depois achar o evento no app.
+
+> **Atenção:** o `event_id` devolvido **não é confirmação de envio**. Se o evento foi descartado por [amostragem](#amostragem-samplerate-e-tracessamplerate) ou por [`beforeSend`](#beforesend), você recebe um id normalmente e nada foi enfileirado. Elas devolvem `undefined` só quando o `init()` nunca foi chamado.
+
+## Level (Severity)
+
+O **level** é a gravidade do evento. São seis: `fatal`, `error`, `warning`, `info`, `debug` e `success`.
+
+Serve para você separar o que precisa acordar alguém do que é só registro histórico. `error` e `fatal` são problemas; `warning` é algo que ainda funciona mas merece olhar; `info` e `debug` são narração.
+
+O `success` é o mais incomum e o mais útil no dia a dia de RPA: ele marca uma conclusão **bem-sucedida**. Conta como evento e aparece na timeline do robô, mas **não gera issue nem alerta** — é o jeito de registrar "as 120 notas do dia foram emitidas" sem que isso pareça um problema.
+
+A precedência é: o `level` do `hint` que você passou → o level que a função de captura já definiu → `error`. Na prática:
+
+- `captureException(error)` sem `hint` é sempre `error`.
+- `captureMessage(msg)` sem level explícito é sempre `info`.
+- Para qualquer outra coisa, passe o level: `captureException(error, { level: 'warning' })`.
+
+> **Atenção:** `scope.setLevel()` (dentro de um [`withScope`](#withscope)) **não afeta** `captureException` nem `captureMessage` — as duas já definem o level do evento antes de o scope ser consultado. Para mudar o level, use o `hint` (`{ level: … }`) ou o segundo argumento do `captureMessage`.
+
+## Fingerprint
+
+O **fingerprint** é a chave de agrupamento: eventos com o mesmo fingerprint caem na **mesma issue**.
+
+Quando você não passa nada, o **servidor** calcula o agrupamento pelo stack trace. Isso funciona bem na maioria dos casos e falha em dois cenários opostos:
+
+- **Uma causa, muitos stacks.** O portal da SEFAZ dá timeout em cinco pontos diferentes do seu código. São cinco issues para o mesmo problema. Passe `fingerprint: ['sefaz-timeout']` e vire uma.
+- **Um stack, muitas causas.** Todo erro passa pelo seu `executarPasso()` genérico, então tudo agrupa junto e você não distingue nada. Inclua algo que diferencie: `fingerprint: ['passo-falhou', nomeDoPasso]`.
+
+```js
+Hobots.captureException(error, { fingerprint: ['sefaz-timeout'] });
+```
+
+O fingerprint é um array de strings — o servidor concatena os pedaços. Precedência: o do `hint` → o do evento → o do [scope](#scope).
+
+> **Atenção:** fingerprint é agrupamento, não filtro. Se o que você quer é **procurar depois** por cliente ou região, isso é [tag](#tag). Fingerprint com valor de alta cardinalidade (um id de nota, um timestamp) cria uma issue nova a cada evento e destrói o agrupamento.
+
+## Scope
+
+O **scope** é a mochila de contexto do SDK: tudo que ele sabe sobre o estado atual do seu programa e que deve viajar junto do próximo evento. Dentro dela: [tags](#tag), [usuário](#scope), [contexts](#context), [extras](#extra), level, [fingerprint](#fingerprint) e a lista de [breadcrumbs](#breadcrumb).
+
+Você não manipula o scope direto — você usa os `set*`, que escrevem nele:
+
+```js
+Hobots.setTag('regiao', 'nordeste');
+Hobots.setUser({ id: 'op-42', email: 'op@acme.com' });
+Hobots.setContext('vm', { cpu: 4, ram: '8GB' });
+Hobots.setExtra('ultimoLote', 128);
+```
+
+A partir daí, **todo** evento capturado leva esses dados. É a diferença entre repetir os mesmos campos em vinte chamadas de `captureException` e dizer uma vez, no começo do programa.
+
+Dois pontos importantes:
+
+- **Existe um scope global, e só um.** Tudo que você escreve nele fica até você sobrescrever. Para contexto temporário, use [`withScope`](#withscope).
+- **`init()` não limpa o scope.** Chamar `Hobots.init()` de novo troca o cliente, mas as tags, o usuário e os breadcrumbs que você já tinha escrito continuam lá.
+
+## withScope
+
+`withScope` executa um callback com uma **cópia isolada** do scope. O que você escrever lá dentro vale para os eventos capturados dentro do callback e **não vaza** para fora.
+
+```js
+Hobots.withScope((scope) => {
+  scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
+  Hobots.captureMessage('Reprocessando lote 128');
+});
+// aqui a tag 'lote' e o fingerprint não existem mais
+```
+
+Todos os métodos do scope são encadeáveis. Use quando o contexto é de um trecho, não do programa: um lote específico, um cliente específico, um retry.
+
+> **Atenção:** `withScope` é **síncrono** — ele troca o scope global, roda o callback e restaura no `finally`. Se você der `await` dentro do callback, o scope isolado continua valendo para **qualquer** código que capturar eventos enquanto aquele `await` está pendente. Em código concorrente (várias runs em paralelo, por exemplo), prefira passar as tags no `hint` de cada captura: `captureException(error, { tags: { lote: '128' } })`.
+
+## Tag
+
+Uma **tag** é um rótulo curto e **indexável**: chave e valor, os dois `string`. É o que você usa para **filtrar** e **agrupar** no app — "só os erros do cliente acme", "quantos eventos por região".
+
+```js
+Hobots.setTag('regiao', 'nordeste');
+Hobots.setTags({ squad: 'automacoes', cliente: 'acme' });
+```
+
+Porque é indexada, tag pede **cardinalidade baixa**: `cliente`, `regiao`, `ambiente`, `versao-do-portal` são boas tags. Número de nota fiscal, id de run e timestamp são péssimas — cada valor vira uma entrada nova no índice e a filtragem perde sentido. Esses vão em [extra](#extra) ou [context](#context).
+
+Tags podem vir de quatro lugares, e em caso de conflito a última vence:
+
+`init({ tags })` → [scope](#scope) → o próprio evento → o `hint` da chamada
+
+Ou seja: uma tag no `hint` sobrescreve a mesma tag do scope, que sobrescreve a do `init()`. Use o `init()` para o que é verdade em todo o processo (squad, ambiente), o scope para o que é verdade num trecho, e o `hint` para o que é verdade só naquele evento.
+
+> **Atenção:** tags do scope entram em **eventos**, não em [transactions](#transaction). Uma transaction só leva as tags do `init()` mais as que você marcar nela com `tx.setTag()`. [Check-ins](#check-in) e [heartbeats](#heartbeat) não levam tag nenhuma.
+
+## Context
+
+Um **context** é um grupo **nomeado** de dados estruturados anexado ao evento. Diferente de [tag](#tag), context não serve para filtrar — serve para **ler** quando você abre o evento e quer entender o ambiente em que ele aconteceu.
+
+```js
+Hobots.setContext('vm', { cpu: 4, ram: '8GB', disco: '40GB' });
+Hobots.setContext('portal', { nome: 'SEFAZ-CE', versao: '2.4', homologacao: false });
+```
+
+O nome do grupo (`'vm'`, `'portal'`) é o que organiza a visualização: cada context aparece como um bloco separado no evento, em vez de virar uma sopa de campos soltos. É a escolha certa quando os dados **andam juntos** e fazem sentido como conjunto.
+
+O SDK já injeta dois contexts sozinho em todo evento: `runtime` (nome e versão do Node, ou `browser`) e `os` (plataforma e arquitetura). Você pode sobrescrevê-los usando os mesmos nomes, mas normalmente não quer.
+
+Para **remover** um grupo, passe `null`:
+
+```js
+Hobots.setContext('portal', null); // apaga o grupo inteiro
+```
+
+## Extra
+
+**Extra** é o depósito livre: chave → qualquer valor, sem grupo e sem tipo. Vai junto do evento e você lê no app.
+
+```js
+Hobots.setExtra('ultimoLote', 128);
+Hobots.setExtra('tentativas', [1, 2, 3]);
+```
+
+É deliberadamente o menos estruturado dos três, e por isso o critério de escolha é simples:
+
+| Você vai… | Use |
+| --- | --- |
+| filtrar, agrupar, contar por isso | [tag](#tag) |
+| ler isso como um conjunto coerente | [context](#context) |
+| nenhum dos dois — é só um dado a mais | **extra** |
+
+Extra não é indexado: não dá para filtrar por ele nem construir gráfico com ele. Se você se pegar querendo isso, o campo era uma tag.
+
+> **Dados sensíveis:** extras, contexts, tags e breadcrumbs **vão todos para o servidor** e ficam visíveis no evento. Não coloque senha, token, CPF, CNPJ de cliente final ou conteúdo de documento em nenhum deles.
+
+## Breadcrumb
+
+Um **breadcrumb** ("migalha de pão") é uma anotação curta de algo que o robô fez — baixou um arquivo, clicou num botão, chamou uma API. Sozinho não vale nada: ele existe para ser lido **depois**, quando um erro acontece.
+
+O SDK mantém em memória a lista dos últimos breadcrumbs. Quando você captura um erro, a lista viaja **junto** com o evento — então em vez de ver só `TimeoutError`, você vê os oito passos que levaram até lá. É a diferença entre "quebrou" e "quebrou depois de baixar 3 notas e tentar a quarta duas vezes".
+
+```js
+Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
+```
+
+Todos os campos são opcionais: `category` agrupa a origem, `message` é o texto lido por humano, `level` colore a linha na timeline, `data` carrega um objeto livre, `type` classifica a migalha. O `timestamp` é preenchido pelo SDK.
+
+Dois pontos que costumam surpreender:
+
+- **Breadcrumbs não são consumidos.** Enviar um evento **não** limpa a lista — o próximo evento leva as mesmas migalhas de novo, mais as novas. A lista só encolhe quando estoura o `maxBreadcrumbs`, e aí as **mais antigas** são descartadas.
+- **A lista é global.** `Hobots.addBreadcrumb()` escreve no [scope](#scope) global. Para uma trilha que não vaze para o resto do programa, adicione dentro de um [`withScope`](#withscope) — ou limpe com `scope.clearBreadcrumbs()`.
+
+> **Dados sensíveis:** breadcrumbs vão para o servidor e ficam visíveis na issue. Não coloque senha, token, CPF ou conteúdo de documento em `message` nem em `data`.
+
+Tamanho do buffer: [`maxBreadcrumbs`](./api-reference.md#initoptions).
+
+## Transaction
+
+Uma **transaction** é uma unidade de trabalho **nomeada** e **medida**: ela começa, termina, e o que fica registrado é quanto tempo levou. É a resposta para "quanto demora minha rotina de emissão?" — e, quando você adiciona [spans](#span), para "onde foram esses minutos?".
+
+Enquanto o [evento](#evento) responde *o que quebrou*, a transaction responde *quanto tempo levou*. São os dois eixos do Monitor.
+
+```js
+const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
+await processarLote();
+tx.setStatus('ok'); // ou 'error'
+tx.finish();
+```
+
+O primeiro argumento é o **nome** (o que agrupa transactions comparáveis no app — use algo estável, não um id) e o segundo é o **`op`**, uma categoria livre do tipo de operação (`rpa.job`, `http.client`, `db.query`).
+
+Três coisas que valem saber:
+
+- **Nada é enviado até o `finish()`.** A transaction vive em memória; o `finish()` é que monta o payload e enfileira. Se o processo morrer antes, ela simplesmente não existe.
+- **`finish()` é idempotente e fecha o resto.** Chamar duas vezes não envia duas; e ele **finaliza automaticamente** todos os spans que ficaram abertos.
+- **A [amostragem](#amostragem-samplerate-e-tracessamplerate) é decidida no `startTransaction()`**, não no `finish()`. Se aquela transaction não foi sorteada, o `finish()` não envia nada — mas os `startChild` continuam funcionando normalmente e não custam quase nada.
+
+O `status` default é `'ok'`; encadeáveis: `setStatus`, `setName`, `setTag`.
+
+Dentro de um handler do Manager você **não** cria transaction — já existe uma em [`ctx.tx`](#transaction-de-run-ctxtx).
+
+## Span
+
+Um **span** é uma etapa medida **dentro** de uma [transaction](#transaction). A transaction diz que a rotina levou 4 minutos; os spans dizem que 3min40 foram esperando o portal.
+
+```js
+const span = tx.startChild('http.client', 'GET /api/notas');
+await api.buscarNotas();
+span.setData('notas', 42).finish();
+```
+
+`startChild(op?, description?)` existe **tanto na transaction quanto no span**, então você aninha quanto quiser — um span de "processar nota" com filhos de "baixar XML" e "gravar no banco". No app isso vira o **waterfall**: barras encaixadas, cada uma com sua duração.
+
+O `op` é a categoria (útil para agrupar "todas as queries") e a `description` é o detalhe humano ("`INSERT INTO notas`"). `setData(chave, valor)` anexa dados àquele span específico — contagens, tamanhos, ids.
+
+- Métodos encadeáveis: `setStatus`, `setData`, `finish`.
+- Esquecer o `finish()` de um span **não perde o dado**: o `finish()` da transaction fecha os spans abertos, marcando o fim naquele instante.
+- Os spans são guardados numa lista plana ligada por `parent_span_id` — o aninhamento que você vê no app é reconstruído a partir dessas referências, não da ordem das chamadas.
+
+## Transaction de run (ctx.tx)
+
+Dentro de um handler do Manager você **não precisa** criar uma transaction: o SDK já abriu uma para aquela execução e entregou em `ctx.tx`. Ela nasce quando o agente captura a run, é **correlacionada** à execução pelo `run_id`, recebe o status conforme o desfecho (`ok`, `error` ou `cancelled`) e é **finalizada automaticamente** quando o handler termina — você nunca chama `ctx.tx.finish()`.
+
+O que sobra para você é a parte interessante: marcar as **etapas** do trabalho com [spans](#span). Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app.
+
+```js
+Hobots.register('processar-nfe', async (params, ctx) => {
+  const login = ctx.tx.startChild('browser', 'login no portal');
+  await entrar();
+  login.finish();
+
+  for (const nota of params.notas) {
+    const span = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
+    ctx.throwIfCanceled();
+    await processar(nota);
+    span.setData('valor', nota.valor).finish();
+  }
+});
+```
+
+Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da run — o waterfall só fica com uma barra. Cada span que você abre é uma resposta a mais para "onde foram os 4 minutos".
+
+- **Não chame `Hobots.startTransaction()` dentro de um handler.** Você criaria uma segunda transaction, **sem** correlação com a run, e ela não apareceria na execução.
+- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale para as transactions que **você** abre com `startTransaction()`.
+- O nome é `run:<task>` e o `op` é `manager.run`, preenchidos pelo SDK.
+
+## Amostragem (sampleRate e tracesSampleRate)
+
+**Amostrar** é enviar só uma fração do que acontece. Existe porque volume alto custa banda, custa armazenamento e não melhora a conclusão: para saber que uma rotina leva ~4 minutos, 10% das execuções contam a mesma história que 100%.
+
+São dois controles independentes, os dois de `0` a `1`:
+
+| Opção | Afeta | `0.1` significa |
+| --- | --- | --- |
+| `sampleRate` | [eventos](#evento) (`captureException`, `captureMessage`) | ~10% dos erros são enviados |
+| `tracesSampleRate` | [transactions](#transaction) abertas por `startTransaction()` | ~10% das transactions são enviadas |
+
+O sorteio é por item, no momento em que ele é criado — nunca "1 a cada 10", e sim 10% de chance cada.
+
+Quem **nunca** é amostrado: [check-ins](#check-in), [heartbeats](#heartbeat) e a [transaction de run](#transaction-de-run-ctxtx) (`ctx.tx`). São sinais de vida e de agendamento — amostrar transformaria "o robô está offline" num palpite.
+
+> **Atenção:** para erros, comece com `sampleRate` em 1 (o default) e só reduza se o volume virar problema de verdade. Amostrar erro significa não ver a falha que aconteceu três vezes — e três vezes é exatamente onde você ainda consegue agir. Para transactions o cálculo é o oposto: reduzir é quase sempre seguro.
+
+Nos dois casos, o descarte é silencioso do ponto de vista do seu código: `captureException` ainda devolve um `event_id`. Veja a ressalva em [Evento](#evento).
+
+## Check-in
+
+Um **check-in** é um aviso de que um job agendado começou ou terminou. Dois check-ins com o **mesmo id** formam um par: `in_progress` na entrada, `ok` ou `error` na saída — e a diferença entre eles é a duração medida.
+
+Isso responde a uma pergunta que erro e performance não respondem: **"o cron rodou?"**. Um robô que nunca executa nunca lança exceção — o silêncio é o sintoma, e check-in é como o silêncio fica visível.
+
+O jeito recomendado é `withMonitor`, que faz o par sozinho e captura a exceção se houver:
+
+```js
+await Hobots.withMonitor('sync-notas', () => executarSync(), {
+  schedule: '0 */2 * * *',
+  timezone: 'America/Fortaleza',
+});
+```
+
+O **`schedule`** (expressão cron) é o campo que muda o jogo: com ele, o servidor **cria ou atualiza o monitor automaticamente** (upsert — você não precisa cadastrar nada no app) e passa a saber quando a próxima execução era esperada. É isso que habilita a detecção de **execução perdida**: se as 4h da manhã passaram e nenhum `in_progress` chegou, o app avisa.
+
+Detalhes que importam:
+
+- `withMonitor` **relança** a exceção depois de fechar o check-in como `error` e capturar o evento (com a tag `monitor: <slug>`) — o seu `try/catch` em volta continua funcionando igual.
+- Precisa de controle manual (o par não está no mesmo lugar do código)? Use `checkIn` direto e reaproveite o `checkInId` devolvido pelo `in_progress` para fechar a execução.
+
+## Heartbeat
+
+O **heartbeat** é um batimento periódico dizendo "estou vivo". O servidor conhece a cadência esperada e marca a instância como **offline** quando os batimentos param.
+
+É o complemento do [check-in](#check-in): check-in vigia *execuções agendadas*, heartbeat vigia *o processo*. Um robô que fica de plantão esperando trabalho não tem cron para monitorar — mas você ainda quer saber quando a VM dele caiu.
+
+```js
+Hobots.init({
+  clientSecret,
+  instanceId: 'vm-cliente-01',
+  heartbeat: { intervalMs: 60_000, name: 'Robô NFe — VM 01' },
+});
+```
+
+`heartbeat: true` usa os defaults. A identidade é sempre o [`instanceId`](#instanceid) do `init()`; o `name` é só o rótulo amigável no dashboard.
+
+Dois detalhes:
+
+- O primeiro batimento sai **na hora** em que o `init()` roda — não depois do primeiro intervalo. O robô aparece online imediatamente.
+- O batimento carrega o próprio intervalo configurado. É assim que o servidor sabe quanto silêncio é normal antes de declarar offline: quem bate a cada meio minuto é cobrado em outro ritmo de quem bate a cada cinco.
+
+O timer do heartbeat é `unref`'d — ele **não** segura o processo vivo.
+
+## instanceId
+
+O **`instanceId`** é a identidade da instância do robô: qual VM, qual container, qual máquina. É **obrigatório** no `init()` e deve ser **estável entre reinícios** (`vm-cliente-01`, `container-nfe-3`) — se você gerar um valor novo a cada boot, o app vê uma frota de robôs fantasmas em vez de um robô que reiniciou.
+
+O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo tempo: o [heartbeat](#heartbeat) do Monitor e o agente do [Manager](./manager.md) enviam o mesmo `instanceId`. O servidor correlaciona os dois, e o robô aparece como **um agente só** no painel — sem nenhuma configuração extra.
+
+## Release e environment
+
+**`release`** é a versão do seu programa (`robo-nfe@1.4.2`) e **`environment`** é o ambiente lógico (`production`, `homologacao`). Os dois são anexados a **todo** item enviado: eventos, transactions e check-ins.
+
+Servem a duas perguntas concretas:
+
+- *"quebrou desde quando?"* — com `release`, você compara o antes e o depois de um deploy e sabe qual versão introduziu o erro.
+- *"isso é real ou é teste?"* — com `environment`, o ruído da homologação não polui os alertas de produção.
+
+`environment` default é `production`. Se você roda homologação sem definir isso, os dois ambientes se misturam na mesma issue — vale configurar no primeiro dia.
+
+## Run
+
+Uma **run** (execução) é um pedido concreto de trabalho criado no app: alguém preencheu o formulário da task, ou uma automação disparou, e agora existe uma solicitação esperando um agente pegar.
+
+É a unidade em volta da qual o [Manager](./manager.md) inteiro gira. O ciclo de vida no servidor:
+
+```
+pending → claimed → running → succeeded | failed | canceled
+```
+
+- **`pending`** — criada, esperando um agente.
+- **`claimed`** — um agente reivindicou ([claim](#claim)), mas o handler ainda não confirmou o início.
+- **`running`** — o handler está executando. Daqui para frente o agente reporta logs incrementais.
+- **`succeeded` / `failed` / `canceled`** — terminal.
+
+O agente só transiciona para `running`, `succeeded` e `failed`. `pending` e `claimed` são do servidor; `canceled` vem de alguém cancelando no app.
+
+Cada run carrega os **`params`** (o JSON validado do formulário) e chega ao seu código como o primeiro argumento do handler, junto de um [`RunContext`](./api-reference.md#managertaskhandler--runcontext) com logs, sinal de cancelamento e a [transaction](#transaction-de-run-ctxtx).
+
+## Claim
+
+O **claim** é o ato de um agente reivindicar uma run para si. Importa porque resolve a pergunta óbvia de qualquer sistema de fila: **o que impede dois agentes de pegarem a mesma run?**
+
+A resposta é que o claim é **server-side e atômico**. O SDK é um cliente HTTP puro: ele faz um `POST` de poll, e é o servidor que seleciona as runs pendentes e as promove a `claimed` numa única operação de banco com `FOR UPDATE SKIP LOCKED`. Dois agentes que fazem poll no mesmo milissegundo recebem conjuntos disjuntos — não há corrida a resolver no cliente, e nenhum lock vive no seu processo.
+
+O agente pede só o que consegue rodar (`max = concurrency − runs ativas`), então ele nunca reivindica trabalho para deixar parado.
+
+Detalhes do protocolo em [Protocolo & transporte](./protocol.md#onde-vive-o-claim-atômico).
+
+## Drain mode
+
+**Drain mode** é o comportamento do polling quando há trabalho acumulado: em vez de esperar o intervalo configurado, o agente faz o próximo poll **imediatamente**, e continua assim enquanto vierem runs. Quando um poll volta vazio, ele volta a esperar `pollIntervalMs`.
+
+O efeito é que a fila esvazia rápido sem que você precise baixar o intervalo. Um agente com `pollIntervalMs` de 5 segundos não demora 50 segundos para consumir 10 runs — ele drena tudo de uma vez e só então volta a dormir.
+
+Isso também explica por que o intervalo de poll não é a latência típica: ele é só o **teto da espera quando não há nada para fazer**.
+
+## Fila, flush e close
+
+O SDK **não** envia um HTTP por evento. Cada `captureException`, transaction, check-in e heartbeat entra numa **fila em memória**; um timer junta os itens num **envelope** e faz um POST só. É isso que faz a telemetria custar quase nada no caminho crítico do seu robô — e é isso que cria o problema que `flush` e `close` resolvem: **quando o processo morre, a fila morre com ele.**
+
+A fila esvazia sozinha em três situações: passou o `flushIntervalMs`, acumulou `maxBatchSize` itens, ou você pediu.
+
+### `flush(timeoutMs?)` — "manda o que tem agora"
+
+Empurra a fila e espera os envios em andamento terminarem. O SDK **continua vivo e usável** depois. Use antes de um ponto de risco: o fim de um lote longo, um `process.exit()` que não é seu, uma etapa que costuma travar a VM.
+
+Devolve `true` se tudo saiu dentro do tempo e `false` se estourou. `false` **não** significa que os dados foram perdidos — significa que o SDK parou de esperar; os envios em voo continuam tentando (com a [ladder de retry](./api-reference.md#tempos-e-intervalos)) enquanto o processo existir.
+
+### `close(timeoutMs?)` — "acabou, encerra"
+
+Encerra tudo, **nesta ordem**: para o agente do Manager (aguardando as runs em execução) → para o heartbeat → faz o flush final e fecha o transport. É sempre a última linha do seu programa.
+
+> **Atenção:** `close()` é **terminal e sem volta**. Depois dele, todo `captureException`, transaction, check-in ou heartbeat é **descartado** com um aviso no console — não existe `reopen()`. Se o programa precisar voltar a emitir telemetria, chame `Hobots.init()` de novo.
+
+> **Atenção:** o `timeoutMs` do `close()` é aplicado **duas vezes, em sequência** — uma para esperar as runs do Manager, outra para o flush final. `close(15_000)` pode levar até ~30s no pior caso. Se você tem um SIGTERM com prazo curto (Kubernetes, systemd), dimensione por aí.
+
+O `flush` cobre a fila do **Monitor**. Os logs de uma run do Manager (`ctx.log`) são um canal separado, com o próprio ritmo — quem espera por eles é o `close()`/`stop()`, ao aguardar a run terminar.
+
+Defaults e tempos dos dois: [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
+
+## beforeSend
+
+`beforeSend` é o último gancho antes de um [evento](#evento) entrar na [fila](#fila-flush-e-close). Você recebe o evento **pronto** — já com tags, contexts, extras e breadcrumbs mesclados — e devolve ele (editado ou não) ou `null` para descartar.
+
+```js
+Hobots.init({
+  clientSecret,
+  instanceId: 'vm-cliente-01',
+  beforeSend: (event) => {
+    if (event.exception?.type === 'AbortError') return null; // não me interessa
+    delete event.extra?.senha;                                // censura
+    return event;
+  },
+});
+```
+
+Dois usos principais: **censurar** dados que não deveriam sair da máquina (a última rede de proteção contra vazar um token num extra) e **descartar** classes de erro que você já sabe que são ruído.
+
+Onde ele entra na ordem das coisas: a [amostragem](#amostragem-samplerate-e-tracessamplerate) acontece **antes** (evento sorteado fora nunca chega ao `beforeSend`), e o merge de scope e `hint` também — então o que você vê é o evento final, exatamente como seria enviado.
+
+> **Atenção:** `beforeSend` roda no caminho da captura, de forma síncrona. Mantenha a função rápida e sem I/O — e cuidado para não lançar exceção dentro dela.
+
+Vale só para eventos. Transactions, check-ins e heartbeats não passam pelo `beforeSend`.

package/docs/getting-started.md

@@ -8,6 +8,19 @@ pnpm add hobots
 
 Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). O Monitor também funciona no browser para captura de erros.
 
+## Conceitos em 2 minutos
+
+Os termos que aparecem nesta página, em uma frase cada. Explicação completa de todos em [Conceitos](./concepts.md).
+
+| Conceito | Em uma frase |
+| --- | --- |
+| [Evento](./concepts.md#evento) | A foto de um erro ou de uma mensagem que você registrou |
+| [Tag](./concepts.md#tag) | Rótulo curto e indexável, para filtrar depois (`cliente`, `regiao`) |
+| [Heartbeat](./concepts.md#heartbeat) | Batimento "estou vivo" — o servidor acusa offline quando ele para |
+| [instanceId](./concepts.md#instanceid) | A identidade da instância do robô; a mesma nos dois canais |
+| [Run](./concepts.md#run) | Uma execução solicitada no app, que um agente pega e executa |
+| [Fila, flush e close](./concepts.md#fila-flush-e-close) | Nada é enviado na hora — vai para uma fila que precisa ser esvaziada antes do processo morrer |
+
 ## O Client Secret
 
 Cada projeto tem **um único Client Secret** — a mesma credencial autentica o Monitor **e** o Manager:
@@ -75,7 +88,7 @@ Hobots.init({
 
 Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log.info(`processando lote ${params.lote}…`);
-  return { processadas: 12 };
+  ctx.log.info('12 notas processadas'); // o retorno do handler é ignorado — reporte por log
 });
 Hobots.start(); // mantém o processo vivo até stop()/close()
 ```
@@ -102,4 +115,6 @@ process.on('SIGINT', () => {
 });
 ```
 
-Para parar de aceitar execuções **sem** derrubar a telemetria, use `Hobots.stop(timeoutMs?)`.
+> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs do Manager, outra no flush final. O `close(15_000)` acima pode levar até ~30s no pior caso. Se o seu SIGTERM tem prazo curto (Kubernetes, systemd), dimensione por aí. Os defaults, quando você omite o argumento, estão em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
+
+Para parar de aceitar execuções **sem** derrubar a telemetria, use `Hobots.stop(timeoutMs?)`. Conceito das duas funções em [Fila, flush e close](./concepts.md#fila-flush-e-close).

package/docs/manager.md

@@ -2,6 +2,8 @@
 
 Capability de **execução remota sob demanda**, habilitada com `manager: true` (ou opções) no `init()` único. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais. Usa o mesmo Client Secret, o mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
 
+O vocabulário desta página ([run](./concepts.md#run), [claim](./concepts.md#claim), [drain mode](./concepts.md#drain-mode), [ctx.tx](./concepts.md#transaction-de-run-ctxtx)) está explicado em [Conceitos](./concepts.md).
+
 ## Ciclo de vida
 
 ```js
@@ -26,10 +28,10 @@ process.on('SIGINT', () => {
 });
 ```
 
-- `init({ manager })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (os handlers registrados são preservados).
+- `init({ manager })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (os handlers registrados são preservados). Se havia runs em execução, elas são interrompidas **sem espera** e reportadas como `AgentTerminated` na hora — `init()` não é um jeito gracioso de reconfigurar um agente ocupado; para isso use `stop()` antes.
 - `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app. Registre **antes** de `start()`. Pode ser chamado antes do `init()`; se o `init()` não habilitou o Manager, o SDK avisa no console.
 - `start()` — começa o polling. Lança se o `init()` não configurou `manager` ou se nenhuma task foi registrada.
-- `stop(timeoutMs?)` — para **só o Manager**: encerra o polling e aguarda as runs ativas (default 30s); a telemetria continua. Retorna `false` se estourou o timeout.
+- `stop(timeoutMs?)` — para **só o Manager**: encerra o polling e aguarda as runs ativas ([default](./api-reference.md#tempos-e-intervalos)); a telemetria continua. Retorna `false` se estourou o timeout.
 - `close(timeoutMs?)` — encerra **tudo**: agente (aguardando runs em voo) → heartbeat → flush final.
 
 O `instanceId` (obrigatório) é a identidade do agente no painel — o poll o envia como `agent.instance_id`, a **mesma identidade** do heartbeat do Monitor. Com o `init()` único, os dois canais convergem em **um agente** automaticamente.
@@ -46,6 +48,7 @@ interface RunContext {
   runId: string;
   task: string;
   log(level: 'debug' | 'info' | 'warning' | 'error', message: string): void;
+  tx: Transaction;
   signal: AbortSignal;
   throwIfCanceled(): void;
   sleep(ms: number): Promise<void>;
@@ -53,7 +56,8 @@ interface RunContext {
 ```
 
 - **`params`** — os dados do formulário configurado no app (o JSON validado).
-- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run em tempo quase real.
+- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run em tempo quase real. Cada linha também é **impressa no terminal local** como `[hobots:<task>] INFO mensagem`, colorida por nível — útil para acompanhar o robô rodando na VM. A cor é desligada automaticamente fora de um TTY e quando a env `NO_COLOR` está definida; o eco local é independente do envio ao servidor.
+- **`ctx.tx`** — a [transaction de performance](./concepts.md#transaction-de-run-ctxtx) desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild()` para medir as etapas (veja abaixo).
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**. Cancelamento é cooperativo (veja abaixo).
 - **`ctx.throwIfCanceled()`** — lança `RunCanceled` se o `signal` já disparou. O ponto de parada de 1 linha para chamar entre as etapas do trabalho.
 - **`ctx.sleep(ms)`** — sleep que respeita o `signal`: rejeita com `RunCanceled` no cancelamento em vez de esperar até o fim. Use no lugar do seu `sleep` em esperas longas.
@@ -64,9 +68,34 @@ Você pode tipar os params: `Hobots.register<{ lote: number }>(...)`.
 
 > **Dados sensíveis:** o que você escreve em `ctx.log()` e as mensagens/stack de erros lançados **são enviados ao servidor** e ficam visíveis na execução no app. Não inclua senhas, tokens, documentos, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
 
+## Performance da run (`ctx.tx`)
+
+O SDK já abre uma [transaction](./concepts.md#transaction-de-run-ctxtx) para cada run e entrega em `ctx.tx`. Ela é correlacionada à execução, recebe o status conforme o desfecho (`ok`, `error` ou `cancelled`) e é **finalizada automaticamente** quando o handler termina. Você não cria e não finaliza — só marca as etapas:
+
+```js
+Hobots.register('processar-nfe', async (params, ctx) => {
+  const login = ctx.tx.startChild('browser', 'login no portal');
+  await entrar();
+  login.finish();
+
+  for (const nota of params.notas) {
+    const span = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
+    ctx.throwIfCanceled();
+    await processar(nota);
+    span.setData('valor', nota.valor).finish();
+  }
+});
+```
+
+Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app — é como você responde "onde foram os 4 minutos". Sem nenhum span, a transaction ainda mede o tempo total da run; o waterfall só fica com uma barra.
+
+- **Não chame `Hobots.startTransaction()` dentro de um handler.** Você criaria uma segunda transaction, sem correlação com a run, e ela não apareceria na execução.
+- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale só para as transactions que você abre com `startTransaction()`.
+- Span que você esquecer aberto é fechado no `finish()` da transaction, então o dado não se perde.
+
 ## Cancelamento cooperativo
 
-Uma run cancelada no app **não mata** o seu handler — o SDK não interrompe código em execução. Ele apenas dispara `ctx.signal`. Enquanto o handler roda, o SDK mantém um **heartbeat de cancelamento** (a cada `cancelCheckIntervalMs`, default 5s, máx 15s): a run cancelada no app é detectada em segundos, mesmo que o handler nunca chame `ctx.log()`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas por `ctx.sleep()`):
+Uma run cancelada no app **não mata** o seu handler — o SDK não interrompe código em execução. Ele apenas dispara `ctx.signal`. Enquanto o handler roda, o SDK mantém um **heartbeat de cancelamento** (a cada `cancelCheckIntervalMs`, veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)): a run cancelada no app é detectada em segundos, mesmo que o handler nunca chame `ctx.log()`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas por `ctx.sleep()`):
 
 ```js
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -84,7 +113,7 @@ Quando o cancelamento veio do app, a run já está `cancelada` no servidor — o
 Se o processo do agente **morre no meio de uma run**, a solicitação vira **falha** no app com erro `AgentTerminated` ("execução encerrada inesperadamente") — sem re-execução automática. Dois caminhos garantem isso:
 
 - **Morte capturável** (SIGINT/SIGTERM sem handler próprio do programa, erro não tratado): o SDK reporta a falha na hora (~2s, um PATCH best-effort com timeout curto) e então deixa o processo morrer com a semântica default do sinal. Os handlers são instalados no `start()` e **nunca interferem** quando o programa tem handler próprio para o sinal (o shutdown gracioso via `close()` continua sendo o caminho normal). Desative com `manager: { installExitHandlers: false }`.
-- **Morte dura** (kill -9, queda de energia, rede fora): nada roda no cliente. O heartbeat de cancelamento é também o **sinal de vida da run** — o servidor marca a run como falha ao notar **~60s sem reporte**.
+- **Morte dura** (kill -9, queda de energia, rede fora): nada roda no cliente. O heartbeat de cancelamento é também o **sinal de vida da run** — o servidor marca a run como falha ao notar silêncio prolongado (o [sweep](./api-reference.md#tempos-e-intervalos) server-side).
 
 `close(timeoutMs)` que estoura o timeout com runs ainda em execução também reporta essas runs como `AgentTerminated` — o processo vai morrer em seguida e o app não deve mostrar a run como "executando" para sempre.
 
@@ -94,7 +123,7 @@ Se o agente morrer logo **após capturar** uma run (antes de reportar `running`)
 
 ## Concorrência
 
-`concurrency` (default 1, máx 5) controla quantas runs o agente executa em paralelo. Com 1, as runs são sequenciais. O agente só reivindica o que consegue rodar (`max = concurrency - runs ativas`) e entra em **drain mode**: enquanto vêm runs, re-pesquisa imediatamente; quando não vem nada, espera `pollIntervalMs`.
+`concurrency` (default 1, máx 5) controla quantas runs o agente executa em paralelo. Com 1, as runs são sequenciais. O agente só reivindica o que consegue rodar (`max = concurrency - runs ativas`) e entra em **[drain mode](./concepts.md#drain-mode)**: enquanto vêm runs, re-pesquisa imediatamente; quando não vem nada, espera `pollIntervalMs`. Ou seja, o intervalo de poll é o teto da espera **quando não há trabalho** — não a latência típica para começar uma run.
 
 ## Timeout por run
 
@@ -104,4 +133,4 @@ Todas as opções em [Referência de API → ManagerOptions](./api-reference.md#
 
 ## Como o claim funciona (resumo)
 
-O SDK é um cliente HTTP: ele faz `POST /v1/manager/poll` e o **servidor** reivindica as runs pendentes de forma atômica com `FOR UPDATE SKIP LOCKED` — dois agentes nunca pegam a mesma run. Detalhes em [Protocolo & transporte](./protocol.md).
+O SDK é um cliente HTTP: ele faz `POST /v1/manager/poll` e o **servidor** reivindica as runs pendentes de forma atômica com `FOR UPDATE SKIP LOCKED` — dois agentes nunca pegam a mesma run. Conceito em [Claim](./concepts.md#claim), detalhes em [Protocolo & transporte](./protocol.md).