Skill v1.0.0

name: seq-search-and-query description: Search and query logs and spans in Seq. Use when interacting with Seq. license: Apache-2.0 metadata: version: "1.0.0" author: Datalust and Contributors

Seq is a storage service for log and trace telemetry. Search Seq to retrieve matching log events and spans. Query Seq to compute tabular, aggregate results from log events and spans.

Seq's query language is not SQL — assuming SQL semantics will produce errors. Do NOT rely on prior knowledge of Seq's query language. Always use the grammar, rules, and examples in this document as a basis for Seq queries and searches.

Starting a Diagnostic Session

Being "confidently wrong" is the most common and worst failure mode when working with diagnostic data. EVERY diagnostic session MUST begin with the following steps:

1. Check for relevant signals. Many event filtering problems have already been solved and the resulting filters saved as efficiently indexed signals.
2. Retrieve a sample of relevant events. Use signals identified in (1) where appropriate, event search and query supports them.
3. Proactively confirm the schema of the search results using appropriate tools.
4. Inspect a subset of relevant events in full.
5. Determine how the correctness of any conclusions can be verified using real diagnostic data.

DO NOT skip steps just because early results suggest a quicker path to a solution: this is the path to being confidently wrong!

Event Data Model

All events stored in Seq use the same data model. Spans are distinguished from log events by the presence of the @Start property. The following built-in properties are supported.

Tip: if searching or querying with seqcli, pass --native to show results in round-trippable, agent-friendly syntax. Consider --json instead for programmatic scenarios, but take care: in JSON output mode, built-in property names are abbreviated.

Type System

Stored data and intermediate values in expression evaluation are typed dynamically. Values are always one of the following types.

In expression evaluation, Seq does not perform any type coercion.

The results of functions and operators that receive invalid arguments are undefined, which is the absence of a value (_undefined_ has the same "poison" semantics as NULL in standard SQL).

Type notation in this document column uses the suffix ? on a type name to indicate values that may be undefined. The synthetic type name any is used as an alias for null | boolean | number | array | object.

Scalar Functions and Operators

These built-in functions and operators work with individual values. See Aggregate Functions for information on functions like count() and distinct() that work with sets of values.

Aggregate Functions

select queries have access to the following aggregate functions.

Base Grammar

identifier = ( letter | '_' ) , { letter | digit | '_' } ;
built_in_identifier = '@' , ( letter | digit | '_' ) , { letter | digit | '_' } ;
variable = '$' , ( letter | digit | '_' ) , { letter | digit | '_' } ;
letter = ? any Unicode letter ? ;
digit = ? any Unicode digit ? ;
string_literal = "'" , { string_char } , "'" ;
string_char = "''" | ? any character except single quote ? ;
number = natural , [ '.' , natural ] ;
hex_number = '0x' , hex_digit , { hex_digit } ;
natural = digit , { digit } ;
hex_digit = digit | 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
   | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' ;
duration = { natural , time_unit }- ;
time_unit = 'd' | 'h' | 'ms' | 'm' | 'us' | 'μs' | 'ns' | 's' ;
regular_expression = '/' , { regex_char } , '/' ;
regex_char = '\/' | ? any character except '/' ? ;

Expression Grammar

Expr = Disjunction ;
Disjunction = Conjunction , { 'or' , Conjunction } ;
Conjunction = Comparison , { 'and' , Comparison } ;
Comparison = Comparand , { comparison_op , Comparand , [ 'ci' ] } ;
comparison_op = 'not' , 'like'
   | 'like'
   | 'not' , 'in'
   | 'in'
   | '<=' | '<>' | '<'
   | '>=' | '>'
   | '=' ;
Comparand = Term , { ( '+' | '-' ) , Term }  ;
Term = InnerTerm , { ( '*' | '/' | '%' ) , InnerTerm } ;
InnerTerm = Operand , { '^' , Operand } ;
 
Operand = ( unary_op , Operand | Path ) , [ 'is' , null_test ] ;
unary_op = '-' | 'not' ;
null_test = 'null' | 'not' , 'null' ;
Path = Factor , { path_step } ;
path_step = '.' , identifier
   | '[' , ( wildcard | Expr ) , ']' ;
wildcard = '?' | '*' ;
Factor = '(' , Expr , ')'
   | Item ;
Item = Property
   | Literal
   | Function
   | ArrayLiteral
   | ObjectLiteral
   | Conditional
   | Block
   | Lambda
   | Variable ;
Property = built_in_identifier
   | identifier ;   (* when not followed by '(' *)
Literal = string_literal
   | number
   | hex_number
   | duration
   | regular_expression
   | 'true'
   | 'false'
   | 'null' ;
Function = function_name , '(' , arg_list , ')' , [ 'ci' ] ;
function_name = identifier
   | 'and' | 'not' | 'or' ;
arg_list = '*'   (* only valid for count(*) *)
   | [ Expr , { ',' , Expr } ] ;
ArrayLiteral = '[' , [ Expr , { ',' , Expr } ] , ']' ;
ObjectLiteral = '{' , [ ObjectMember , { ',' , ObjectMember } ] , '}' ;
ObjectMember  = ( identifier | string_literal ) , ':' , Expr ;
Conditional = 'if' , Expr , 'then' , Expr , 'else' , Expr ;
Block = 'let' , '|' , Binding , { ',' , Binding } , '|' , Expr ;
Binding = identifier , ':' , Expr ;
Lambda = '|' , [ identifier , { ',' , identifier } ] , '|' , Expr ;
Variable = variable ;

Query Grammar

Query = [ ExplainClause ]
   SelectClause
   [ IntoClause ]
   [ FromClause ]
   [ WhereClause ]
   [ GroupByClause ]
   [ HavingClause ]
   [ OrderByClause ]
   [ LimitClause ]
   [ ForClause ] ;
ExplainClause = 'explain' , [ 'analyze' | 'lower' ] ;
SelectClause = 'select' , SelectColumn , { ',' , SelectColumn } ;
SelectColumn = '*'
   | Expr , [ 'as' , identifier ] ;
IntoClause = 'into' , variable ;
FromClause = 'from' , source , { LateralJoin } ;
source = 'stream' | 'series' ;
LateralJoin = 'lateral' , 'unnest' , '(' , Expr , ')' , 'as' , identifier ;
WhereClause = 'where' , Expr ;
GroupByClause = 'group' , 'by' , Grouping , { ',' , Grouping } ;
Grouping = TimeGrouping
   | Expr , [ 'ci' ] , [ 'as' , identifier ] ;
TimeGrouping  = 'time' , '(' , duration , ')' ;
HavingClause = 'having' , Expr ;
OrderByClause = 'order' , 'by' , Ordering , { ',' , Ordering } ;
Ordering = TimeOrdering
   | identifier , [ 'ci' ] , [ 'asc' | 'desc' ] ; (* identifier must be a selected column or group key alias *)
TimeOrdering  = 'time' ;
LimitClause = 'limit' , natural ;
ForClause = 'for' , ForOption , { ',' , ForOption } ;
ForOption = identifier , [ '(' , [ Expr , { ',' , Expr } ] , ')' ] ;

Keywords are case-insensitive.

Example Expressions

Query Example

Grouped query with ordering:

select count(*)
from stream
group by @Resource.service.name as service
order by service

Tracing Tactics

• Find traces by searching for their included spans.
• To reconstruct a trace as a call tree, use the seq_load_trace MCP tool, or run seqcli trace -i <traceid>.
• Project additional Seq expressions per span with columns (CLI: repeated --column), for example

@Resource.service.name or @SpanKind; values appear in each node's columns object, keyed by expression.

• On large traces, pass span_id (CLI: --span-id) to retrieve only the subtree rooted at one span.
• If complete is false, the trace was truncated at the retrieval limit.
• Log events recorded during a span are not included by seq_load_trace; find them by searching with

@TraceId = '...' and @SpanId = '...' and not Has(@Start) (CLI: pass --logs).

• To see all properties of a single span, use the "retrieve a specific trace span" search recipe above.

Rank services by span latency over a window:

select
   count(*) as spans,
   Round(TotalMilliseconds(percentile(@Elapsed, 95)), 2) as p95_ms,
   Round(TotalMilliseconds(max(@Elapsed)), 2) as max_ms
from stream
where @Timestamp >= now() - 30m and Has(@Start)
group by @Resource.service.name as service     -- group key: alias it, do NOT put it in the select list
having spans > 50                              -- filter groups by the select alias, NOT by count(*) directly
order by p95_ms desc                           -- order by a selected aggregate's alias
limit 100

User-Defined Property Schema

Seq servers are compatible with a vast array of data sources. They may use a mix of OpenTelemetry and framework/ecosystem-specific property names, and may do so inconsistently.

When available, always use the MCP schema tool to inspect the actual properties appearing on search results. In particular, don't skip schema checks early in investigations just because you've seen a few events. Events are inconsistent! Use the schema tool at least once just to be safe.

Gotchas

• Group keys are automatically included in result rowsets and must not be explicitly included in the select list.
• To order by group keys, apply an alias with group by <expr> as <alias> and use order by <alias>. Never add the group key to the select list, this will fail.
• OpenTelemetry dotted property names correspond to property accessor paths in Seq, so @Resource.service.name and http.response.status_code are written exactly like this.
• Never put a dotted OTel name inside [...]. @Resource['a.b.c'] is a single literal key (almost always undefined); use @Resource.a.b.c for path navigation.
• Seq expression literals are not JSON, take care to use the Seq expression syntax when formatting literal values.
• Seq queries are not SQL. Don't expect standard SQL syntax, operators, or semantics to apply, always use the grammar and built-ins described above.
• Seq searches work backwards through the event stream and always return results in reverse-chronological order, from most recent to least recent.
• Data in Seq servers doesn't always use OpenTelemetry semantic conventions. When searching or querying, only use property names from the built-ins described above, that appear on search results, or that are returned from the schema tool.
• Bare identifiers like SomeName are synonymous with @Properties['SomeName']. The latter form allows irregular names to be used.
• The only escape sequence allowed and required in Seq strings is a doubled single quote - '' - which evaluates to an embedded literal single quote. Backslash escaping is not recognized.
• @Timestamp, @Start, and @Elapsed are internally represented as .NET DateTime ticks (100 ns resolution) in order to support consistent timestamp/duration math. Comparing these properties with strings will fail: use duration literals for durations, and the DateTime function to convert from ISO-8601 strings.
• Although Seq's types resemble those from JavaScript, Seq does not support JavaScript operators and does not use JavaScript's system of comparisons.
• The expression null = null is true in Seq's type system; null is just a regular value.
• Timestamp bounds with inclusive starts and exclusive ends are the most efficient for Seq to work with.
• Regular expression evaluation is extremely expensive, avoid these as much as possible.
• Queries without from stream or from series are scalar (can't project out fields or compute aggregations).
• Searches and queries should always constrain results using @Timestamp, @TraceId, or @Id.
• group by time(..) requires an inclusive lower time bound on @Timestamp.
• Queries impose a default limit of 1024 rows, which can be changed with the limit clause. Set smaller limits to conserve resources when speculatively exploring.
• Use ToIsoString() and ToTimeString() to make timestamps or durations (even computed ones) readable. If you forget, you can convert individual values cheaply with a scalar query like ToIsoString(12345).
• When grouping by time(..), the time ordering leaves of the interval - just order by time, the interval isn't re-specified.
• All function calls and operators are case-sensitive unless the ci modifier is appended.