hobots 2.4.0 → 3.2.0

package/docs/telemetry.md

@@ -1,162 +0,0 @@
-# Telemetria
-
-Capability de telemetria: erros (módulo **Issues**), performance e uptime (módulo **Agentes**). Sempre ativa no `init()` único:
-
-```js
-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); o que cada conceito **é**, em [Conceitos](./concepts.md).
-
-## init
-
-```js
-Hobots.init({
-  clientSecret: 'hb_<64 hex>',
-  environment: 'production',
-  release: 'robo-nfe@1.4.2',
-  instanceId: 'vm-cliente-01',
-  tags: { squad: 'automacoes' },
-  heartbeat: true,
-});
-```
-
-Cria o cliente, instala handlers globais de erro (a menos que `captureUnhandled: false`) e inicia o heartbeat se configurado. Chamar de novo substitui o cliente. Todos os campos em [Referência de API → InitOptions](./api-reference.md#initoptions).
-
-## Captura de erros e mensagens
-
-```js
-// exceções
-Hobots.captureException(error, {
-  tags: { cliente: 'acme' },
-  type: 'error',
-  fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
-});
-
-// mensagens sem exceção
-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) (`type`, `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) · [Type](./concepts.md#type-tipo-do-evento) · [Fingerprint](./concepts.md#fingerprint).
-
-## Breadcrumbs
-
-Trilha do que aconteceu antes do erro; enviada junto do próximo evento.
-
-```js
-Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
-```
-
-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:
-
-```js
-Hobots.setTag('regiao', 'nordeste');
-Hobots.setTags({ squad: 'automacoes', cliente: 'acme' });
-Hobots.setUser({ id: 'op-42', email: 'op@acme.com' });
-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
-Hobots.withScope((scope) => {
-  scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
-  Hobots.captureMessage('Reprocessando lote 128');
-});
-```
-
-> **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 etapas
-
-Uma **transaction** é uma unidade de trabalho nomeada e medida ("quanto minha rotina demorou"); as **etapas** são as unidades dentro dela ("onde o tempo foi gasto"). Conceitos: [Transaction](./concepts.md#transaction) · [Step](./concepts.md#step).
-
-```js
-const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
-
-const step = tx.startChild('http.client', 'GET /api/notas');
-await api.buscarNotas();
-step.setData('notas', 42).finish();
-
-const filho = step.startChild('db.query', 'INSERT INTO notas'); // etapas aninham
-await gravar();
-filho.finish();
-
-tx.setStatus('ok'); // ou 'error'
-tx.finish(); // só aqui a transaction é enviada (respeitando tracesSampleRate)
-```
-
-- `startChild(op?, description?)` existe tanto em `Transaction` quanto em `Step` (aninhamento arbitrário).
-- Métodos encadeáveis: `setStatus`, `setData` (step), `setTag`/`setName` (transaction).
-- Status de step: `'ok'` (default), `'warning'` (atenção, não é falha) ou `'error'` — cores distintas no waterfall.
-- `finish()` na transaction fecha etapas abertas 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 uma step não perde o dado: ela é fechada 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 de task, `startTransaction()` **retorna a transaction da própria run** ([`ctx.tx`](./concepts.md#transaction-de-run-ctxtx)) em vez de criar uma segunda — cada execução tem exatamente **uma** transaction. Fora de um handler, ela cria uma transaction nova, sem correlação com run nenhuma.
-
-## Heartbeat (uptime)
-
-Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os batimentos param.
-
-```js
-Hobots.init({
-  clientSecret,
-  heartbeat: { intervalMs: 30_000, name: 'Robô NFe — VM 01' },
-});
-```
-
-`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 poll de tasks envia (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** no módulo Agentes automaticamente. Por isso, com `tasks: true` o heartbeat é **opcional** (o poll já marca a presença do agente); ele é essencial para agentes só de telemetria.
-
-## Recursos da máquina (CPU, memória, disco)
-
-Ligado por padrão em Node (`machineMetrics: true`), o SDK coleta CPU do sistema, memória, disco do volume do bot e RSS/CPU do próprio processo — **sem dependência nova** e sem timer próprio: a leitura pega carona em cada heartbeat e em cada poll de tasks (série da instância em **Instâncias → recursos da máquina**) e vai como `contexts.machine` em cada evento (card **"máquina no momento do erro"** no detalhe da issue). Assim dá para responder se o ambiente tem recurso suficiente e se um erro coincidiu com CPU/memória no limite.
-
-```js
-Hobots.init({ clientSecret, instanceId: 'vm-01', heartbeat: true }); // coleta ligada
-Hobots.init({ clientSecret, instanceId: 'vm-01', machineMetrics: false }); // desliga
-```
-
-O snapshot tem ~600 bytes (teto do servidor: 4 KiB). Formato em [Protocolo → MachineSnapshot](./protocol.md#machinesnapshot).
-
-## Flush e close
-
-Nada é enviado na hora: cada evento, transaction 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 polling de tasks (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 da telemetria são `unref`'d, então ela **não** segura o processo vivo sozinha (só o `start()` das tasks segura).
-
-> **Atenção:** `close()` é **terminal**. Depois dele, todo evento, transaction 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 de tasks, outra no flush final. `close(15_000)` pode levar até ~30s no pior caso. Dimensione por aí se o seu SIGTERM tem prazo curto.