Kubesense

Log & Trace Fields

The columns available for filtering, grouping, and selecting in logs and traces queries — with their storage names, display labels, types, and values.

Every logs and traces query — whether a filter, an SPL pipeline, or a required_fields selection — refers to fields by their column name. This page lists all standard columns for both signals so you can build queries without guessing.

note: Column name vs. display label. The API and SPL use the underlying column name (e.g. return_code, protocol_type, pod_name). The Explorer UI shows a friendlier label for some of them (status_code, protocol, instance). When you write a query, use the Column value from the tables below. Where a label differs, it's shown so you can translate what you see in the UI.

Beyond these standard columns, both signals carry dynamic attributes — arbitrary key/value fields emitted by your instrumentation. See Attributes below.

Using fields in requests

The same column name works across all query surfaces:

common_filter (POST /api/logs, /api/traces)
{ "field": "level", "operation": "IN", "values": ["ERROR", "WARN"], "type": "string" }
SPL (POST /api/logs/spl)
fields @timestamp, workload, level, body | filter level = "ERROR" | limit 50
required_fields (column selection)
{ "required_fields": ["workload", "namespace", "level", "body"] }
  • type in a filter is string for text columns and float for numeric ones (see the tables).
  • Discover the live values for any field by calling POST /api/logs/filters or POST /api/traces/filter — the same facets the Explorer sidebar shows.

Log columns

ColumnUI labelTypeValues / notes
timestamptimestampstringLog timestamp. Time range is set via the query string, not as a filter.
workloadworkloadstringKubernetes workload (Deployment/StatefulSet/…) name
namespacenamespacestringKubernetes namespace
clusterclusterstringCluster name
pod_nameinstancestringPod name
container_namecontainerstringContainer name
hostnodestringNode / host name
leveltypestringERROR, WARN, INFO, DEBUG, TRACE, FATAL, PANIC
formatformatstringjson, klog, nginx
sourcesourcestringCollection source
regionregionstringCloud region
app_versionapp_versionstringApplication version
env_typeenv_typestringEnvironment type (e.g. production, staging)
bodybodystringThe raw log line. Use for substring/token search — see Searching the log body.
body_lengthbody_lengthfloatLength of the log line in bytes
pattern_idpattern_idstringAuto-clustered log-pattern id

Searching the log body

body holds the full log message. Beyond exact match, these operators target it (they leverage the body text index — much faster than a bare wildcard):

OperationMeaningExample value
HAS_TOKENWhole-word token matchtimeout
HAS_ANY_TOKENSAny of the listed whole words["timeout", "refused"]
HAS_ALL_TOKENSAll of the listed whole words["connection", "reset"]
MULTI_SEARCH_ANYSubstring match (matches inside larger words)["oom", "sigkill"]
ILIKE / SUBSTR_ILIKECase-insensitive wildcard / substring%deadline exceeded%

note: Token operators match whole words split on non-alphanumerics: HAS_ALL_TOKENS of node-agent matches a line containing node and agent (in any position), not the literal adjacent string. For an exact substring use MULTI_SEARCH_ANY or SUBSTR_ILIKE.

Parsed (structured) log fields

For structured logs, fields parsed out of the message are addressed with the log_processed. prefix in SPL — e.g. fields log_processed.http.status_code, log_processed.duration_ms. See the SPL guide.

Trace columns

Identity & topology

ColumnUI labelTypeValues / notes
workloadworkloadstringWorkload name. Group "by service" on workload — it's populated on every span, unlike app_service.
app_serviceservicestringOTel service.name. Populated only for SDK-instrumented services; may be sparse.
namespacenamespacestringKubernetes namespace
pod_nameinstancestringPod name
container_namecontainerstringContainer name
node_namenode_namestringNode / host name
clusterclusterstringCluster name
regionregionstringCloud region
app_versionapp_versionstringApplication version
env_typeenv_typestringEnvironment type
clustered_resourceresourcestringNormalized resource / endpoint path (e.g. GET /api/v1/users/{id})
operation_nameoperation_namestringSpan operation name
serverserverstringServer side of the call
clientclientstringClient side of the call
server_namespaceserver_namespacestringNamespace of the server side
client_namespaceclient_namespacestringNamespace of the client side
partner_clusterpartner_clusterstringPeer cluster in cross-cluster calls
customer_identifierdomainstringTenant / customer identifier

Protocol, status & method

ColumnUI labelTypeValues / notes
protocol_typeprotocolstringHTTP, gRPC, TCP, MongoDB, Redis, MySQL, PostgreSQL
statusstatusstringerror, ok
return_codestatus_codestringHTTP/RPC status — 200, 400, 401, 403, 404, 500, 502, 503, 504, …
subtypemethodstringGET, POST, PUT, DELETE, PATCH
kindrolestringserver, client
is_externalrequest_typebooleanWhether the call crosses the cluster boundary
sourcesourcestringeBPF, OTel
issue_reasonreasonstringDetected issue category (freeform)

Timing & identifiers

ColumnUI labelTypeValues / notes
durationdurationfloatSpan duration in nanoseconds. See the note below.
start_timestamptimestampstringSpan start time (time range is set via the query string)
trace_idtrace_idstringTrace id (freeform match)
span_idspan_idstringSpan id (freeform match)

warning: Trace duration is in nanoseconds. When filtering or thresholding on latency, convert: 500ms → 500000000, 250ms → 250000000, 1s → 1000000000.

note: For a status-code class rather than a list — all 5xx, all 4xx — use an advanced-query filter with a LIKE pattern (return_code LIKE "5__") instead of enumerating every code.

Attributes

Both logs and traces carry dynamic attributes — key/value fields your instrumentation emits (e.g. http.route, db.system, user.id, payload.tenant) that aren't standard columns. Reference them with an @ prefix:

Filtering on an attribute
{ "field": "@http.route", "operation": "IN", "values": ["/checkout"], "type": "string" }
SPL
fields @timestamp, workload, @http.route | filter @http.route = "/checkout"

Attributes are stored separately from the standard columns, so a query that filters, groups, or aggregates on one reads a wider (raw) data path than a pure-column query. Discover the attribute keys and values present in your data with POST /api/logs/filters / POST /api/traces/filter, or the attribute-search field endpoints.

Where these fields apply

The same column names are used consistently across KubeSense:

  • Logs & Traces API — common_filter / adv_filters field, required_fields, and SPL.
  • Alert rules — filter and Group By fields (grouping by workload, namespace, etc. produces per-series alerts). Alerts persist and evaluate using these column names, so an imported rule should reference return_code/protocol_type, not the UI labels.
  • Dashboards — logs/traces panel filters, group-by, and template variables.

back

Metrics API