Log query reference

Columns, filters, and measures for kq.logs.aggregate() / kq.logs.raw() (and the client.searchLogs(...) filter shape). Run a built query with client.query(q) — it is fully typed (const { data } = await client.query(q) for aggregate; { data, nextCursor } for raw).

How columns work

Same rules as traces: PascalCase = structural field, dotted = semantic-convention attribute (auto-resolved), { container, key } = explicit. Log containers: LogAttributes (record-specific), ResourceAttributes (process/host/service), ScopeAttributes (instrumentation scope).

Structural columns

No ServiceName structural column — use the dotted "service.name" attribute.

Severity model (canonical error detector)

Filter errors by SeverityNumber >= 17 rather than SeverityText. SeverityNumber is standardized by the OTel Log Data Model; SeverityText is free-form and inconsistent.

kq.logs
  .raw()
  .where((f) => f.gte("SeverityNumber", 17))
  .timeRelative("1h")
  .limit(50)
  .build();
kq.logs
  .raw()
  .where((f) => f.eq("TraceId", traceId))
  .timeRelative("1h")
  .build(); // correlate
kq.logs
  .raw()
  .where((f) => f.contains("Body", "connection refused"))
  .timeRelative("1h")
  .build();

Common semantic-convention attributes (dotted)

log.level, log.file.path, exception.type, exception.message, exception.stacktrace, error.type, code.function.name, code.file.path, http.request.method, http.response.status_code, http.route, url.path, client.address, plus the resource set (service.name, k8s.pod.name, …).

Filter & measure ops

Filters: same DSL as traces (eq/neq/contains/startsWith/in/gt/gte/lt/lte/isNull/and/or). Aggregate measures: count, countDistinct, sum/avg/min/max, rate*. (No errorRate/ throughput — those are trace-only.) Every query needs a time window + .summary()/.timeSeries().

// error volume by service + severity over time
kq.logs
  .aggregate()
  .measure((m) => m.count("n"))
  .dimension("service.name")
  .dimension("SeverityText")
  .where((f) => f.gte("SeverityNumber", 17))
  .timeRelative("3h")
  .timeSeries("5m")
  .orderByMeasure("n", "desc")
  .build();

CLI fallback (quick lookups)

client.searchLogs({ serviceName, severityNumberMin, bodyContains, traceId, logAttributes, limit }) mirrors these (field is bodyContains, not body). searchLogs is an async iterable — use for await (const log of client.searchLogs({…})) {…}, don't await it as an array; for one page use searchLogsPage → { data, nextCursor }.