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

# Saúde e Prontidão

> Monitoramento da saúde da API, endpoints de prontidão e página de status.

Monitore a saúde da API Truthlocks, verifique a prontidão para dependências e integre-se à sua pilha de observabilidade.

## Endpoints de integridade

### Liveness Probe

Verifique se a API está em execução. Use para sondas de vivacidade do Kubernetes:

```http theme={null}
GET https://api.truthlocks.com/health/live

# Response (200 OK)
{
  "status": "ok",
  "timestamp": "2026-01-13T12:00:00Z"
}
```

### Sondagem de Prontidão

Verifique se a API está pronta para atender ao tráfego (todas as dependências saudáveis):

```http theme={null}
GET https://api.truthlocks.com/health/ready

# Response (200 OK - All systems operational)
{
  "status": "ok",
  "timestamp": "2026-01-13T12:00:00Z",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "signing_service": "ok",
    "transparency_log": "ok"
  }
}
```

```http theme={null}
# Response (503 Service Unavailable - Degraded)
{
  "status": "degraded",
  "timestamp": "2026-01-13T12:00:00Z",
  "checks": {
    "database": "ok",
    "redis": "timeout",
    "signing_service": "ok",
    "transparency_log": "ok"
  }
}
```

## Configuração do Kubernetes

Se você estiver construindo aplicativos que dependem do Truthlocks, configure suas sondas para verificar tanto seu aplicativo quanto a API do Truthlocks:

```yaml theme={null}
apiVersion: v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: app
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
            failureThreshold: 3
```

### Exemplo de Verificação de Prontidão (App)

```javascript theme={null}
// Include Truthlocks health in your app's readiness
app.get('/health/ready', async (req, res) => {
  const checks = {
    database: await checkDatabase(),
    truthlock: await checkTruthlock(),
  };

  const allHealthy = Object.values(checks).every(c => c === 'ok');

  res.status(allHealthy ? 200 : 503).json({
    status: allHealthy ? 'ok' : 'degraded',
    checks,
  });
});

async function checkTruthlock(): Promise<string> {
  try {
    const res = await fetch('https://api.truthlocks.com/health/ready', {
      timeout: 5000,
    });
    return res.ok ? 'ok' : 'degraded';
  } catch {
    return 'unreachable';
  }
}
```

## Página de status

Verifique a saúde e o tempo de atividade do serviço em tempo real em [status.truthlocks.com](https://status.truthlocks.com). A página de status é atualizada automaticamente a cada 60 segundos e não requer autenticação.

### Serviços monitorizados

A página de status rastreia a saúde de cada serviço principal independentemente:

| Serviço | Descrição |
| - | - |
| Gateway API | Ponto de extremidade principal da API para todas as solicitações |
| Registro de Confiança | Gerenciamento e governança do emissor |
| Faturamento | Processamento de assinatura e pagamento |
| Assinatura | Operações de assinatura criptográfica |
| Atestados | Cunhagem e gerenciamento de atestados |
| Registros de Auditoria | Registro de atividades e conformidade |
| Log de Transparência | Log criptográfico somente de adição |
| Verificação | Verificação de pacote de prova |
| Identidade da Máquina | Registro de agente, sessões e pontuação de confiança |
| CMO de IA | Moderação e orquestração de conteúdo de IA |

Cada serviço reporta um dos quatro status: **operacional**, **degradado**, **interrupção** ou **desconhecido**. A página exibe um tempo de resposta por serviço e um banner de saúde geral do sistema.

### Histórico de tempo de atividade

Uma barra de tempo de atividade de 90 dias mostra a disponibilidade diária para cada serviço. Passe o mouse sobre qualquer dia para ver a data e a porcentagem de tempo de atividade. Uma porcentagem geral de tempo de atividade é exibida ao lado de cada serviço.

### Histórico de incidentes

Visite a página **Histórico de Incidentes** para ver incidentes passados em formato de linha do tempo. Cada entrada inclui o nível de gravidade, serviços afetados e atualizações com carimbo de data/hora desde a investigação até a resolução.

### Assinar notificações

Insira seu e-mail na parte inferior da página de status para receber notificações de incidentes. Você será notificado quando os incidentes forem criados, atualizados ou resolvidos.

Clientes empresariais também podem configurar retornos de chamada de webhook para receber eventos de mudança de status automaticamente.

### API de status programático

Consulte a API de status para obter a saúde do serviço legível por máquina. Use isso para integrar a disponibilidade do Truthlocks em seus próprios painéis, pipelines de alerta ou verificações pré-voo. Nenhuma autenticação é necessária.

```http theme={null}
GET https://status.truthlocks.com/api/health
```

O endpoint retorna o status geral do sistema, um carimbo de data/hora e um array de verificações de saúde por serviço:

```json theme={null}
{
  "status": "operational",
  "timestamp": "2026-03-26T14:30:00Z",
  "services": [
    {
      "id": "api-gateway",
      "name": "API Gateway",
      "status": "operational",
      "responseTime": 42
    },
    {
      "id": "signing-service",
      "name": "Signing",
      "status": "degraded",
      "responseTime": 1200,
      "error": "HTTP 503"
    }
  ]
}
```

**Campos de resposta:**

| Campo | Tipo | Descrição |
| - | - | - |
| `status` | string | Saúde geral do sistema: `operational`, `degraded`, ou `outage`. |
| `timestamp` | string | Carimbo de data/hora ISO 8601 da verificação. |
| `services` | array | Resultados de saúde por serviço. |
| `services[].id` | string | Identificador de serviço legível por máquina (por exemplo, `api-gateway`, `signing-service`). |
| `services[].name` | string | Nome do serviço legível. |
| `services[].status` | string | Saúde do serviço: `operational`, `degraded`, ou `outage`. |
| `services[].responseTime` | number or null | Tempo de resposta em milissegundos, ou `null` se inacessível. |
| `services[].error` | string | Presente apenas quando o serviço não está operacional. |

O status geral é `outage` se algum serviço estiver inativo, `degraded` se algum serviço estiver lento ou retornando erros, e `operational` quando todos os serviços estiverem saudáveis.

**Exemplo: consultar status do seu aplicativo**

```javascript theme={null}
async function checkTruthlockStatus() {
  const res = await fetch("https://status.truthlocks.com/api/health");
  const data = await res.json();

  if (data.status !== "operational") {
    console.warn(`Truthlocks is ${data.status}`);
    const issues = data.services.filter((s) => s.status !== "operational");
    issues.forEach((s) => console.warn(`  ${s.name}: ${s.status} — ${s.error}`));
  }

  return data;
}
```

**Exemplo: verificação pré-voo antes da cunhagem**

Verifique se os serviços de assinatura e atestado estão saudáveis antes de tentar uma operação de cunhagem. Isso evita novas tentativas desnecessárias quando você já sabe que os serviços necessários estão inoperantes.

```javascript theme={null}
async function mintWithStatusCheck(attestation) {
  const status = await fetch("https://status.truthlocks.com/api/health");
  const health = await status.json();

  const signing = health.services.find((s) => s.id === "signing-service");
  const attestations = health.services.find(
    (s) => s.id === "attestation-service"
  );

  if (
    signing?.status !== "operational" ||
    attestations?.status !== "operational"
  ) {
    throw new Error("Required services are not operational — retry later");
  }

  return client.attestations.mint(attestation);
}
```

> [!NOTE]
>
> A API de status é limitada por taxa para evitar abusos. Para monitoramento contínuo,
> consultar não mais frequentemente do que uma vez a cada 30 segundos.

Para o esquema de resposta completo, IDs de serviço monitorados e exemplos adicionais, consulte a [referência da API de status](https://docs.truthlocks.com/pt/api-reference/health/status.md).

> [card] [Página de status](https://status.truthlocks.com)
>
> Saúde do serviço em tempo real e histórico de incidentes.

> [card] Notificações de webhook
>
> Clientes empresariais podem configurar callbacks de webhook para mudanças de status.

> [card] [Referência da API de status](https://docs.truthlocks.com/api-reference/health/status.md)
>
> Referência completa da API para o endpoint de status programático.

> [card] Alertas por e-mail
>
> Assine a página de status para notificações de incidentes.

## Compromissos de nível de serviço

Metas de disponibilidade, cobertura de suporte, tempos de resposta e créditos de serviço aplicam-se apenas quando explicitamente acordados no contrato aplicável. As verificações de saúde públicas relatam o estado do serviço observado; elas não estabelecem uma porcentagem de tempo de atividade garantida, capacidade de recuperação de ponta a ponta ou cronograma de suporte com equipe. Confirme a implantação atual e as evidências de recuperação antes de confiar em um compromisso.

## Integração de monitoramento

Integre as verificações de saúde do Truthlocks com suas ferramentas de observabilidade:

```yaml Prometheus theme={null}
# prometheus.yml
scrape_configs:
  - job_name: "truthlock-health"
    scrape_interval: 30s
    metrics_path: /metrics
    static_configs:
      - targets: ["api.truthlocks.com"]
```

```yaml Datadog theme={null}
# datadog.yaml
init_config:

instances:
  - name: truthlock_api
    url: https://api.truthlocks.com/health/ready
    timeout: 5
    content_match: '"status":"ok"'
    http_response_status_code: 200
    tags:
      - service:truthlock
      - env:production
```

```javascript Custom Dashboard Metrics theme={null}
// Export key metrics for dashboards
const metrics = {
  "truthlock.availability": isHealthy ? 1 : 0,
  "truthlock.latency_ms": responseTime,
  "truthlock.ratelimit_remaining": rateLimitRemaining,
  "truthlock.attestations_today": dailyCount,
};
```

## Resiliência do gateway

O gateway da API inclui recuperação automática de pânico e suporte a implantação sem tempo de inatividade:

* **Recuperação de pânico** — Se o gateway encontrar um erro interno inesperado, ele se recupera automaticamente e retorna uma resposta de erro estruturada em vez de derrubar sua conexão. Você não precisa lidar com conexões derrubadas causadas por pânicos no nível do gateway.
* **Desligamento gracioso** — Durante as implantações, o gateway e o serviço de assinatura drenam as requisições em andamento em uma janela de 15 segundos, em vez de terminá-las imediatamente. Se você anteriormente experimentou falhas ocasionais de requisição durante as janelas de manutenção, elas não devem mais ocorrer.

Essas proteções funcionam automaticamente e não exigem alterações na sua integração.

## Resposta a incidentes

Se a Truthlocks estiver com problemas:

1. **Verificar página de status:** [status.truthlocks.com](https://status.truthlocks.com)
2. **Habilitar disjuntor:** Falhe graciosamente em seu aplicativo
3. **Operações de fila:** Tentar novamente a cunhagem de atestado mais tarde
4. **Entre em contato com o suporte:** Para escalonamento de SLA Enterprise

### Padrão de Disjuntor

```javascript theme={null}
import CircuitBreaker from "opossum";

const breaker = new CircuitBreaker(
  async (attestation) => client.attestations.mint(attestation),
  {
    timeout: 5000, // Fail if no response in 5s
    errorThresholdPercentage: 50, // Open if 50% fail
    resetTimeout: 30000, // Try again after 30s
  },
);

breaker.fallback(() => {
  // Queue for retry later
  queue.add("retry-attestation", attestation);
  return { queued: true };
});
```

## Próximos passos

> [card] [Painel de observabilidade](https://docs.truthlocks.com/guides/observability.md)
>
> Monitore a saúde do serviço, latência e uso a partir da console.

> [card] [Referência de erro](https://docs.truthlocks.com/ops/errors.md)
>
> Lista completa de códigos de erro e tratamento.

> [card] [Limites de taxa](https://docs.truthlocks.com/ops/limits.md)
>
> Lide com a limitação de taxa de forma elegante.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.