# Observabilidade do Banco de Talentos (Tarefa 7)

## Objetivo

Padronizar rastreabilidade e sinais minimos de operacao do modulo BT para diagnostico rapido de incidentes.

## O que foi implementado

- `correlation_id` em todas as requisicoes via `AssignCorrelationId` (header `X-Request-ID`).
- middleware `LogTalentBankRequestMetrics` no grupo `api`:
  - registra latencia por request do prefixo `/api/talent-bank/*`;
  - inclui metodo, path, status e flag de sucesso.
- helper `App\Support\TalentBank\Observability` para eventos/metricas estruturadas.
- canal de log dedicado:
  - `logging.channels.talent_bank_observability`
  - arquivo: `storage/logs/talent-bank-observability.log`
- eventos de negocio adicionados:
  - `candidate.register.success|failed`
  - `candidate.login.failed`
  - `candidate.self_edit.success|failed`
  - `candidate.contact.success|failed`
  - `company.register.success|failed`
  - `company.login.failed`
  - `company.self_edit.success|failed`
  - `job.application.created|create_failed|deleted|delete_failed`

Observacao: os eventos `*.failed` cobrem tanto excecao (`catch`) quanto retorno HTTP de erro das integracoes externas (ex.: `401/422/5xx`).

## Configuracao

No `.env`:

```env
TALENT_BANK_OBSERVABILITY_CHANNEL=talent_bank_observability
```

## Estrutura de log

Campos padrao esperados:

- `domain` (sempre `talent_bank`)
- `event` (nome do evento)
- `correlation_id` (quando disponivel)
- contexto especifico (ex.: `document`, `email`, `job_id`, `candidate_id`, `status_code`, `metric_value`)

## KPIs operacionais minimos

Com base nos eventos/metricas implementados:

1. **Taxa de cadastro concluido**
   - numerador: `candidate.register.success` + `company.register.success`
   - denominador: sucessos + falhas de cadastro
2. **Taxa de candidatura**
   - numerador: `job.application.created`
   - denominador: created + create_failed
3. **Falhas de integracao**
   - eventos `*.failed` relacionados a cadastro/self-edit/contato
4. **Latencia p95 dos endpoints criticos**
   - `event=metric.http_request_latency_ms`, agregado por `path`

## Consultas rapidas (PowerShell)

Exemplos usando `rg`:

```bash
rg "talent_bank\\.candidate\\.register\\.(success|failed)" "storage/logs/talent-bank-observability.log"
rg "metric\\.http_request_latency_ms" "storage/logs/talent-bank-observability.log"
rg "job\\.application\\.(created|create_failed|deleted|delete_failed)" "storage/logs/talent-bank-observability.log"
```

## Alertas sugeridos

- Pico de `*.failed` em janela de 5 minutos.
- p95 de `metric.http_request_latency_ms` > 1200ms em rotas de candidatura/cadastro.
- taxa de sucesso de candidatura abaixo de 95%.