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).

GET /v1/project/:id/metrics

Parâmetros de Path

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

Headers

Header	Obrigatório	Descrição
`x-api-key`	Sim	API Key do projeto
`x-organization-id`	Sim	Organização ativa do projeto

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.

O campo uptime representa o tempo de atividade atual da instância ou do container retornado 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 tiers valkey_realtime, valkey_premium e valkey_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 em planos Premium+ usam os mesmos endpoints estáveis. 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.

Obter Logs do Projeto

Retorna os logs do projeto em execução.

GET /project/:id/logs

Parâmetros de Path

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

Parâmetros de Query (opcionais)

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

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.

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