hobots 1.7.4 → 1.7.6

package/dist/protocol.d.cts

@@ -125,18 +125,18 @@ interface EventPayload {
     release?: string;
     environment?: string;
 }
-/** Status de um span (etapa). `warning` = terminou, mas merece atenção (não é falha). */
-type SpanStatus = 'ok' | 'warning' | 'error' | 'cancelled';
-interface SpanData {
+/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */
+type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';
+interface StepData {
     /** 16 hex */
-    span_id: string;
-    parent_span_id?: string;
+    step_id: string;
+    parent_step_id?: string;
     op?: string;
     description?: string;
-    status?: SpanStatus;
+    status?: StepStatus;
     /** ISO 8601 */
     start_timestamp: string;
-    /** ISO 8601 (fim do span) */
+    /** ISO 8601 (fim da step) */
     timestamp: string;
     data?: Record<string, unknown>;
 }
@@ -147,7 +147,7 @@ interface TransactionPayload {
     status: string;
     start_timestamp: string;
     timestamp: string;
-    spans: SpanData[];
+    steps: StepData[];
     tags?: Record<string, string>;
     release?: string;
     environment?: string;
@@ -199,4 +199,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { AgentInfo, Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };
+export type { AgentInfo, Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };

package/dist/protocol.d.ts

@@ -125,18 +125,18 @@ interface EventPayload {
     release?: string;
     environment?: string;
 }
-/** Status de um span (etapa). `warning` = terminou, mas merece atenção (não é falha). */
-type SpanStatus = 'ok' | 'warning' | 'error' | 'cancelled';
-interface SpanData {
+/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */
+type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';
+interface StepData {
     /** 16 hex */
-    span_id: string;
-    parent_span_id?: string;
+    step_id: string;
+    parent_step_id?: string;
     op?: string;
     description?: string;
-    status?: SpanStatus;
+    status?: StepStatus;
     /** ISO 8601 */
     start_timestamp: string;
-    /** ISO 8601 (fim do span) */
+    /** ISO 8601 (fim da step) */
     timestamp: string;
     data?: Record<string, unknown>;
 }
@@ -147,7 +147,7 @@ interface TransactionPayload {
     status: string;
     start_timestamp: string;
     timestamp: string;
-    spans: SpanData[];
+    steps: StepData[];
     tags?: Record<string, string>;
     release?: string;
     environment?: string;
@@ -199,4 +199,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { AgentInfo, Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };
+export type { AgentInfo, Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };

package/docs/README.md

@@ -6,16 +6,16 @@ O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do ag
 
 | Capability | Como habilita | Para quê |
 | --- | --- | --- |
-| **Telemetria** | sempre ativa no `init()` | O que o programa **emite** sozinho: erros com stack trace (módulo **Issues**), performance (transactions/spans) e heartbeats de uptime (módulo **Agentes**), check-ins de cron (módulo **Monitores**). Instala handlers globais de erro; os timers são `unref`'d, então nunca seguram o processo vivo. |
+| **Telemetria** | sempre ativa no `init()` | O que o programa **emite** sozinho: erros com stack trace (módulo **Issues**), performance (transactions/etapas) e heartbeats de uptime (módulo **Agentes**), check-ins de cron (módulo **Monitores**). Instala handlers globais de erro; os timers são `unref`'d, então nunca seguram o processo vivo. |
 | **Tasks** | `tasks: true` (ou opções) no `init()` | Execução **sob demanda**: o agente faz polling no app, executa handlers registrados e reporta status/logs — o módulo **Solicitações**. `start()` **mantém o processo vivo** até `stop()`/`close()`. |
 
 ## Páginas
 
-Se termos como transaction, span, breadcrumb, tag, context, extra, flush e close ainda não são familiares, comece por **Conceitos** — as outras páginas assumem esse vocabulário.
+Se termos como transaction, step, breadcrumb, tag, context, extra, flush e close ainda não são familiares, comece por **Conceitos** — as outras páginas assumem esse vocabulário.
 
 - [Conceitos](./concepts.md) — o vocabulário: o que cada coisa é, por que existe e quando escolher uma em vez da outra.
 - [Getting started](./getting-started.md) — instalação, Client Secret, o `init` único, telemetria e tasks.
-- [Telemetria](./monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons e heartbeat.
+- [Telemetria](./monitor.md) — erros, breadcrumbs, escopo, transactions/etapas, crons e heartbeat.
 - [Tasks](./tasks.md) — registro de handlers, `RunContext`, cancelamento, concorrência, idempotência.
 - [Referência de API](./api-reference.md) — todas as funções e tabelas de opções com defaults.
 - [Protocolo & transporte](./protocol.md) — o Client Secret, endpoints, envelope, retries e onde vive o claim atômico.

package/docs/api-reference.md

@@ -4,7 +4,7 @@
 
 | Import | Conteúdo |
 | --- | --- |
-| `hobots` | Tudo: `init` único, funções de telemetria, `register`/`start`/`stop` de tasks, `close`, classes (`Client`, `Scope`, `Transaction`, `Span`), `DEFAULT_BASE_URL`, `scrubSecrets` e tipos. |
+| `hobots` | Tudo: `init` único, funções de telemetria, `register`/`start`/`stop` de tasks, `close`, classes (`Client`, `Scope`, `Transaction`, `Step`), `DEFAULT_BASE_URL`, `scrubSecrets` e tipos. |
 | `hobots/protocol` | Tipos do wire format (telemetria e tasks). |
 
 ---
@@ -50,7 +50,7 @@ Os conceitos por trás dessas chamadas estão em [Conceitos](./concepts.md); aqu
 - **`flush(timeoutMs = 5_000)`** → `Promise<boolean>` — empurra a fila do transport e aguarda os envios em andamento. `true` = tudo saiu no prazo; `false` = o SDK parou de esperar (os envios em voo seguem tentando). O SDK **continua utilizável** depois. Conceito: [Fila, flush e close](./concepts.md#fila-flush-e-close).
 - **`close(timeoutMs = 5_000)`** → `Promise<boolean>` — encerra tudo na ordem agente → heartbeat → flush final. O `timeoutMs` é gasto **duas vezes** (espera das runs, depois flush). Depois do `close()` o transport está fechado e todo item novo é descartado com aviso no console; não há `reopen()`. Conceito: [Fila, flush e close](./concepts.md#fila-flush-e-close).
 
-Classes exportadas: `Client`, `Scope`, `Transaction`, `Span`. A resolução da credencial nos endpoints é interna ao `init()` (constante `DEFAULT_BASE_URL = 'https://api2.hobots.app'`, exportada; em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base). A config resolvida fica acessível em `getClient()?.config`:
+Classes exportadas: `Client`, `Scope`, `Transaction`, `Step`. A resolução da credencial nos endpoints é interna ao `init()` (constante `DEFAULT_BASE_URL = 'https://api2.hobots.app'`, exportada; em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base). A config resolvida fica acessível em `getClient()?.config`:
 
 ```ts
 getClient()?.config; // {
@@ -61,12 +61,12 @@ getClient()?.config; // {
 // }
 ```
 
-### Métodos de `Transaction` / `Span` / `Scope`
+### Métodos de `Transaction` / `Step` / `Scope`
 
 Todos encadeáveis, exceto `finish()` e `toJSON()`.
 
-- **`Transaction`** — `startChild(op?, description?) → Span` abre um [span](./concepts.md#span) direto; `setTag(k, v)` marca a transaction (tags de scope **não** são herdadas); `setStatus(s)` (default `'ok'`); `setName(n)` renomeia antes do envio; `finish()` fecha os spans abertos, monta o payload e envia — é **idempotente** e não envia nada se a transaction não foi amostrada.
-- **`Span`** — `startChild(op?, description?) → Span` aninha um filho (profundidade arbitrária); `setStatus(s)` (default `'ok'`); `setData(k, v)` anexa dados só àquele span; `finish()` marca o fim — **opcional**, porque o `finish()` da transaction fecha o que ficou aberto; `toJSON()` serializa no formato do wire.
+- **`Transaction`** — `startChild(op?, description?) → Step` abre uma [step](./concepts.md#step) direta; `setTag(k, v)` marca a transaction (tags de scope **não** são herdadas); `setStatus(s)` (default `'ok'`); `setName(n)` renomeia antes do envio; `finish()` fecha as etapas abertas, monta o payload e envia — é **idempotente** e não envia nada se a transaction não foi amostrada.
+- **`Step`** — `startChild(op?, description?) → Step` aninha uma filha (profundidade arbitrária); `setStatus(s)` (default `'ok'`); `setData(k, v)` anexa dados só àquela step; `finish()` marca o fim — **opcional**, porque o `finish()` da transaction fecha o que ficou aberto; `toJSON()` serializa no formato do wire.
 - **`Scope`** — `setTag`/`setTags`/`setUser`/`setContext`/`setExtra`/`setExtras`/`setLevel`/`setFingerprint`/`addBreadcrumb`/`clearBreadcrumbs`/`clone`. Alcançável via [`withScope`](./concepts.md#withscope). `setContext(name, null)` apaga o grupo; `setUser(null)` remove o usuário.
   > **Atenção:** `setLevel` **não tem efeito** em `captureException` (que já grava `error`) nem em `captureMessage` (que já grava `info`) — os dois definem o level do evento antes de o scope ser consultado. Use o `hint`.
 

package/docs/concepts.md

@@ -1,6 +1,6 @@
 # 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**.
+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, step, 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.
 
@@ -20,7 +20,7 @@ Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e interval
 | [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                        |
+| [Step](#step)                                           | 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 de task                       |
 | [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                                |
@@ -45,7 +45,7 @@ Cada API do SDK alimenta um módulo do app da Hobots (app.hobots.app). O mapa:
 | **Instância** — o par `(project_id, instance_id)`; heartbeat e poll de tasks convergem nele | Módulo **Agentes** (uptime, performance) |
 | **[Evento](#evento)** agrupado em **issue** — `captureException` / `captureMessage` | Módulo **Issues** |
 | **Monitor (cron)** — `withMonitor` / `checkIn` com `schedule` | Módulo **Monitores** |
-| **[Transaction](#transaction) / spans** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **Agentes**; nas execuções, a aba de performance da solicitação |
+| **[Transaction](#transaction) / etapas** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **Agentes**; nas execuções, a aba de performance da solicitação |
 | **Task / [run](#run)** — `register('task-slug', …)` casa com o `task_slug` do formulário | Módulo **Solicitações** (formulários em **Configurações → Formulários**) |
 
 ---
@@ -218,7 +218,7 @@ 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?".
+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 [etapas](#step), para "onde foram esses minutos?".
 
 Enquanto o [evento](#evento) responde _o que quebrou_, a transaction responde _quanto tempo levou_. São os dois eixos da telemetria.
 
@@ -234,37 +234,37 @@ O primeiro argumento é o **nome** (o que agrupa transactions comparáveis no ap
 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.
+- **`finish()` é idempotente e fecha o resto.** Chamar duas vezes não envia duas; e ele **finaliza automaticamente** todas as etapas que ficaram abertas.
 - **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 de task você **não** cria transaction — já existe uma em [`ctx.tx`](#transaction-de-run-ctxtx), e o `startTransaction()` chamado lá dentro devolve exatamente ela.
 
-## Span
+## Step
 
-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.
+Uma **step** (etapa) é medida **dentro** de uma [transaction](#transaction). A transaction diz que a rotina levou 4 minutos; as etapas dizem que 3min40 foram esperando o portal.
 
 ```js
-const span = tx.startChild('http.client', 'GET /api/notas');
+const step = tx.startChild('http.client', 'GET /api/notas');
 await api.buscarNotas();
-span.setData('notas', 42).finish();
+step.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.
+`startChild(op?, description?)` existe **tanto na transaction quanto na step**, então você aninha quanto quiser — uma step de "processar nota" com filhas 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.
+O `op` é a categoria (útil para agrupar "todas as queries") e a `description` é o detalhe humano ("`INSERT INTO notas`"). `setData(chave, valor)` anexa dados àquela step específica — contagens, tamanhos, ids.
 
 - Métodos encadeáveis: `setStatus`, `setData`, `finish`.
-- **Status do span:** `'ok'` (default), `'warning'` (terminou, mas merece atenção — não é falha) ou `'error'` (falhou). No waterfall do app cada um tem sua cor: verde/neutro, âmbar e vermelho. Use `span.setStatus('warning')` para etapas que passaram com ressalva (ex.: retry que deu certo, resultado parcial).
-- 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.
+- **Status da step:** `'ok'` (default), `'warning'` (terminou, mas merece atenção — não é falha) ou `'error'` (falhou). No waterfall do app cada um tem sua cor: verde/neutro, âmbar e vermelho. Use `step.setStatus('warning')` para etapas que passaram com ressalva (ex.: retry que deu certo, resultado parcial).
+- Esquecer o `finish()` de uma step **não perde o dado**: o `finish()` da transaction fecha as etapas abertas, marcando o fim naquele instante.
+- As etapas são guardadas numa lista plana ligada por `parent_step_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 de task 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.
+O que sobra para você é a parte interessante: marcar as **etapas** do trabalho com [steps](#step). Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app.
 
 ```js
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -273,17 +273,17 @@ Hobots.register('processar-nfe', async (params, ctx) => {
   login.finish();
 
   for (const nota of params.notas) {
-    const span = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
+    const step = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
     ctx.throwIfCanceled();
     await processar(nota);
-    span.setData('valor', nota.valor).finish();
+    step.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".
+Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da run — o waterfall só fica com uma barra. Cada step que você abre é uma resposta a mais para "onde foram os 4 minutos".
 
-- **`Hobots.startTransaction()` dentro de um handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: o SDK detecta o contexto da run e reutiliza a transaction dela em vez de criar uma segunda — os spans caem no mesmo waterfall. Fora de um handler, `startTransaction()` cria uma transaction nova, sem `run_id`.
+- **`Hobots.startTransaction()` dentro de um handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: o SDK detecta o contexto da run e reutiliza a transaction dela em vez de criar uma segunda — as etapas caem no mesmo waterfall. Fora de um handler, `startTransaction()` cria uma transaction nova, sem `run_id`.
 - `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale para as transactions que **você** abre com `startTransaction()` fora de uma run.
 - O nome é `run:<task>` e o `op` é `hobots.task`, preenchidos pelo SDK.
 

package/docs/monitor.md

@@ -88,18 +88,18 @@ 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
+## Performance: transactions e etapas
 
-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).
+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 span = tx.startChild('http.client', 'GET /api/notas');
+const step = tx.startChild('http.client', 'GET /api/notas');
 await api.buscarNotas();
-span.setData('notas', 42).finish();
+step.setData('notas', 42).finish();
 
-const filho = span.startChild('db.query', 'INSERT INTO notas'); // spans aninham
+const filho = step.startChild('db.query', 'INSERT INTO notas'); // etapas aninham
 await gravar();
 filho.finish();
 
@@ -107,11 +107,11 @@ tx.setStatus('ok'); // ou 'error'
 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).
-- Status de span: `'ok'` (default), `'warning'` (atenção, não é falha) ou `'error'` — cores distintas no waterfall.
-- `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.
+- `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.

package/docs/tasks.md

@@ -79,20 +79,20 @@ Hobots.register('processar-nfe', async (params, ctx) => {
   login.finish();
 
   for (const nota of params.notas) {
-    const span = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
+    const step = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
     ctx.throwIfCanceled();
     await processar(nota);
-    span.setData('valor', nota.valor).finish();
+    step.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.
+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 nenhuma step, a transaction ainda mede o tempo total da run; o waterfall só fica com uma barra.
 
-- **`startTransaction()` dentro do handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: se o seu código (ou uma lib sua já instrumentada) chamar `Hobots.startTransaction()` dentro de um handler, o SDK detecta o contexto da run e retorna a transaction dela em vez de criar uma segunda — os spans caem no mesmo waterfall. Fora de um handler, `startTransaction()` cria uma transaction nova, sem `run_id`.
+- **`startTransaction()` dentro do handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: se o seu código (ou uma lib sua já instrumentada) chamar `Hobots.startTransaction()` dentro de um handler, o SDK detecta o contexto da run e retorna a transaction dela em vez de criar uma segunda — as etapas caem no mesmo waterfall. Fora de um handler, `startTransaction()` cria uma transaction nova, sem `run_id`.
 - `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale só para as transactions abertas com `startTransaction()` fora de uma run.
-- Span que você esquecer aberto é fechado no `finish()` da transaction, então o dado não se perde.
-- Marque etapas com ressalva usando `span.setStatus('warning')` (ex.: retry que deu certo, resultado parcial): elas aparecem em âmbar no waterfall, distintas de sucesso e de falha (`'error'`).
+- Step que você esquecer aberta é fechada no `finish()` da transaction, então o dado não se perde.
+- Marque etapas com ressalva usando `step.setStatus('warning')` (ex.: retry que deu certo, resultado parcial): elas aparecem em âmbar no waterfall, distintas de sucesso e de falha (`'error'`).
 
 ## Cancelamento cooperativo
 

package/package.json

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