> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Observabilidade no Flowker

> Configure a telemetria do Flowker e use os endpoints de health e os registros de execução para operar os workflows.

O Flowker pode emitir dados de OpenTelemetry das operações HTTP e de serviço dele. A telemetria é opt-in: habilite-a no deploy, mande-a para o seu collector e use a API de execuções para o status e os resultados de cada workflow.

## Habilitar e exportar a telemetria

***

Defina estas variáveis de ambiente no deploy do Flowker:

```bash theme={null}
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otlp-collector.example:4317
```

Com a telemetria habilitada, o Flowker inicializa os instrumentos de telemetria dele e exporta pelo endpoint OTLP configurado. Você não adiciona instrumentação a cada workflow, mas o deploy deve fornecer um collector alcançável. Use um endpoint `https://` para um collector remoto. Reserve um endpoint `http://` em texto claro para um collector local ao host ou alcançável apenas por uma rede isolada. O Flowker não provisiona dashboards do Grafana, retenção nem regras de alerta. Essas são decisões da sua plataforma de observabilidade.

## Verificar a saúde do serviço

***

O Flowker expõe probes compatíveis com Kubernetes. O endpoint `GET /health` é uma checagem de liveness. Depois que o self-probe de inicialização dele passa, ele devolve `200 healthy` e, de propósito, não chama o banco de dados, o cache nem os serviços downstream. O endpoint `GET /readyz` é a checagem de readiness das dependências. Use-o quando você precisa saber se o Flowker consegue atender requisições agora.

## Usar a sua plataforma de observabilidade

***

Direcione o fluxo OTLP para o backend que a sua plataforma opera, como o Grafana, e monte os dashboards e os alertas lá. Mantenha esses dashboards separados da investigação de execuções: a telemetria das requisições da API não substitui o registro da execução.

Para uma rodada específica de workflow, use [Obter resultados da execução](/pt/reference/products/flowker/get-execution-results) para ver o status, os resultados das etapas e a saída final dela, quando presente. Uma etapa com falha pode incluir um `errorMessage`. Esta resposta não tem campo de detalhes de erro no nível superior.

## Como interpretar o status da execução

***

Cada execução de workflow no Flowker tem um status que diz a você em que ponto ela está.

| Status      | Significado                                                                                                                                                                             | O que fazer                                                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `pending`   | A execução foi criada, mas não começou. No caminho normal de execução, o Flowker a muda para `running` de forma síncrona antes de responder; não trate isso como uma fila de agendador. | —                                                                                                                                   |
| `running`   | A execução está em andamento                                                                                                                                                            | Normal — acompanhe até a conclusão                                                                                                  |
| `completed` | Todas as etapas terminaram com sucesso                                                                                                                                                  | Nenhuma ação necessária                                                                                                             |
| `failed`    | A execução terminou com erro                                                                                                                                                            | Verifique `stepResults` em busca de uma etapa com falha. Uma falha anterior à primeira etapa não traz erro de etapa nesta resposta. |

<Tip>
  Se você vê um número expressivo de execuções `failed` em um período curto, junte os ids de execução e os detalhes de erro delas antes de escalar.
</Tip>

## Quando envolver a engenharia

***

Escale para a engenharia quando:

* `GET /readyz` informa uma dependência fora do ar
* o collector OTLP está inalcançável ou rejeita o fluxo de telemetria
* as execuções `failed` passam do limiar de alerta que o seu deploy define e a causa não está clara
* o Flowker não processa novas execuções enquanto a readiness continua bem-sucedida

Compartilhe os ids de execução, a janela de tempo em UTC, os payloads de erro relevantes da API e a resposta do `/readyz`. Com a telemetria habilitada, inclua o link do collector ou do dashboard como evidência de apoio.