Pular para o conteúdo principal
Busque linhas de log com a API pública (V2). Esta é a forma de consultar logs programaticamente, incluindo dados de log estruturados (JSON). A API GraphQL não expõe linhas de log.
Se você está construindo um agente ou assistente de IA, o AppSignal MCP expõe a busca de logs e outros dados de monitoramento diretamente aos agentes, sem precisar chamar esta API por conta própria.

Encontrando seus IDs de site e fonte

Uma busca em logs precisa de um site_id e um ou mais source_ids. Ambos aparecem na URL de uma fonte de log na AppSignal. Abra uma fonte de log e leia-os no path:

Buscar linhas de log

Para todos os campos da requisição e da resposta, veja a referência Buscar linhas de log. A requisição recebe um site_id, os source_ids a buscar, uma query e um objeto pagination. Inclua pelo menos um ID de fonte: uma lista source_ids vazia não retorna nenhuma linha. Uma query vazia corresponde a todas as linhas. Veja linguagem de query. from tem como padrão o início da sua retenção de logs, e to tem como padrão o momento atual. pagination recebe per_page (número), order (ASC ou DESC) e um cursor com um time e um id. Defina ambos como null para a primeira página. Para buscar a próxima página, envie o timestamp e o id da última linha recebida como cursor.time e cursor.id. Sem o id, as linhas que compartilham esse timestamp são ignoradas.

Exemplo de requisição

O endpoint retorna um array de linhas de log. Os dados estruturados de cada linha ficam no campo json, como uma string codificada em JSON. Para contar linhas ou calcular a média de um campo, consulte as métricas de log.
Campos estruturados como status_code, path ou detail vivem no campo json. Consulte-os pela chave exata como ela aparece no JSON do seu log (por exemplo, status_code=401 ou detail.message:"required").

Linguagem de query

A string query suporta lógica booleana sobre campos da linha de log e o corpo json estruturado.

Operadores

Operadores de string (=, !=, :, !:) comparam ambos os lados como strings. Operadores numéricos (>, >=, <, <=) convertem ambos os lados em número; se um valor não puder ser parseado como número, aquela linha de log é ignorada.

Combinando expressões

  • AND / OR: severity=error AND hostname:web, ou severity=info OR severity=warn.
  • AND implícito: um espaço entre expressões significa AND. severity=error hostname:web é o mesmo que severity=error AND hostname:web.
  • Aninhamento com parênteses: message:"API request" AND (severity=info OR severity=warn).
  • Precedência: AND tem precedência maior que OR.
Qualquer operador pode ser usado dentro de um grupo OR, não só igualdade — por exemplo, message:"API request" AND (user.id>1000 OR user.email:"example.com").

Campos

Dada uma linha de log com este corpo JSON:
  • Campos base: message, severity, hostname e group correspondem aos campos de nível superior da linha de log.
  • JSON aninhado: use notação de ponto para alcançar dentro do corpo json, como status_code=200 ou user.id=12345.
  • Arrays JSON: indexe elementos do array, como user.roles.0=admin.
  • Pontos escapados: para corresponder a um ponto literal em um nome de chave, escape-o. user.location\.country=US corresponde à chave location.country dentro de user, em vez de um objeto country aninhado.
  • Campo padrão: um termo isolado sem campo corresponde a message com o operador contains. timeout é o mesmo que message:timeout.
Referencie um campo diretamente pelo nome no JSON do seu log, sem sufixo de tipo. Veja sintaxe de query legada se você tem queries mais antigas.

Aspas em valores

Envolva valores que contêm espaços ou parênteses entre aspas duplas. Caso contrário, o espaço divide o valor em expressões separadas unidas por AND implícito.
Apenas aspas duplas são reconhecidas. Dentro de um valor entre aspas, escape uma aspa com \" e uma barra invertida com \\. Por exemplo, message:"value with \"quotes\"" corresponde ao texto value with "quotes".

Sintaxe de query legada

Queries mais antigas armazenavam atributos como campos tipados, então precisavam prefixar attributes., adicionar um sufixo de tipo (_string, _int) e usar uma lista [ ] para múltiplos valores. A linguagem de query atual remove todas as três — referencie campos diretamente e use OR em vez de uma lista:
A API não lê mais a sintaxe legada, e também não a rejeita mais. attributes. agora é um caminho comum dentro do JSON do seu log. Assim, attributes.user_id_int=12345 procura uma chave user_id_int dentro de um objeto attributes. Um filtro na antiga forma attributes. não corresponde a nada, em vez de retornar um erro. Se seus logs contêm um objeto attributes, você pode filtrar pelos campos dele, como attributes.user_id=12345.