traces

Creates, updates, deletes, gets or lists a traces resource.

Overview

Name	traces
Type	Resource
Id	railway.observability.traces

Fields

The following fields are returned by SELECT queries:

list

One row per TraceSummary. One trace of an environment: the request as a whole, summarised from its spans.

Name	Datatype	Description
root_service_id	string	Railway service the root span belongs to
trace_id	string	W3C trace id, 32 lower-case hex characters
root_service_name	string	The root span's service.name
root_span_name	string	Name of the root span, or of the earliest span when the root is missing
service_name	string	service.name of the earliest span a service exported; null when the request never reached one
duration_ms	number	From the earliest span start to the latest span end
error_count	integer	Spans with an error status
has_edge	boolean	Whether the edge exported any span of the trace
root_component	string	Which hop exported the root span: edge (hikari), proxy (tcp-proxy) or service
root_server_address	string	The root span's server.address, when it set one
root_url_path	string	The root span's url.path, when it set one
span_count	integer
started_at	string	Start of the earliest span (ISO timestamp)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	environment_id	end_date, filter, service_id, start_date	Traces of an environment with at least one span matching the filter, newest first. Backed by the Railway GraphQL query traces. A SQL LIMIT is pushed down to the limit argument.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
environment_id	string
end_date	string	Latest span start to consider (ISO); defaults to now.
filter	string	Filter expression over spans, e.g. @status:error @component:edge @duration:>500 @http.route:/api/users. Built-in fields: trace, span, name, serviceName, service, deployment, replica, component, kind, status, duration (ms). Any other @key looks the key up in the span and resource attributes; free text matches the span name. Prefix a term with - to exclude it.
service_id	string	Only traces with a span from this Railway service (optional).
start_date	string	Oldest span start to consider (ISO). Clamped to the project's retention; defaults to one hour ago.

SELECT examples

list

Traces of an environment with at least one span matching the filter, newest first. Backed by the Railway GraphQL query traces. A SQL LIMIT is pushed down to the limit argument.

SELECT
root_service_id,
trace_id,
root_service_name,
root_span_name,
service_name,
duration_ms,
error_count,
has_edge,
root_component,
root_server_address,
root_url_path,
span_count,
started_at
FROM railway.observability.traces
WHERE environment_id = '{{ environment_id }}' -- required
AND end_date = '{{ end_date }}'
AND filter = '{{ filter }}'
AND service_id = '{{ service_id }}'
AND start_date = '{{ start_date }}'
;