Finding your site and source IDs
A log search needs asite_id and one or more source_ids. Both appear in the
URL of a log source in AppSignal. Open a log source and read them from the path:
Search log lines
site_id, the source_ids to search, a query, and a
pagination object. Include at least one source ID: an empty source_ids
list returns no lines. An empty query matches every line. See query
language. from defaults to the start of your log retention,
and to defaults to now.
pagination takes per_page (number), order (ASC or DESC), and a
cursor with a time and an id. Set both to null for the first page. To
fetch the next page, send the timestamp and id of the last line you
received as cursor.time and cursor.id. Without the id, lines that share
that timestamp are skipped.
Example request
json field, as a JSON-encoded string. To count lines or average a field
instead, query log metrics.
Structured fields such as
status_code, path, or detail live in the json
field. Query them by their exact key as it appears in your log’s JSON (for
example, status_code=401 or detail.message:"required").Query language
Thequery string supports boolean logic over log line fields and the
structured json body.
Operators
String operators (
=, !=, :, !:) compare both sides as strings. Numeric
operators (>, >=, <, <=) cast both sides to a number; if a value cannot be
parsed as a number, that log line is skipped.
Combining expressions
- AND / OR:
severity=error AND hostname:web, orseverity=info OR severity=warn. - Implicit AND: a space between expressions means AND.
severity=error hostname:webis the same asseverity=error AND hostname:web. - Nesting with parentheses:
message:"API request" AND (severity=info OR severity=warn). - Precedence: AND binds tighter than OR.
OR group, not only equality — for example,
message:"API request" AND (user.id>1000 OR user.email:"example.com").
Fields
Given a log line with this JSON body:- Base fields:
message,severity,hostname, andgroupmatch the log line’s top-level fields. - Nested JSON: use dot notation to reach into the
jsonbody, such asstatus_code=200oruser.id=12345. - JSON arrays: index array elements, such as
user.roles.0=admin. - Escaped dots: to match a literal dot in a key name, escape it.
user.location\.country=USmatches the keylocation.countryinsideuser, rather than a nestedcountryobject. - Default field: a bare term with no field matches
messagewith thecontainsoperator.timeoutis the same asmessage:timeout.
Quoting values
Wrap values that contain spaces or parentheses in double quotes. Otherwise the space splits the value into separate expressions joined by implicit AND.\" and a backslash with \\. For example, message:"value with \"quotes\""
matches the text value with "quotes".
Legacy query syntax
Older queries stored attributes as typed fields, so they had to prependattributes., append a type suffix (_string, _int), and use a [ ] list for
multiple values. The current query language removes all three — reference fields
directly and use OR instead of a list:
attributes. is now an ordinary path into your log’s JSON. So
attributes.user_id_int=12345 looks for a user_id_int key inside an
attributes object. A filter in the old attributes. form matches nothing,
instead of returning an error.
If your logs contain an attributes object, you can filter on its fields, such
as attributes.user_id=12345.