Package codes.grow.packages.tempo
Class TempoQueryClient
java.lang.Object
codes.grow.packages.tempo.TempoQueryClient
- All Implemented Interfaces:
TraceQueryClient,AutoCloseable
Client for Tempo's HTTP query API (port 3200). Implements the SPEC
TraceQueryClient
(getTrace, searchTraces, listServices, listOperations,
getDependencies, waitForTrace) plus Tempo's own search
(TraceQL), searchTags, searchTagValues, traceQLMetrics, echo(), ready() and buildInfo().
Get one from TempoClient.query(), or build an owned one with create(TempoConfig) / fromEnv() (close() then closes its client). The tenant
(X-Scope-OrgID) comes from the config. Every method has a blocking form and an
…Async form returning CompletableFuture.
Tempo shows a trace by id immediately after ingest, but search, tags and metrics only after about 30 seconds.
-
Constructor Summary
ConstructorsConstructorDescriptionTempoQueryClient(TempoClient client) Wraps an existing client (not closed byclose()). -
Method Summary
Modifier and TypeMethodDescriptionGET /api/status/buildinfo→ version, revision, branch, build user/date, Go version.AsynchronousbuildInfo().client()The underlying client.voidclose()Closes the underlying client when this query client owns it.static TempoQueryClientcreate(TempoConfig config) Builds a query client that owns itsTempoClient.echo()GET /api/echo→"echo"(no tenant needed).Asynchronousecho().static TempoQueryClientfromEnv()Builds an owned query client fromGROW_GRAFANA_TEMPO_*/TEMPO_*variables.getDependencies(Instant start, Instant end) AlwaysUnsupportedException: Tempo has no dependency-graph API (service graphs need the metrics-generator plus a Prometheus backend).getDependenciesAsync(Instant start, Instant end) Fetches a trace by id:GET /api/v2/traces/{id}(falls back to v1/api/traces/{id}when the v2 route answers 404).getTrace(String traceId, GetTraceOptions options) getTrace(String)with a time window that narrows the backend blocks searched (recent data is returned anyway).getTraceAsync(String traceId) AsynchronousTraceQueryClient.getTrace(java.lang.String); runs with the caller's id policy (TraceQueryClient.acceptsNativeIds()).getTraceAsync(String traceId, GetTraceOptions options) AsynchronousgetTrace(String, GetTraceOptions).listOperations(String service) Span names of one service (namevalues filtered by the service), sorted.listOperationsAsync(String service) AsynchronousTraceQueryClient.listOperations(java.lang.String).Service names (resource.service.namevalues seen recently), sorted.AsynchronousTraceQueryClient.listServices().booleanready()GET /ready: true when Tempo answersready, false while it is starting (HTTP 503) or reports another state.Asynchronousready().search(SearchRequest request) Runs a TraceQL search:GET /api/search?q=…&start&end&limit&spss(noqwithout a query).searchAsync(SearchRequest request) Asynchronoussearch(SearchRequest).searchTags(SearchTagsOptions options) Tag names per scope:GET /api/v2/search/tags→{resource: [...], span: [...], …}.searchTagsAsync(SearchTagsOptions options) AsynchronoussearchTags(SearchTagsOptions).searchTagValues(String tag) searchTagValues(String, SearchTagValuesOptions)without filters.searchTagValues(String tag, SearchTagValuesOptions options) Values of one tag:GET /api/v2/search/tag/{tag}/values.searchTagValuesAsync(String tag, SearchTagValuesOptions options) AsynchronoussearchTagValues(String, SearchTagValuesOptions).searchTraces(TraceSearchQuery query) SPEC search: builds one TraceQL spanset (resource.service.name,name, unscoped.tagfilters,trace:durationbounds in µs) and maps hits toTraceSummary(duration has millisecond precision).AsynchronousTraceQueryClient.searchTraces(codes.grow.packages.tempo.tracing.query.TraceSearchQuery); runs with the caller's id policy (TraceQueryClient.acceptsNativeIds()).static TraceQLThe TraceQL querysearchTraces(codes.grow.packages.tempo.tracing.query.TraceSearchQuery)sends for aTraceSearchQuery.toString()traceQLMetrics(TraceQL query, MetricsRange range) traceQLMetrics(String, MetricsRange)with a builder query.traceQLMetrics(String query, MetricsRange range) TraceQL metrics over a range:GET /api/metrics/query_range(for example{ resource.service.name = "api" } | rate()).traceQLMetricsAsync(String query, MetricsRange range) AsynchronoustraceQLMetrics(String, MetricsRange).Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface codes.grow.packages.tempo.tracing.query.TraceQueryClient
acceptsNativeIds, waitForTrace, waitForTrace, waitForTraceAsync
-
Constructor Details
-
TempoQueryClient
Wraps an existing client (not closed byclose()).- Parameters:
client- the client
-
-
Method Details
-
create
Builds a query client that owns itsTempoClient.- Parameters:
config- configuration- Returns:
- query client
-
fromEnv
Builds an owned query client fromGROW_GRAFANA_TEMPO_*/TEMPO_*variables.- Returns:
- query client
-
client
The underlying client.- Returns:
- client
-
getTrace
Fetches a trace by id:GET /api/v2/traces/{id}(falls back to v1/api/traces/{id}when the v2 route answers 404). Empty when the trace does not exist or belongs to another tenant.- Specified by:
getTracein interfaceTraceQueryClient- Parameters:
traceId- 1-32 hex characters- Returns:
- the trace, or empty
- Throws:
ValidationException- for an invalid id
-
getTrace
getTrace(String)with a time window that narrows the backend blocks searched (recent data is returned anyway).- Parameters:
traceId- trace idoptions- window- Returns:
- the trace, or empty
-
getTraceAsync
Description copied from interface:TraceQueryClientAsynchronousTraceQueryClient.getTrace(java.lang.String); runs with the caller's id policy (TraceQueryClient.acceptsNativeIds()).- Specified by:
getTraceAsyncin interfaceTraceQueryClient- Parameters:
traceId- trace id- Returns:
- future trace
-
getTraceAsync
AsynchronousgetTrace(String, GetTraceOptions).- Parameters:
traceId- trace idoptions- window- Returns:
- future trace
-
search
Runs a TraceQL search:GET /api/search?q=…&start&end&limit&spss(noqwithout a query). Trace ids come back padded to 32 hex characters.- Parameters:
request- query, window and limits- Returns:
- matching traces
- Throws:
ValidationException- for invalid TraceQL (HTTP 400) or a non-positive limit
-
searchAsync
Asynchronoussearch(SearchRequest).- Parameters:
request- request- Returns:
- future result
-
searchTraces
SPEC search: builds one TraceQL spanset (resource.service.name,name, unscoped.tagfilters,trace:durationbounds in µs) and maps hits toTraceSummary(duration has millisecond precision).- Specified by:
searchTracesin interfaceTraceQueryClient- Parameters:
query- filter (limit default 20)- Returns:
- summaries
-
searchTracesAsync
Description copied from interface:TraceQueryClientAsynchronousTraceQueryClient.searchTraces(codes.grow.packages.tempo.tracing.query.TraceSearchQuery); runs with the caller's id policy (TraceQueryClient.acceptsNativeIds()).- Specified by:
searchTracesAsyncin interfaceTraceQueryClient- Parameters:
query- filter- Returns:
- future summaries
-
searchTracesTraceQL
The TraceQL querysearchTraces(codes.grow.packages.tempo.tracing.query.TraceSearchQuery)sends for aTraceSearchQuery.- Parameters:
query- filter- Returns:
- TraceQL builder
-
searchTags
Tag names per scope:GET /api/v2/search/tags→{resource: [...], span: [...], …}. Without a scope it returns every scope that has data.- Parameters:
options- scope, TraceQL filter and window- Returns:
- scope name → tag names
-
searchTagsAsync
AsynchronoussearchTags(SearchTagsOptions).- Parameters:
options- options- Returns:
- future map
-
searchTagValues
Values of one tag:GET /api/v2/search/tag/{tag}/values.tagis a TraceQL identifier (resource.service.name,span.http.response.status_code,name,status,span.grow weird.key); an unscoped attribute name is aValidationException.- Parameters:
tag- TraceQL identifieroptions- TraceQL filter and window- Returns:
- values with their types
-
searchTagValues
searchTagValues(String, SearchTagValuesOptions)without filters.- Parameters:
tag- TraceQL identifier- Returns:
- values
-
searchTagValuesAsync
public CompletableFuture<List<TagValue>> searchTagValuesAsync(String tag, SearchTagValuesOptions options) AsynchronoussearchTagValues(String, SearchTagValuesOptions).- Parameters:
tag- TraceQL identifieroptions- options- Returns:
- future values
-
listServices
Service names (resource.service.namevalues seen recently), sorted.- Specified by:
listServicesin interfaceTraceQueryClient- Returns:
- service names
-
listServicesAsync
Description copied from interface:TraceQueryClientAsynchronousTraceQueryClient.listServices().- Specified by:
listServicesAsyncin interfaceTraceQueryClient- Returns:
- future names
-
listOperations
Span names of one service (namevalues filtered by the service), sorted.- Specified by:
listOperationsin interfaceTraceQueryClient- Parameters:
service- service name- Returns:
- operation names
- Throws:
ValidationException- when the service is blank
-
listOperationsAsync
Description copied from interface:TraceQueryClientAsynchronousTraceQueryClient.listOperations(java.lang.String).- Specified by:
listOperationsAsyncin interfaceTraceQueryClient- Parameters:
service- service name- Returns:
- future names
-
traceQLMetrics
TraceQL metrics over a range:GET /api/metrics/query_range(for example{ resource.service.name = "api" } | rate()). Zero samples omitted by Tempo are reported as 0.- Parameters:
query- TraceQL metrics queryrange- window, step and exemplars- Returns:
- series
- Throws:
ValidationException- for a blank query or one without a metrics pipeline (HTTP 400)
-
traceQLMetrics
traceQLMetrics(String, MetricsRange)with a builder query.- Parameters:
query- TraceQL builder (append the metrics pipeline yourself in text form otherwise)range- window- Returns:
- series
-
traceQLMetricsAsync
AsynchronoustraceQLMetrics(String, MetricsRange).- Parameters:
query- queryrange- window- Returns:
- future series
-
echo
GET /api/echo→"echo"(no tenant needed).- Returns:
- the echoed text
-
echoAsync
Asynchronousecho().- Returns:
- future text
-
ready
public boolean ready()GET /ready: true when Tempo answersready, false while it is starting (HTTP 503) or reports another state. Throws on network errors (unlikeTempoClient.health()).- Returns:
- readiness
-
readyAsync
Asynchronousready().- Returns:
- future readiness
-
buildInfo
GET /api/status/buildinfo→ version, revision, branch, build user/date, Go version.- Returns:
- build information
- Throws:
UnsupportedException- when the endpoint does not exist
-
buildInfoAsync
AsynchronousbuildInfo().- Returns:
- future build information
-
getDependencies
AlwaysUnsupportedException: Tempo has no dependency-graph API (service graphs need the metrics-generator plus a Prometheus backend).- Specified by:
getDependenciesin interfaceTraceQueryClient- Parameters:
start- ignoredend- ignored- Returns:
- never
- Throws:
UnsupportedException- always
-
getDependenciesAsync
Description copied from interface:TraceQueryClient- Specified by:
getDependenciesAsyncin interfaceTraceQueryClient- Parameters:
start- range start ornullend- range end ornull- Returns:
- future links
-
close
public void close()Closes the underlying client when this query client owns it. Idempotent.- Specified by:
closein interfaceAutoCloseable
-
toString
-