Consultando logs

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:

https://appsignal.com/<organization>/sites/<SITE_ID>/logs/sources/<SOURCE_ID>

Buscar linhas de log

POST /api/v2/logs/lines

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`site_id`	string	Sim	Site a ser consultado.
`source_ids`	string[]	Sim	IDs de fonte de log a serem buscados. Pelo menos um é obrigatório.
`query`	string	Sim	String de query que filtra linhas de log. Veja linguagem de query.
`use_expressions`	boolean	Não	Quando `true`, parseia `query` com a linguagem de query baseada em expressões.
`from`	string (ISO 8601)	Não	Início do intervalo de tempo. Padrão é o limite inferior de retenção.
`to`	string (ISO 8601)	Não	Fim do intervalo de tempo. Padrão é o horário atual.
`pagination`	object	Sim	Cursor e direção da paginação (veja a seção a seguir).

Defina use_expressions como true para usar a linguagem de query baseada em expressões documentada nesta página. pagination recebe per_page (número), order (ASC ou DESC) e um cursor com um campo time (um timestamp ISO 8601, ou null na primeira página). Para buscar a próxima página, envie o timestamp da última linha recebida como cursor.time da próxima requisição.

Exemplo de requisição

curl --request POST \
  --url "https://appsignal.com/api/v2/logs/lines" \
  --header "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json

{
  "site_id": "YOUR-SITE-ID",
  "source_ids": ["YOUR-LOG-SOURCE-ID"],
  "query": "severity=error status_code=401",
  "use_expressions": true,
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T23:59:59Z",
  "pagination": {
    "per_page": 100,
    "order": "DESC",
    "cursor": { "time": null }
  }
}

Resposta

O endpoint retorna um array de linhas de log. Cada linha inclui estes campos:

Campo	Tipo	Descrição
`id`	string	Identificador da linha de log.
`timestamp`	string (ISO 8601)	Quando a linha de log foi registrada.
`source_id`	string	Fonte de log a que a linha pertence.
`severity`	string	Nível de severidade, como `info` ou `error`.
`message`	string	O corpo da mensagem de log.
`hostname`	string	Host que produziu a linha.
`group`	string	Grupo de log.
`json`	string	O corpo estruturado (JSON) bruto da linha de log, quando disponível.
`attributes`	object	Atributos chave-valor tipados legados. Sendo descontinuado — prefira `json`.

Campos estruturados como status_code, path ou detail vivem no campo json, não em attributes. Consulte-os pela chave exata como aparece no JSON do seu log (por exemplo, status_code=401 ou detail.message:"required").

Linguagem de query

Quando use_expressions é true, a string query suporta lógica booleana sobre campos da linha de log e o corpo json estruturado.

Operadores

Operador	Nome	Comportamento
`=`	Igual	Correspondência exata.
`!=`	Diferente	Não correspondência exata.
`:`	Contém	Correspondência por substring.
`!:`	Não contém	Não correspondência por substring.
`>`	Maior que	Comparação numérica.
`>=`	Maior ou igual	Comparação numérica.
`<`	Menor que	Comparação numérica.
`<=`	Menor ou igual	Comparação numérica.

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:

{
  "message": "API request completed",
  "severity": "info",
  "duration": 156.7,
  "status_code": 200,
  "user": {
    "id": 12345,
    "roles": ["admin", "developer"],
    "location.country": "US"
  }
}

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.

Você não precisa prefixar com attributes. nem adicionar um sufixo de tipo para consultar um campo — referencie-o diretamente pelo nome. 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.

message:"hello world"           matches message containing "hello world"
message:hello world             parsed as message:hello AND message:world
severity=error message:"oh no"  severity equals error AND message contains "oh no"

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:

message:"API request" attributes.user_id_int=12345 severity=[info, warn]

message:"API request" user.id=12345 (severity=info OR severity=warn)

Uma query que ainda usa a sintaxe legada retorna 422 com o slug de erro legacy_log_query_syntax.

AppSignal API

Servidor MCP

AppSignal CLI

Encontrando seus IDs de site e fonte

Buscar linhas de log

Corpo da requisição

Exemplo de requisição

Resposta

Linguagem de query

Operadores

Combinando expressões

Campos

Aspas em valores

Sintaxe de query legada

​Encontrando seus IDs de site e fonte

​Buscar linhas de log

​Corpo da requisição

​Exemplo de requisição

​Resposta

​Linguagem de query

​Operadores

​Combinando expressões

​Campos

​Aspas em valores

​Sintaxe de query legada

Encontrando seus IDs de site e fonte

Buscar linhas de log

Corpo da requisição

Exemplo de requisição

Resposta

Linguagem de query

Operadores

Combinando expressões

Campos

Aspas em valores

Sintaxe de query legada