Obter Métricas do Projeto

Escopo: esta página documenta métricas e logs da aplicação em execução. Logs de build GitHub usam endpoints separados em Builds GitHub.

Retorna as métricas de uso do projeto (CPU, memória, etc).

Permissões necessárias

Use project.metrics.read em project:<project-id> para métricas, capacidades, storage usage e analytics de rede. Use project.logs.read no mesmo projeto para logs da aplicação e builds. owner tem acesso completo; assistant, member e API Keys precisam do scope correspondente.

GET /v1/project/:id/metrics

Limite de requisições: 100 por minuto (contado por IP de origem).

Parâmetros de Path

Parâmetro	Tipo	Descrição
`id`	string	ID do projeto

Headers

Header	Obrigatório	Descrição
`x-api-key` ou `Authorization`	Sim	API Key da organização ou token de usuário
`x-organization-id`	Com token de usuário	Organização ativa do projeto. Dispensável com API Key da organização

Parâmetros de Query (opcionais)

Parâmetro	Tipo	Descrição
`instance`	string	Identificador de uma instância específica. Quando omitido, projetos HTTP retornam métricas de rede agregadas e projetos PostgreSQL e MariaDB retornam uma lista com o snapshot de cada instância. Obrigatório em projetos Analytics, Key-Value, Cache e Queue.

Resposta

O campo uptime representa o tempo de atividade atual da instância retornada pelo endpoint de métricas. Ele não deve ser interpretado como uptime da aplicação, SLA ou histórico de disponibilidade pública.

{
  "status": "success",
  "message": "get metrics with success",
  "data": {
    "type": "application",
    "aggregate": true,
    "network": {
      "requests": 1200,
      "bytes_received": 420000,
      "bytes_sent": 1800000,
      "status_codes": {
        "200": 1160,
        "500": 5
      },
      "user_agents": {
        "Mozilla/5.0": 900,
        "curl/8.0": 300
      },
      "window_seconds": 300
    }
  }
}

Métricas nativas de projetos Valkey

Projetos Valkey usam a mesma rota de métricas com o parâmetro instance, mas retornam um snapshot nativo sanitizado. O acesso deve ser verificado pelas capacidades do projeto antes da consulta.

Consultar capacidades

GET /v1/project/:id/metrics/capabilities

Para os tiers com acesso a snapshot, data retorna os grupos disponíveis, a frequência de atualização e a ausência de histórico:

{
  "data": {
    "access": "snapshot",
    "groups": [
      "resources",
      "capacity",
      "clients",
      "activity",
      "key_lifecycle",
      "profile",
      "reliability"
    ],
    "refresh_seconds": 60,
    "history": null
  }
}

Os planos Premium e Enterprise de Key-Value, Cache e Queue (db-premium, db-enterprise, cache-premium, cache-enterprise, queue-premium e queue-enterprise) oferecem snapshots. Quando access é none, não consulte o snapshot; o Console mostra a observabilidade como indisponível.

Consultar um snapshot

GET /v1/project/:id/metrics?instance=instance-1

O objeto de métricas em data tem o seguinte formato. cpu e memory no nível superior são os campos legados de recurso; os dados nativos ficam em valkey.

{
  "data": {
    "instance": "instance-1",
    "type": "valkey",
    "cpu": 0.25,
    "memory": 134217728,
    "observed_at": "2026-08-28T12:00:00.000Z",
    "availability": "available",
    "valkey": {
      "schema_version": 1,
      "profile": "cache",
      "availability": "available",
      "memory": {
        "used_bytes": 104857600,
        "peak_bytes": 125829120,
        "limit_bytes": 536870912,
        "fragmentation_ratio": 1.02
      },
      "clients": {
        "connected": 12,
        "blocked": 0
      },
      "activity": {
        "operations_per_second": 240,
        "input_bytes_per_second": 1048576,
        "output_bytes_per_second": 2097152
      },
      "keys": {
        "expired_total": 120,
        "evicted_total": 3
      },
      "uptime_seconds": 86400,
      "cache": {
        "hits_total": 3900,
        "misses_total": 100,
        "hit_ratio": 0.975
      },
      "reliability": {
        "replication": {
          "status": "not_applicable",
          "replicas_available": null,
          "replicas_expected": 1,
          "lag_seconds": null
        },
        "persistence": {
          "enabled": true,
          "status": "healthy",
          "last_success_at": "2026-08-28T11:59:55.000Z"
        }
      }
    }
  }
}

Os campos opcionais cache e key_value dependem do perfil do projeto:

cache: hits_total, misses_total e hit_ratio;
key_value: keys_total e keys_with_expiration.

A disponibilidade do snapshot pode ser available, partial, stale ou unavailable. Campos sem evidência suficiente retornam null; a API não substitui esses valores por dados inventados.

Quando não existe snapshot válido, a resposta mantém os metadados públicos e retorna valkey: null:

{
  "data": {
    "instance": "instance-1",
    "type": "valkey",
    "cpu": 0,
    "memory": 0,
    "observed_at": null,
    "availability": "unavailable",
    "valkey": null
  }
}

O contrato não oferece histórico nesta capacidade (history: null). Métricas específicas de fila, como profundidade, idade do item ou atraso do consumidor, não fazem parte do snapshot verificado.

Métricas nativas de PostgreSQL e MariaDB

Projetos PostgreSQL e MariaDB nos planos db-premium e db-enterprise usam os mesmos endpoints estáveis. Sem instance, a rota retorna uma lista com um snapshot por instância. Consulte as capacidades antes de solicitar o snapshot de uma instância:

GET /v1/project/:id/metrics/capabilities
GET /v1/project/:id/metrics?instance=instance-1

As capacidades informam o acesso, os grupos disponíveis e o intervalo de atualização. history: null significa que a capacidade fornece somente o snapshot mais recente, sem retenção de séries ou gráficos históricos.

{
  "data": {
    "access": "snapshot",
    "groups": [
      "resources",
      "connections",
      "activity",
      "cache",
      "storage",
      "locks",
      "latency",
      "reliability"
    ],
    "refresh_seconds": 60,
    "history": null
  }
}

Envelope do snapshot

A resposta preserva a rota existente e retorna um envelope versionado por instância. Este exemplo PostgreSQL contém valores representativos; campos condicionais podem ser null.

{
  "status": "success",
  "data": {
    "schema_version": 1,
    "project_id": "507f1f77bcf86cd799439011",
    "instance": "instance-1",
    "type": "postgresql",
    "observed_at": "2026-08-29T12:00:00.000Z",
    "collected_at": "2026-08-29T12:00:01.000Z",
    "availability": "available",
    "resource": {
      "cpu_usage_cores": 0.42,
      "memory_usage_bytes": 268435456,
      "storage_used_bytes": 2147483648,
      "storage_capacity_bytes": 10737418240
    },
    "native": {
      "connections": {
        "current": 12,
        "max": 100,
        "utilization_ratio": 0.12,
        "active": 3,
        "idle": 9
      },
      "activity": {
        "commits_total": 24000,
        "rollbacks_total": 120,
        "transactions_per_second": 18.5,
        "rows_returned_total": 980000,
        "rows_fetched_total": 310000,
        "rows_written_total": 42000,
        "temp_files_total": 7,
        "temp_bytes_total": 1048576
      },
      "cache": {
        "buffer_hits_total": 950000,
        "buffer_reads_total": 50000,
        "hit_ratio": 0.95
      },
      "storage": {
        "database_size_bytes": 1610612736
      },
      "locks": {
        "waiting_total": 1,
        "deadlocks_total": 2
      },
      "latency": {
        "average_query_latency_ms": null,
        "slow_queries_total": null
      },
      "reliability": {
        "up": true,
        "uptime_seconds": 86400,
        "wal_bytes_total": 734003200,
        "wal_bytes_per_second": 32768,
        "checkpoints_total": 36,
        "checkpoint_buffers_total": 4200,
        "role": "primary",
        "replicas_available": 1,
        "replicas_expected": 1,
        "lag_seconds": 0.4,
        "lag_bytes": 4096
      }
    }
  }
}

schema_version identifica a versão do envelope.
type discrimina postgresql e mariadb; cada projeto recebe somente os grupos da própria engine.
observed_at é o momento em que os valores foram observados na instância.
collected_at é o momento em que o snapshot ficou disponível para consulta.
resource contém CPU em núcleos e memória/armazenamento em bytes.
native contém somente campos de produto definidos para a engine.

Campos PostgreSQL

Grupo	Campos
Conexões	`current`, `max`, `utilization_ratio`, `active`, `idle`
Atividade e transações	`commits_total`, `rollbacks_total`, `transactions_per_second`, `rows_returned_total`, `rows_fetched_total`, `rows_written_total`, `temp_files_total`, `temp_bytes_total`
Cache de leitura	`buffer_hits_total`, `buffer_reads_total`, `hit_ratio`
Armazenamento	`database_size_bytes`
Locks	`waiting_total`, `deadlocks_total`
Latência	`average_query_latency_ms`, `slow_queries_total`, quando disponíveis
Saúde, WAL e checkpoints	`up`, `uptime_seconds`, `wal_bytes_total`, `wal_bytes_per_second`, `checkpoints_total`, `checkpoint_buffers_total`
Replicação	`role`, `replicas_available`, `replicas_expected`, `lag_seconds`, `lag_bytes`

Campos MariaDB

Grupo	Campos
Conexões e threads	`current`, `max`, `utilization_ratio`, `threads_connected`, `threads_running`, `aborted_connects_total`
Atividade	`queries_total`, `questions_total`, `queries_per_second`, `bytes_received_per_second`, `bytes_sent_per_second`, `slow_queries_total`
Cache de leitura	`buffer_pool_size_bytes`, `buffer_pool_data_bytes`, `buffer_pool_free_bytes`, `buffer_pool_dirty_pages`, `buffer_pool_reads_total`, `buffer_pool_read_requests_total`, `hit_ratio`
Redo e I/O	`log_writes_total`, `log_waits_total`, `fsyncs_total`, `io_per_second`, quando disponíveis
Armazenamento	`database_size_bytes`
Locks	`row_lock_waits_total`, `row_lock_time_ms_total`, `current_waits`, `deadlocks_total`
Latência	`average_query_latency_ms`, quando disponível
Saúde	`up`, `uptime_seconds`
Replicação	`status`, `replicas_available`, `replicas_expected`, `lag_seconds`

No MariaDB, threads_connected representa sessões abertas; threads_running representa threads executando trabalho no momento da amostra. Os dois campos não são equivalentes.

Contadores, taxas, razões e unidades

Campos _total são contadores acumulados desde o último reinício ou reset.
Campos _per_second são taxas calculadas entre duas amostras válidas.
Depois de um reset, a taxa relacionada retorna null até existir uma nova base válida; nunca retorna um valor negativo.
Campos _ratio são frações entre 0 e 1.
Bytes são inteiros; latência usa milissegundos; atraso usa segundos ou bytes conforme o nome do campo; CPU usa núcleos.
O cache de leitura é o cache interno da engine e não representa o cache do sistema operacional.

Disponibilidade e campos anuláveis

availability pode ser:

available: a amostra foi concluída;
partial: somente parte dos grupos ou campos foi obtida;
stale: uma amostra válida anterior é retornada com seus horários originais;
unavailable: não há amostra válida para apresentar.

Um campo ausente, não suportado ou que não pôde ser calculado retorna null, nunca zero sintético. O snapshot apresenta valores agregados e não inclui texto nem parâmetros de consultas.

Métricas nativas de Analytics

Projetos Analytics nos planos analytics-starter, analytics-production e analytics-enterprise também oferecem snapshot pelas mesmas rotas, com os grupos resources, connections, activity, storage e reliability, atualização a cada 60 segundos e sem histórico. O parâmetro instance é obrigatório; use os valores de GET /v1/project/:id/instances. No analytics-sandbox, access é none e a rota de métricas responde 402.

Obter Logs do Projeto

Retorna os logs do projeto em execução.

GET /v1/project/:id/logs

Disponível em todos os planos. Exige project.logs.read. Limite de requisições: 200 por minuto (contado por IP de origem). Somente aplicações HTTP têm logs por esta rota; os demais tipos de projeto respondem 400. Para Jobs agendados, use os logs por execução em Jobs agendados.

Parâmetros de Path

Parâmetro	Tipo	Descrição
`id`	string	ID do projeto

Parâmetros de Query (opcionais)

Parâmetro	Tipo	Descrição
`instance`	string	Identificador da instância para retornar logs de apenas uma instância

Resposta

{
  "status": "success",
  "message": "get instances logs with success",
  "data": [
    "2024-01-15T10:30:00Z Starting application...\n2024-01-15T10:30:01Z Server listening on port 3000",
    "2024-01-15T10:30:05Z GET /health 200"
  ]
}

Quando instance é enviado, data pode ser uma string única com os logs da instância solicitada.

Erros (métricas e logs)

Status	Quando ocorre
`400`	`instance` é obrigatório ou inválido (métricas de Analytics, Key-Value, Cache e Queue); a instância informada não existe (logs); ou o projeto não é uma aplicação HTTP (logs)
`402`	O plano do projeto não inclui métricas (os logs estão disponíveis em todos os planos)
`404`	Projeto ou instância não encontrados

Exemplos

Obter Métricas

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/metrics" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id"

Obter Logs

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/logs?instance=abc" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id"

Python

import requests

API_KEY = "sua-api-key"
ORGANIZATION_ID = "sua-organization-id"
PROJECT_ID = "507f1f77bcf86cd799439011"

headers = {"x-api-key": API_KEY, "x-organization-id": ORGANIZATION_ID}

# Obter métricas
metrics = requests.get(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/metrics",
    headers=headers
).json()
print(metrics)

# Obter logs
logs = requests.get(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/logs",
    params={"instance": "abc"},
    headers=headers
).json()
print(logs)

Nessa página