# Logs e diagnóstico
> Produza logs úteis com console.log(), aplique cor somente quando ela melhora a leitura e evite flood em rotinas repetitivas.

- Área: Operação
- URL humana: https://ninenity.vercel.app/doc/logs
- URL Markdown: https://ninenity.vercel.app/doc/markdown/logs
- Pacotes e conceitos: console.log, Color, Contexto, Anti-flood

## Use console.log() como saída

O código da aplicação não precisa de `Logger.info()`, `Logger.warn()` ou `Logger.error()`.

### logs diretos

```text

console.log('[Commands] comando registrado: ping')
console.log('[Database] conexão estabelecida')
console.log('[API] requisição falhou: status=502')
```


> **Uma convenção simples:** Comece com uma tag curta, descreva o evento e adicione somente os campos que ajudam a reproduzir ou medir o resultado.

## Color para ênfase visual

`Color` formata texto ANSI; `console.log()` continua sendo o responsável por imprimir.

### Color.ts

```text

import { Color } from '@ninenity/core'

console.log(Color.green('[Database] conectado').bold())
console.log(Color.yellow('[WebSocket] reconectando'))
console.log(Color.red('[API] falha ao buscar configuração').bold())

// Forma funcional
console.log(Color('Deploy concluído', 'lightGreen', 'bold'))

// Chain vazia com text no final
console.log(Color().lightBlue().bold().text('[Core] pronto'))
```


| Cores | Estilos |
| --- | --- |
| `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray` | `bold`, `dim`, `italic`, `underline` |
| `lightRed`, `lightGreen`, `lightYellow`, `lightBlue` | `strikethrough`, `inverse`, `hidden`, `visible` |

> **Cor não substitui contexto:** Um terminal inteiramente colorido é tão difícil de ler quanto um sem hierarquia. Reserve cor para estados ou tags importantes e mantenha o corpo neutro quando possível.

## Inclua contexto útil

Formato consistente torna busca, dashboard e investigação muito mais simples.

### contextual logging

```text

function logCommand(input: {
  command: string
  guildId?: string | null
  userId: string
  durationMs: number
}) {
  console.log(
    '[Command] name=' + input.command +
    ' guild=' + (input.guildId ?? 'dm') +
    ' user=' + input.userId +
    ' duration=' + input.durationMs + 'ms'
  )
}

logCommand({
  command: interaction.commandName,
  guildId: interaction.guildId,
  userId: interaction.user.id,
  durationMs: Date.now() - startedAt
})
```


- Inclua o módulo ou domínio na tag: `[Prompt]`, `[Task:catalog]`, `[Database]`.
- Use pares `chave=valor` para IDs, duração, quantidade e estado.
- Não registre tokens, cookies, API secrets, conteúdo privado ou payloads completos de usuários.
- Para erros, registre a mensagem e o ponto da operação; stack completa apenas quando realmente necessária.

## Evite flood em reconexões e loops

A operação continua em frequência normal, mas a comunicação ao usuário pode ser agregada.

### aviso agregado de WebSocket

```text

const REPORT_INTERVAL = 10 * 60 * 1000
let lastReportAt = 0
let failedAttempts = 0

function onWebSocketFailure(message: string) {
  failedAttempts += 1
  const now = Date.now()

  if (lastReportAt && now - lastReportAt < REPORT_INTERVAL) return

  lastReportAt = now
  console.log(
    '[WebSocket] conexão indisponível; reconexão segue em segundo plano' +
    ' attempts=' + failedAttempts +
    ' lastError=' + message
  )
  failedAttempts = 0
}
```


A função de reconexão pode continuar com backoff próprio a cada poucos segundos. O intervalo de dez minutos limita apenas o aviso visível, não a tentativa técnica.

### resumo de lote

```text

const results = await Promise.allSettled(items.map(processItem))
const failed = results.filter(result => result.status === 'rejected')

console.log(
  '[Import] total=' + results.length +
  ' success=' + (results.length - failed.length) +
  ' failed=' + failed.length
)
```


## Diagnóstico em produção

| Sinal | Pergunta que responde |
| --- | --- |
| Boot concluído | O auto-loader e os plugins terminaram? |
| Comandos registrados | Quantos módulos foram aceitos por guild/global? |
| Duração | A operação ficou lenta ou expirou? |
| Guild e usuário | Qual contexto reproduz o problema? |
| Tentativas agregadas | Uma integração está instável sem inundar o terminal? |

> **Logs contam a história, métricas mostram a tendência:** Use logs para eventos discretos e diagnóstico. Use telemetria para volume, latência, memória, CPU e taxa de falhas ao longo do tempo.