API de leitura
Consulte os eventos de um projeto a partir de um script, com uma chave de leitura.
O painel é uma forma de ler os eventos. A API de leitura é a outra: os mesmos filtros, em JSON, para um script, um notebook, um job agendado ou um agente.
Autenticação
Na página API keys do projeto, escolha New key e defina What it can do como Read
events. A chave começa com lyr_read_ e é mostrada uma única vez. Envie-a como bearer token
para https://app.lyrelog.com. Os exemplos abaixo a guardam numa variável do shell:
export LYRELOG_READ_KEY=lyr_read_...
curl -s https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY"Uma chave de leitura vê todos os eventos do seu projeto e nada mais. Mantenha-a num servidor:
qualquer pessoa que a tenha pode ler os eventos dos seus usuários. Uma chave Full access
também lê; uma chave de ingestão não pode (403).
Listar eventos
GET /v1/events responde com os eventos mais novos primeiro, 100 de cada vez, das últimas 24
horas, a menos que você diga outra coisa.
| Parâmetro | Significado |
|---|---|
from, to | Milissegundos Unix. Padrão: as últimas 24 horas. |
level | Um ou mais níveis, separados por vírgula: error,critical |
category, message | A área e o nome do evento. Vários valores com |, ! na frente para excluir: message=!http_request_served |
user, session, install | Um id |
env, platform | production, ios... Sem eles, todos os ambientes e plataformas. |
version, os, device, locale | A versão do app, a versão do sistema operacional (27.2.0), o modelo do dispositivo e a localidade |
country | Onde a pessoa está: o país do endereço de onde vieram os eventos, senão a região da localidade do dispositivo (es_ES é ES) |
verified | Como um evento é verificado: server (enviado com uma chave de servidor), app_attest (enviado pelo seu app da Apple, comprovado com App Attest), key_attestation (enviado pelo seu app Android, comprovado com Key Attestation), none (não verificado) |
attr | path:value num atributo, ou path!:value para excluir. Repita para usar vários. |
q | Texto na mensagem ou na área (sem diferenciar maiúsculas), ou um id exato de evento, usuário, sessão ou instalação. Os atributos não entram na busca: use attr. |
limit | De 1 a 1000, padrão 100 |
order | asc para os mais antigos primeiro |
cursor | O next_cursor da resposta anterior, para a próxima página |
category, message, user, session, install, env, platform, version, os,
device, locale, country e verified aceitam vários valores separados por | ("é algum
destes"), ou uma lista com ! na frente ("não é"): os=26.4|27.2.0, platform=!web. Um valor
de attr também aceita |, e é excluído com ! depois do caminho: attr=plan!:free|trial. Os
modelos de dispositivo contêm vírgulas (iPhone18,1), e é por isso que o separador é |.
# Errors on iOS in production in the last hour
curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" \
--data-urlencode "platform=ios" \
--data-urlencode "env=production" \
--data-urlencode "from=$(( ($(date +%s) - 3600) * 1000 ))"A resposta é {"events": [...], "next_cursor": "..."}; next_cursor é null na última página.
Cada evento tem event_id, ts (milissegundos Unix), level, category, message, user_id,
install_id, session_id e attrs, além dos campos de resource (app_id, app_version,
app_build, os_name, os_version, device_model, locale, environment, platform),
country e verified_by: "server" quando o evento veio com uma chave de servidor,
"app_attest" quando o seu app da Apple se comprovou com App Attest, "key_attestation"
quando o seu app Android se comprovou com Key Attestation, "" quando não é verificado (veja Eventos verificados). A lista deixa o payload de fora: peça um
evento específico para obtê-lo.
Todas as páginas
Um cursor só continua a consulta de onde veio: envie os mesmos filtros junto com ele. Sem from
e to, a janela anda com o relógio, então fixe esses valores quando for ler várias páginas. Isto
lê todos os erros dos últimos 7 dias, dos mais antigos para os mais novos, 1000 de cada vez
(precisa de jq):
FROM=$(( ($(date +%s) - 7*86400) * 1000 )); TO=$(( $(date +%s) * 1000 )); CURSOR=""
while :; do
PAGE=$(curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" --data-urlencode "order=asc" --data-urlencode "limit=1000" \
--data-urlencode "from=$FROM" --data-urlencode "to=$TO" ${CURSOR:+--data-urlencode "cursor=$CURSOR"})
echo "$PAGE" | jq -c '.events[]'
CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty'); [ -z "$CURSOR" ] && break
doneUm evento
GET /v1/events/{event_id}?ts={ts} responde com um evento, com o payload inteiro, como
{"event": {...}}. Passe o ts (milissegundos Unix) que a lista retornou: os eventos são guardados
por tempo, então só o id obrigaria a procurar em todos eles.
curl -s -G "https://app.lyrelog.com/v1/events/6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f" \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "ts=1794996000123"{"event":{"event_id":"6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f","ts":1794996000123,"level":"error","category":"checkout","message":"payment_declined","user_id":"user-1","install_id":"","session_id":"2f9a...","app_id":"com.example.app","app_version":"2.0","app_build":"202611181200","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,1","locale":"es_ES","country":"ES","environment":"production","platform":"ios","verified_by":"","attrs":{"code":51},"payload":{"response":"..."}}}Um campo que o app não enviou é uma string vazia. payload fica de fora quando o evento não tem
um.
Limites e erros
| Status | Significado |
|---|---|
400 | Um parâmetro está errado; o corpo diz qual. Por exemplo: from que não é anterior a to, um intervalo de mais de 400 dias, mais de 8 filtros attr, mais de 100 valores num filtro, um nível desconhecido, limit fora de 1 a 1000, um cursor inválido |
401 | Nenhuma chave, ou uma desconhecida ou revogada |
403 | A chave não pode ler (uma chave de ingestão) |
404 | Nenhum evento com esse id e esse ts |
429 | Mais de 120 requisições por minuto para esta chave (Retry-After: 60); o projeto já está rodando 4 consultas ao mesmo tempo, somando o painel e as suas chaves (Retry-After: 2); ou mais de 60 chaves desconhecidas vindas do seu endereço em 15 minutos |
500 | {"error":"something went wrong on the server"}. Uma consulta que leva mais de 15 segundos termina assim: reduza o intervalo ou adicione filtros |
Um erro responde {"error": "..."}. Depois de um 429, espere o Retry-After antes de tentar de
novo.
As respostas nunca vão para cache (Cache-Control: no-store). A API não tem headers de CORS de
propósito: uma chave de leitura não deve ficar num navegador.