API HTTP

Base, formatos e versão

• Base: https://tracker-api.fortground.com.br. Todas as rotas começam com /v1.
• JSON em UTF-8. Datas em ISO 8601 (as respostas vêm em UTC, com Z); durações em milissegundos (durationMs, decimais aceitos).
• A referência gerada do código está em tracker-api.fortground.com.br/docs. Ela lista também as rotas internas do painel e ainda não descreve o token Bearer nem a maioria das respostas; esta página é a referência para integrações.

Autenticação

Chave de projeto não lê nada e token não envia telemetria: a API recusa um fgt_ no header de chave e uma chave no Bearer. Como obter e quando usar cada uma: Chaves e tokens.

Rotas públicas de integração

Estas são as rotas que esta documentação cobre para integrações. Todas foram conferidas no código da API; as que têm exemplo nesta página foram executadas.

Ingestão (chave de projeto)

Leitura e automação (token pessoal)

Além da permissão do token, a pessoa dona do token precisa ser membro ativo do projeto; onde aparece owner/admin, o papel dela no projeto também conta.

Ingestão de spans

POST /v1/ingest recebe traces agrupados. Cada span:

Resposta parcial

Erro de estrutura ou de tipo (campo obrigatório faltando, data como número) recusa o lote inteiro com 400 e nada é gravado. Um valor fora da faixa recusa só aquele span: a resposta é 202, com rejected e o motivo em errors[] (até 100 itens):

{"accepted":0,"rejected":1,"duplicates":0,"adjusted":0,"errors":[{"traceId":"cb5991b1fef1bbd8b000a0a95bdc8495","spanId":"d57234e92bc131c3","reason":"started_at_too_old"}],"issuesDetected":0,"live":false,"liveIntervalMs":60000}

Motivos: started_at_too_old, started_at_in_future, ended_at_in_future, status_code_out_of_range, duration_out_of_range, attributes_too_large, error_too_large e public_key_not_allowed. Span recusado não deve ser reenviado igual.

Idempotência

Um span é identificado por projeto, traceId e spanId. Reenviar o mesmo span responde accepted: 1, duplicates: 1 e não grava de novo, então é seguro repetir um lote depois de timeout ou 5xx. Logs, pageviews e agregados de infra usam o id do emissor (eventId, event_id, id, de 8 a 128 caracteres) e são deduplicados por 48 horas; sem id, cada envio grava.

Exemplos com curl

Variáveis usadas em todos os exemplos:

export FG_TRACKER_URL=https://tracker-api.fortground.com.br
export FG_TRACKER_KEY=fgsk_<chave_de_servidor>        # ingestão do servidor
export FG_TRACKER_TOKEN=fgt_<token_pessoal>           # leitura e automação
export FG_TRACKER_PROJECT_ID=<uuid_do_projeto>        # aparece na URL do painel: ?project=…

Enviar um span

TRACE_ID=$(openssl rand -hex 16)
SPAN_ID=$(openssl rand -hex 8)
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -sS -X POST "$FG_TRACKER_URL/v1/ingest" \
  -H 'content-type: application/json' \
  -H "x-fg-tracker-key: $FG_TRACKER_KEY" \
  -d '{"traces":[{"traceId":"'"$TRACE_ID"'","spans":[{
        "spanId":"'"$SPAN_ID"'","parentSpanId":null,"kind":"http.server",
        "name":"GET /hello/:name","method":"GET","route":"/hello/:name","statusCode":200,
        "startedAt":"'"$NOW"'","endedAt":"'"$NOW"'","durationMs":12,
        "attributes":{"serviceName":"checkout-api","environment":"development"},"error":null}]}]}'

{"accepted":1,"rejected":0,"duplicates":0,"adjusted":0,"errors":[],"issuesDetected":0,"live":false,"liveIntervalMs":60000}

Ler o trace enviado

curl -sS "$FG_TRACKER_URL/v1/projects/$FG_TRACKER_PROJECT_ID/traces/$TRACE_ID" \
  -H "authorization: Bearer $FG_TRACKER_TOKEN"

A resposta traz o trace com spans[] (cada um com offsetMs, depth, service e environment). A lista recente:

curl -sS "$FG_TRACKER_URL/v1/projects/$FG_TRACKER_PROJECT_ID/traces?range=1h&limit=5" \
  -H "authorization: Bearer $FG_TRACKER_TOKEN"

Saúde da ingestão

curl -sS "$FG_TRACKER_URL/v1/projects/$FG_TRACKER_PROJECT_ID/ingest-health?range=1h" \
  -H "authorization: Bearer $FG_TRACKER_TOKEN"

Mostra lastReceivedAt, o atraso entre o fim do span e a gravação (lagMs), quantos spans foram aceitos, duplicados e recusados por motivo, com a última recusa. É o primeiro lugar para olhar quando nada aparece no painel.

Logs

curl -sS -X POST "$FG_TRACKER_URL/v1/logs" \
  -H 'content-type: application/json' \
  -H "x-fg-tracker-key: $FG_TRACKER_KEY" \
  -d '{"logs":[{"eventId":"'"$(openssl rand -hex 16)"'","level":"info","service":"checkout-api",
        "env":"development","message":"pedido criado","context":{"orderId":42}}]}'

{"accepted":1,"duplicates":0}

Até 500 linhas por lote; level é trace, debug, info, warn, error ou fatal; ts é opcional (padrão: agora); mensagem até 32 KB e context até 8 KB.

Release

curl -sS -X POST "$FG_TRACKER_URL/v1/releases" \
  -H 'content-type: application/json' \
  -H "x-fg-tracker-key: $FG_TRACKER_KEY" \
  -d '{"version":"checkout-api@1.4.0","environment":"development","commitSha":"<sha_do_commit>"}'

Responde 201 com a release. Repetir com a mesma version atualiza a existente.

Check-in de job

curl -sS "$FG_TRACKER_URL/v1/monitors/backup-diario/ping?status=ok&environment=development" \
  -H "x-fg-tracker-key: $FG_TRACKER_KEY"

O primeiro check-in cria o monitor do slug no ambiente informado. status aceita ok, fail e in_progress. A chave de servidor vai no header; em ?key= ela é recusada.

Limites, 413 e 429

• Corpo JSON até 2 MiB depois de descomprimir (Content-Encoding: gzip é aceito). Acima disso: 413; divida o lote. Os SDKs mandam no máximo 1,5 MiB e 1000 spans por lote.
• Por lote: até 2000 traces, 5000 spans por trace, 500 pageviews e 500 agregados de infra.
• A API pode limitar a vazão de ingestão por projeto. Quando isso acontece: 429 com Retry-After (segundos) e code: INGEST_QUOTA_EXCEEDED, sem gravar nada; reenvie o mesmo lote depois do prazo. Um lote maior que a rajada permitida recebe 413 com code: INGEST_BATCH_EXCEEDS_QUOTA. Os SDKs a partir de fg-tracker-sdk 0.10.0, fg-tracker-browser 0.3.0 e fg-tracker-lambda-extension 0.2.0 já tratam os dois casos.
• Spans ficam 14 dias, logs 7 dias; o histórico por hora de cada rota, até 400 dias.

Leitura: janelas, filtros e paginação

• Janela: range = 15m, 1h, 6h, 24h (padrão), 7d ou 30d; ou from/to em ISO 8601, com no máximo 31 dias. Com janela absoluta, a resposta traz o header x-fg-tracker-window com a janela aplicada.
• Filtros de métricas e traces: rootKind = http (padrão), custom (jobs), browser ou all; service e env comparam por igualdade exata com o span raiz.
• O filtro de ambiente se chama env em métricas, traces e logs, e environment em monitores, releases e SLOs.
• Paginação por cursor: traces (padrão 50, máximo 200), logs (100/200), alerts/events (50/200) e issues (50/200). Passe o nextCursor da resposta em cursor; null é o fim. Sem limit nem cursor, issues devolve o array completo (formato antigo).
• Listas sem paginação: projetos, endpoints, monitores, membros, regras de alerta, SLOs e source maps.

Erros

Erros simples vêm como { statusCode, message, error }. Erros com code trazem o code e a message (e, às vezes, campos extras), sem statusCode; use o status HTTP da resposta.

{"code":"TOKEN_SCOPE_INSUFFICIENT","message":"Falta a permissão \"Chave de ingestão: ler\" neste token. Edite as permissões em Conta → Tokens de acesso","requiredScope":"ingest_key:read","requiredPermission":"Chave de ingestão: ler","sessionOnly":false}

Rotas internas e estabilidade

A API ainda não tem uma política de versionamento publicada. O prefixo /v1 e as rotas desta página são as que integrações devem usar; mudanças nelas aparecem nesta documentação. Não construa integrações sobre as demais rotas que aparecem na referência OpenAPI:

• Rotas do painel: login, cadastro, MFA, sessões, criação de tokens, convites, WhatsApp, IA em streaming e o diagrama ao vivo. Exigem a sessão do painel e podem mudar com ele.
• Rotas de operação: /v1/internal/*, o tick de alertas, webhooks de eventos da AWS e o relatório do executor de teste de carga. Exigem segredos da operação e não são para clientes.
• Infraestrutura AWS e testes de carga (/v1/projects/:id/infra/*, /v1/projects/:id/loadtest/*): aceitam token, mas são usadas pelo painel e pelo MCP e não estão documentadas aqui. Use pelo MCP.