hobots 1.3.5 → 1.3.6

package/docs/monitor.md

@@ -6,7 +6,7 @@ Capability de telemetria: erros, performance, crons e uptime. Sempre ativa no `i
 import * as Hobots from 'hobots';
 ```
 
-Todas as funções abaixo são no-op seguros se `Hobots.init()` não foi chamado (com aviso no console). Assinaturas completas em [Referência de API](./api-reference.md).
+Todas as funções abaixo são no-op seguros se `Hobots.init()` não foi chamado (com aviso no console). Assinaturas completas em [Referência de API](./api-reference.md); o que cada conceito **é**, em [Conceitos](./concepts.md).
 
 ## init
 
@@ -39,8 +39,12 @@ Hobots.captureMessage('Lote processado com sucesso', 'info');
 
 Ambas retornam o `event_id` (ou `undefined` se não inicializado). O segundo argumento é um [`CaptureHint`](./api-reference.md#capturehint) (`level`, `tags`, `extra`, `fingerprint`).
 
+> **Atenção:** o `event_id` retornado **não é confirmação de envio** — se o evento foi descartado por amostragem ou por `beforeSend`, você recebe um id normalmente e nada foi enfileirado.
+
 Erros **não tratados** (`uncaughtException` / `unhandledRejection`) são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`.
 
+Conceitos: [Evento](./concepts.md#evento) · [Level](./concepts.md#level-severity) · [Fingerprint](./concepts.md#fingerprint).
+
 ## Breadcrumbs
 
 Trilha do que aconteceu antes do erro; enviada junto do próximo evento.
@@ -51,6 +55,8 @@ Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level
 
 O buffer é limitado por `maxBreadcrumbs` (default 100, mais antigos descartados).
 
+Dois pontos que costumam surpreender: a lista **não é limpa** ao enviar um evento (o próximo evento leva as mesmas migalhas de novo), e ela é **global** — para uma trilha que não vaze, adicione dentro de um `withScope`. Conceito: [Breadcrumb](./concepts.md#breadcrumb).
+
 ## Escopo: tags, usuário, contexto, extras
 
 Dados anexados a **todos** os eventos seguintes:
@@ -63,6 +69,14 @@ Hobots.setContext('vm', { cpu: 4, ram: '8GB' });
 Hobots.setExtra('ultimoLote', 128);
 ```
 
+Qual usar para quê: **tag** é rótulo curto e indexável (você vai filtrar por isso), **context** é grupo nomeado de dados que andam juntos (você vai ler), **extra** é depósito livre para o resto. Detalhes e critérios em [Tag](./concepts.md#tag) · [Context](./concepts.md#context) · [Extra](./concepts.md#extra).
+
+Três comportamentos que valem saber:
+
+- Tags podem vir de quatro lugares e a última vence: `init({ tags })` → scope → evento → `hint` da chamada.
+- `setContext(nome, null)` **apaga** o grupo. O SDK já injeta os grupos `runtime` e `os` em todo evento.
+- `setExtra` não é indexado — se você quiser filtrar por aquele campo, ele deveria ser uma tag.
+
 Para um escopo **isolado** (sem vazar para o global), use `withScope`:
 
 ```js
@@ -72,8 +86,12 @@ Hobots.withScope((scope) => {
 });
 ```
 
+> **Atenção:** `withScope` é **síncrono** — ele troca o scope global e restaura no fim do callback. Se você der `await` lá dentro, o scope isolado vale para qualquer código que capturar eventos enquanto aquele `await` está pendente. Em código concorrente (várias runs em paralelo), passe as tags no `hint`: `captureException(error, { tags: { lote: '128' } })`. Conceito: [withScope](./concepts.md#withscope).
+
 ## Performance: transactions e spans
 
+Uma **transaction** é uma unidade de trabalho nomeada e medida ("quanto minha rotina demorou"); os **spans** são as etapas dentro dela ("onde o tempo foi gasto"). Conceitos: [Transaction](./concepts.md#transaction) · [Span](./concepts.md#span).
+
 ```js
 const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
 
@@ -91,7 +109,11 @@ tx.finish(); // só aqui a transaction é enviada (respeitando tracesSampleRate)
 
 - `startChild(op?, description?)` existe tanto em `Transaction` quanto em `Span` (aninhamento arbitrário).
 - Métodos encadeáveis: `setStatus`, `setData` (span), `setTag`/`setName` (transaction).
-- `finish()` na transaction fecha spans abertos e envia o payload; nada é enviado se ela não foi amostrada.
+- `finish()` na transaction fecha spans abertos e envia o payload; nada é enviado se ela não foi amostrada. É **idempotente** — chamar duas vezes não envia duas.
+- A decisão de amostragem acontece no **`startTransaction()`**, não no `finish()`. Esquecer o `finish()` de um span não perde o dado: ele é fechado no instante em que a transaction fecha.
+- Uma transaction leva as tags do `init()` e as que você marcar com `tx.setTag()` — ela **não** herda as tags do scope.
+
+Dentro de um handler do Manager não abra transaction: já existe uma em [`ctx.tx`](./concepts.md#transaction-de-run-ctxtx).
 
 ## Crons (check-ins)
 
@@ -113,6 +135,8 @@ const id = Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
 Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
 ```
 
+`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. Conceito: [Check-in](./concepts.md#check-in).
+
 ## Heartbeat (uptime)
 
 Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os batimentos param.
@@ -124,15 +148,25 @@ Hobots.init({
 });
 ```
 
-`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`. Campos em [HeartbeatOptions](./api-reference.md#heartbeatoptions).
+`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`. Campos em [HeartbeatOptions](./api-reference.md#heartbeatoptions); conceito em [Heartbeat](./concepts.md#heartbeat).
+
+O primeiro batimento sai **na hora** em que o `init()` roda — não depois do primeiro intervalo. O batimento também carrega o intervalo configurado: é assim que o servidor sabe quanto silêncio é normal antes de declarar o robô offline.
 
 Essa identidade é a mesma que o Manager envia no poll (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** em Monitor → Agentes automaticamente.
 
 ## Flush e close
 
+Nada é enviado na hora: cada evento, transaction, check-in e heartbeat entra numa **fila em memória** e sai em lote. É por isso que essas duas funções existem — quando o processo morre, a fila morre com ele. Conceito: [Fila, flush e close](./concepts.md#fila-flush-e-close).
+
 ```js
 await Hobots.flush(2000); // envia o que está em buffer, mantém o SDK vivo
 await Hobots.close(2000); // para o Manager (se ativo) + heartbeat + flush final do transport
 ```
 
+O `timeoutMs` é opcional nas duas — o default é 5s (veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)). As duas devolvem `false` quando estouram o prazo, o que significa que o SDK parou de esperar, **não** que os dados foram perdidos: os envios em voo continuam tentando enquanto o processo existir.
+
 Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d, então a telemetria **não** segura o processo vivo sozinha (só o `start()` do Manager segura).
+
+> **Atenção:** `close()` é **terminal**. Depois dele, todo evento, transaction, check-in ou heartbeat novo é **descartado** com 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()` é gasto **duas vezes, em sequência** — uma esperando as runs do Manager, outra no flush final. `close(15_000)` pode levar até ~30s no pior caso. Dimensione por aí se o seu SIGTERM tem prazo curto.

package/docs/protocol.md

@@ -40,7 +40,9 @@ Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Beare
 
 Tipos de item: `event`, `transaction`, `check_in`, `heartbeat` (definidos em `hobots/protocol`).
 
-**Flush & retries:** o transport flusha por `flushIntervalMs` (default 2s) ou ao atingir `maxBatchSize` (default 10). Ladder de retry `[1s, 4s, 16s]`; respostas 4xx (exceto 429) são descartadas sem retry; a fila tem teto de 200 itens (descarta os mais antigos).
+Um `transaction` pode carregar `run_id`: é assim que a [transaction de uma run do Manager](./concepts.md#transaction-de-run-ctxtx) (`ctx.tx`) é correlacionada à execução, e o que permite o app montar o waterfall de performance dentro da solicitação. Transactions abertas com `startTransaction()` não têm esse campo.
+
+**Flush & retries:** o transport flusha por `flushIntervalMs` ou ao atingir `maxBatchSize`. Ladder de retry de 3 tentativas; respostas 4xx (exceto 429) são descartadas sem retry; a fila tem teto fixo e descarta os itens **mais antigos** ao encher. Todos os valores em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
 
 ## Manager — polling e reporte
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "description": "SDK JavaScript da Hobots — captura de erros, transactions, check-ins de cron e heartbeats (Monitor) e execução remota de tarefas sob demanda (Manager) para RPAs e integrações. Um único import e um único init().",
   "type": "module",
   "sideEffects": false,