Package codes.grow.packages.datadogapm
Class DatadogSpansQuery
java.lang.Object
codes.grow.packages.datadogapm.DatadogSpansQuery
- All Implemented Interfaces:
TraceQueryClient,AutoCloseable
The Datadog spans query client: the SaaS API at
https://api.<site> with the headers
DD-API-KEY and DD-APPLICATION-KEY (the application key needs apm_read).
It implements TraceQueryClient on top of the spans search and aggregate APIs, plus the
Datadog-specific searchSpans(codes.grow.packages.datadogapm.SearchSpansOptions), aggregateSpans(java.util.List<codes.grow.packages.datadogapm.SpanCompute>, java.util.List<codes.grow.packages.datadogapm.SpanGroupBy>) and ping(). Thread-safe. No
container can serve these endpoints, so they are unit-tested against Datadog's documented
examples and verified by the live sandbox job (API.md section 4).
Errors: 400/413/422 VALIDATION, 401 AUTHENTICATION, 403
PERMISSION_DENIED (AUTHENTICATION from ping()), 404 NOT_FOUND, 408
TIMEOUT, 429 RATE_LIMITED (waits Retry-After / X-RateLimit-Reset within
the retry budget), 5xx UNAVAILABLE.
try (DatadogSpansQuery q = DatadogSpansQuery.fromEnv()) {
for (DatadogSpan s : q.searchSpans(SearchSpansOptions.builder().query("service:checkout").build())) {
System.out.println(s.span().name());
}
}
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final DurationDefault polling interval ofwaitForTrace(String)(Datadog allows 50 searches/min). -
Method Summary
Modifier and TypeMethodDescriptionaggregateSpans(List<SpanCompute> compute, List<SpanGroupBy> groupBy) aggregateSpans(List, List, AggregateSpansOptions)over all spans of the last 15 minutes.aggregateSpans(List<SpanCompute> compute, List<SpanGroupBy> groupBy, AggregateSpansOptions options) CallsPOST /api/v2/spans/analytics/aggregate: computescomputeper group ofgroupBy.aggregateSpansAsync(List<SpanCompute> compute, List<SpanGroupBy> groupBy, AggregateSpansOptions options) AsynchronousaggregateSpans(List, List, AggregateSpansOptions).voidclose()Releases connections; idempotent.config()The effective configuration.static DatadogSpansQuerycreate(DatadogApmConfig config) Creates a query client.static DatadogSpansQueryfromEnv()Creates a query client from the environment (DD_API_KEY,DD_APP_KEY,DD_SITE, ...; seeDatadogApmConfig).getDependencies(Instant start, Instant end) Not supported: Datadog's public API offers no service dependency graph.Reads a trace by searching the indexed spans withtrace_id:<id>over the last 24 hours (all pages, merged by span id): only spans kept by retention filters, so the trace may be partial.getTrace(String traceId, GetTraceOptions options) getTrace(String)with a search window or, withpreview, the trace-by-id endpointGET /api/v2/trace/{id}(full trace, preview API; 404 gives empty).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) The distinct span names (Datadogresource_name) ofservicein the last 24 hours, viaaggregateSpans(java.util.List<codes.grow.packages.datadogapm.SpanCompute>, java.util.List<codes.grow.packages.datadogapm.SpanGroupBy>)grouped byresource_name(up to 1000), sorted.listOperationsAsync(String service) AsynchronousTraceQueryClient.listOperations(java.lang.String).CallsGET /api/v2/apm/services?filter[env]=...with the configured environment (else*, all) and returns the sorted names of the services that reported traces.listServices(String env) listServices()with an explicit environment filter.AsynchronousTraceQueryClient.listServices().listServicesAsync(String env) AsynchronouslistServices(String).ping()Authenticated round tripGET /api/v2/validate_keys(API key + application key).Asynchronousping().static StringquoteQueryValue(String value) Quotes a value for the Datadog query syntax when it contains spaces or special characters.searchSpans(SearchSpansOptions options) Iterates over every span matching the search, following the cursor page by page (same absolute window for every page; pages are fetched lazily).searchSpansAsync(SearchSpansOptions options) AsynchronoussearchSpans(codes.grow.packages.datadogapm.SearchSpansOptions): every page collected into one list.searchSpansPage(SearchSpansOptions options) Returns one page ofPOST /api/v2/spans/events/search.searchSpansPageAsync(SearchSpansOptions options) searchTraces(TraceSearchQuery query) Finds traces with spans matching the query (service, span name,@tagvalues, duration) in start..end (default: the last 15 minutes), newest first, up to the limit of distinct trace ids (at most 5 pages).AsynchronousTraceQueryClient.searchTraces(codes.grow.packages.datadogapm.tracing.query.TraceSearchQuery); runs with the caller's id policy (TraceQueryClient.acceptsNativeIds()).toString()static StringThe Datadog query string for a SPEC trace search:service:,resource_name:,@<tag>:and@duration:>=/<=(nanoseconds).waitForTrace(String traceId) PollsgetTrace(String)every 2 s (Datadog allows 50 searches per minute) for up to 30 s until the trace has a span.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface codes.grow.packages.datadogapm.tracing.query.TraceQueryClient
acceptsNativeIds, getDependenciesAsync, waitForTrace, waitForTraceAsync
-
Field Details
-
DATADOG_WAIT_INTERVAL
Default polling interval ofwaitForTrace(String)(Datadog allows 50 searches/min).
-
-
Method Details
-
create
Creates a query client.- Parameters:
config- configuration withapiKeyandappKey- Returns:
- client
- Throws:
ConfigException- unless both keys are configured
-
fromEnv
Creates a query client from the environment (DD_API_KEY,DD_APP_KEY,DD_SITE, ...; seeDatadogApmConfig).- Returns:
- client
-
config
The effective configuration.- Returns:
- configuration
-
searchSpansPage
Returns one page ofPOST /api/v2/spans/events/search. PassDatadogSpansPage.nextCursor()back as the cursor with the same absolute window for the next page. Statustimeoutor warnings mark a partial result.- Parameters:
options- search options- Returns:
- the page
-
searchSpansPageAsync
- Parameters:
options- search options- Returns:
- future page
-
searchSpans
Iterates over every span matching the search, following the cursor page by page (same absolute window for every page; pages are fetched lazily). ATimeoutExceptionis thrown when Datadog reports a timed-out query that returned no spans (never a silently empty result).for (DatadogSpan s : q.searchSpans(SearchSpansOptions.builder().query("@grow.run:abc").build())) { System.out.println(s.span().name() + " " + s.span().durationMicros()); }- Parameters:
options- search options- Returns:
- lazy iterable (each
iterator()starts a new search)
-
searchSpansAsync
AsynchronoussearchSpans(codes.grow.packages.datadogapm.SearchSpansOptions): every page collected into one list.- Parameters:
options- search options- Returns:
- future spans
-
aggregateSpans
aggregateSpans(List, List, AggregateSpansOptions)over all spans of the last 15 minutes.- Parameters:
compute- computations (results keyedc0,c1, ...)groupBy- group-by facets (may be empty ornull)- Returns:
- result
-
aggregateSpans
public SpanAggregateResult aggregateSpans(List<SpanCompute> compute, List<SpanGroupBy> groupBy, AggregateSpansOptions options) CallsPOST /api/v2/spans/analytics/aggregate: computescomputeper group ofgroupBy.q.aggregateSpans(List.of(SpanCompute.of("pc90", "@duration")), List.of(SpanGroupBy.of("service")), AggregateSpansOptions.of("env:prod", null, null));- Parameters:
compute- computations (results keyedc0,c1, ...)groupBy- group-by facets (may be empty ornull)options- filter- Returns:
- result
- Throws:
ConfigException- whencomputeis empty
-
aggregateSpansAsync
public CompletableFuture<SpanAggregateResult> aggregateSpansAsync(List<SpanCompute> compute, List<SpanGroupBy> groupBy, AggregateSpansOptions options) AsynchronousaggregateSpans(List, List, AggregateSpansOptions).- Parameters:
compute- computationsgroupBy- group-by facetsoptions- filter- Returns:
- future result
-
getTrace
Reads a trace by searching the indexed spans withtrace_id:<id>over the last 24 hours (all pages, merged by span id): only spans kept by retention filters, so the trace may be partial. SeegetTrace(String, GetTraceOptions)for the preview trace-by-id API.- Specified by:
getTracein interfaceTraceQueryClient- Parameters:
traceId- trace id (hex, 64- or 128-bit)- Returns:
- the trace, or empty when nothing is found
-
getTrace
getTrace(String)with a search window or, withpreview, the trace-by-id endpointGET /api/v2/trace/{id}(full trace, preview API; 404 gives empty).- Parameters:
traceId- trace idoptions- options- 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- options- Returns:
- future trace
-
listServices
CallsGET /api/v2/apm/services?filter[env]=...with the configured environment (else*, all) and returns the sorted names of the services that reported traces.- Specified by:
listServicesin interfaceTraceQueryClient- Returns:
- service names
-
listServices
listServices()with an explicit environment filter.- Parameters:
env- environment,*for all,nullfor the default- Returns:
- service names
-
listServicesAsync
Description copied from interface:TraceQueryClientAsynchronousTraceQueryClient.listServices().- Specified by:
listServicesAsyncin interfaceTraceQueryClient- Returns:
- future names
-
listServicesAsync
AsynchronouslistServices(String).- Parameters:
env- environment filter ornull- Returns:
- future names
-
listOperations
The distinct span names (Datadogresource_name) ofservicein the last 24 hours, viaaggregateSpans(java.util.List<codes.grow.packages.datadogapm.SpanCompute>, java.util.List<codes.grow.packages.datadogapm.SpanGroupBy>)grouped byresource_name(up to 1000), sorted.- Specified by:
listOperationsin interfaceTraceQueryClient- Parameters:
service- service name- Returns:
- operation names
-
listOperationsAsync
Description copied from interface:TraceQueryClientAsynchronousTraceQueryClient.listOperations(java.lang.String).- Specified by:
listOperationsAsyncin interfaceTraceQueryClient- Parameters:
service- service name- Returns:
- future names
-
quoteQueryValue
Quotes a value for the Datadog query syntax when it contains spaces or special characters.- Parameters:
value- value- Returns:
- the value, quoted and escaped when needed
-
traceSearchQueryString
The Datadog query string for a SPEC trace search:service:,resource_name:,@<tag>:and@duration:>=/<=(nanoseconds). An empty query is*.- Parameters:
query- trace search query- Returns:
- query string
-
searchTraces
Finds traces with spans matching the query (service, span name,@tagvalues, duration) in start..end (default: the last 15 minutes), newest first, up to the limit of distinct trace ids (at most 5 pages). Summaries are built from the matching spans only.- Specified by:
searchTracesin interfaceTraceQueryClient- Parameters:
query- trace search query- Returns:
- summaries
-
searchTracesAsync
Description copied from interface:TraceQueryClientAsynchronousTraceQueryClient.searchTraces(codes.grow.packages.datadogapm.tracing.query.TraceSearchQuery); runs with the caller's id policy (TraceQueryClient.acceptsNativeIds()).- Specified by:
searchTracesAsyncin interfaceTraceQueryClient- Parameters:
query- filter- Returns:
- future summaries
-
getDependencies
Not supported: Datadog's public API offers no service dependency graph.- Specified by:
getDependenciesin interfaceTraceQueryClient- Parameters:
start- ignoredend- ignored- Returns:
- never
- Throws:
UnsupportedException- always
-
waitForTrace
PollsgetTrace(String)every 2 s (Datadog allows 50 searches per minute) for up to 30 s until the trace has a span.- Specified by:
waitForTracein interfaceTraceQueryClient- Parameters:
traceId- trace id- Returns:
- the trace
- Throws:
TimeoutException- when it does not appear in time
-
ping
Authenticated round tripGET /api/v2/validate_keys(API key + application key).- Returns:
- latency
- Throws:
AuthenticationException- for invalid keys (Datadog answers 401 or 403)
-
pingAsync
Asynchronousping().- Returns:
- future latency
-
close
public void close()Releases connections; idempotent.- Specified by:
closein interfaceAutoCloseable
-
toString
-