Sincronize métricas externas com o rollfuse usando conectores

Um conector é uma configuração dentro de um projeto que busca dados de uma fonte HTTP externa que você já mantém, periodicamente, e registra cada entrada como uma Observation associada a uma definição de métrica e um ambiente dentro do rollfuse. É isso que alimenta guardrails e métricas de rollout com números que os seus próprios sistemas já produzem, em vez de exigir que cada serviço envie dados diretamente para o rollfuse. Este guia mostra como configurar um conector, pré-visualizar o mapeamento antes de salvar qualquer coisa, e forçar uma sincronização sob demanda.

Pré-visualizando o mapeamento antes de salvar

Antes de criar um conector, confirme que o mapeamento realmente resolve contra a sua fonte ao vivo com POST /v1/projects/{project_id}/connectors/preview. Isso busca source_url uma vez, aplica o mapeamento que você passou, e nunca persiste um conector, uma versão de contract template ou uma observation:

const response = await fetch(
  `https://api.rollfuse.com/v1/projects/${projectId}/connectors/preview`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      source_url: "https://billing.example.com/metrics",
      secret: "s3cr3t",
      root_path: ".",
      value_field: "amount",
      observed_at_field: "observed_at",
      observed_at_format: "rfc3339",
    }),
  },
);

const preview = await response.json();

if (preview.error) {
  console.error("mapeamento não resolveu:", preview.error, preview.raw_response);
} else {
  console.log("observations resolvidas:", preview.observations);
}

raw_response está sempre presente, então um mapeamento que falhou ainda mostra exatamente o que a fonte retornou, o que geralmente já é suficiente para achar o nome de campo errado.

Criando o conector

Depois que o mapeamento resolver, crie o conector com POST /v1/projects/{project_id}/connectors, apontando para a definição de métrica e o ambiente que ele deve alimentar:

const response = await fetch(
  `https://api.rollfuse.com/v1/projects/${projectId}/connectors`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Métricas de billing",
      template_id: templateId,
      source_url: "https://billing.example.com/metrics",
      secret: "s3cr3t",
      metric_definition_id: metricDefinitionId,
      environment_id: environmentId,
    }),
  },
);

const connector = await response.json();
console.log(connector.id, connector.status);

A resposta é o único momento em que o segredo de leitura em texto puro é retornado; um GET posterior no conector nunca o inclui de volta. O conector fica fixado, desde a criação, em uma versão aprovada específica do contract template, então aprovar uma versão mais nova do template depois nunca muda silenciosamente o comportamento deste conector.

Forçando uma sincronização sob demanda

Conectores buscam dados no próprio ritmo agendado, mas você pode disparar uma sincronização imediata com POST /v1/connectors/{connector_id}/sync, útil logo depois de criar um conector ou ao depurar uma mudança de mapeamento:

const response = await fetch(
  `https://api.rollfuse.com/v1/connectors/${connector.id}/sync`,
  { method: "POST", headers: { Authorization: `Bearer ${token}` } },
);

if (!response.ok) {
  const error = await response.json();
  console.error("sincronização falhou:", error);
} else {
  const synced = await response.json();
  console.log("última sincronização ok, status:", synced.status);
}

Uma sincronização que falha (fonte inacessível, resposta não 2xx, corpo que não dá pra interpretar, ou uma falha ao gravar o dado) não registra nenhuma observation, e deixa o estado de última sincronização com falha visível no próximo GET do conector, então uma fonte com problema nunca grava dado parcial silenciosamente no seu histórico de métrica.

Desativando um conector

Desative um conector em vez de apagá-lo se precisar parar de buscar de uma fonte sem perder a configuração ou o histórico de sincronizações:

await fetch(`https://api.rollfuse.com/v1/connectors/${connector.id}/disable`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});

Um conector desativado rejeita novas solicitações de sincronização, mas sua configuração e histórico continuam intactos.

Configuração específica de cada ferramenta

O source_url de um conector pode apontar para qualquer coisa que devolva dados HTTP sob demanda, incluindo um exporter ou API de uma ferramenta de observabilidade que você já usa. Para a referência de como extrair dados de métrica de uma ferramenta específica em primeiro lugar, veja as páginas de integração do Prometheus, Grafana e Datadog, em vez de duplicar essa configuração aqui.