Class DatadogLogsQuery
- All Implemented Interfaces:
LogQueryClient
searchLogs(codes.grow.packages.datadoglogs.SearchLogsRequest) (one page), iterateLogs(codes.grow.packages.datadoglogs.SearchLogsRequest) (cursor pagination), aggregateLogs(java.util.List<codes.grow.packages.datadoglogs.DatadogCompute>, java.util.List<codes.grow.packages.datadoglogs.DatadogGroupBy>, codes.grow.packages.datadoglogs.AggregateLogsOptions), listIndexes(), and the category LogQueryClient methods: search(java.lang.String, codes.grow.packages.datadoglogs.logging.SearchOptions), waitForLog(java.lang.String), tail(java.lang.String, java.util.function.Consumer<codes.grow.packages.datadoglogs.logging.LogRecord>, codes.grow.packages.datadoglogs.logging.TailOptions) (polling search: Datadog Live Tail has no public
API), listStreams() (index names, needs logs_read_config); listLabels()
throws UnsupportedException. Get it from DatadogLogsClient.query().
DatadogLogsQuery query = client.query();
DatadogLogsPage page = query.searchLogs(
SearchLogsRequest.builder().query("service:checkout").from("now-1h").limit(50).build());
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringAggregate path (POST).static final intPage size ofiterateLogs(codes.grow.packages.datadoglogs.SearchLogsRequest)when none is given.static final DurationPoll interval ofwaitForLog(String)(the Datadog search rate limit is low).static final intPage size ofsearchLogswhen none is given.static final StringIndexes path (GET).static final intLargest page size accepted by the search API.static final StringSearch path (POST).static final DurationHow far back each tail poll searches again before the newest seen log. -
Method Summary
Modifier and TypeMethodDescriptionaggregateLogs(DatadogCompute compute, List<DatadogGroupBy> groupBy) aggregateLogs(List<DatadogCompute> compute, List<DatadogGroupBy> groupBy, AggregateLogsOptions options) Computescompute(results keyedc0,c1, …) over the logs matching the filter, optionally grouped by facets (POST /api/v2/logs/analytics/aggregate).aggregateLogsAsync(List<DatadogCompute> compute, List<DatadogGroupBy> groupBy, AggregateLogsOptions options) iterateLogs(SearchLogsRequest request) Iterates over every matching event across pages (cursor pagination), lazily: each page is fetched when the previous one is consumed.Returns the log indexes (GET /api/v1/logs/config/indexes; needs thelogs_read_configpermission).AsynchronouslistIndexes().Datadog has no public API that lists facets or attributes.AsynchronousLogQueryClient.listLabels().Index names fromlistIndexes()(needs thelogs_read_configpermission).AsynchronousLogQueryClient.listStreams().search(String query, SearchOptions options) Category search: one page ofsearchLogs(codes.grow.packages.datadoglogs.SearchLogsRequest)(start/endtofrom/to, default the last 15 minutes;orderto the sort;cursortopage.cursor).searchAsync(String query, SearchOptions options) AsynchronousLogQueryClient.search(String, SearchOptions).searchLogs(SearchLogsRequest request) Returns one page of logs matching the request (POST /api/v2/logs/events/search).searchLogsAsync(SearchLogsRequest request) tail(String query, Consumer<LogRecord> onRecord, TailOptions options) Polling tail: searches everyoptions.interval()for logs matchingqueryfromoptions.start()(default now), oldest first, and callsonRecordonce per log id.waitForLog(String query) Pollssearch(java.lang.String, codes.grow.packages.datadoglogs.logging.SearchOptions)until a record matches (intervalDEFAULT_POLL_INTERVAL, timeout 30 s).waitForLogAsync(String query, WaitForLogOptions options) AsynchronousLogQueryClient.waitForLog(String, WaitForLogOptions).Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface codes.grow.packages.datadoglogs.logging.LogQueryClient
search, waitForLog
-
Field Details
-
SEARCH_PATH
Search path (POST).- See Also:
-
AGGREGATE_PATH
Aggregate path (POST).- See Also:
-
INDEXES_PATH
Indexes path (GET).- See Also:
-
MAX_PAGE_LIMIT
public static final int MAX_PAGE_LIMITLargest page size accepted by the search API.- See Also:
-
DEFAULT_SEARCH_LIMIT
public static final int DEFAULT_SEARCH_LIMITPage size ofsearchLogswhen none is given.- See Also:
-
DEFAULT_ITERATOR_PAGE_SIZE
public static final int DEFAULT_ITERATOR_PAGE_SIZEPage size ofiterateLogs(codes.grow.packages.datadoglogs.SearchLogsRequest)when none is given.- See Also:
-
DEFAULT_POLL_INTERVAL
Poll interval ofwaitForLog(String)(the Datadog search rate limit is low). -
TAIL_LAG
How far back each tail poll searches again before the newest seen log.
-
-
Method Details
-
searchLogs
Returns one page of logs matching the request (POST /api/v2/logs/events/search). PassDatadogLogsPage.nextCursor()back ascursor(with the same filter and sort) for the next page. Atimeoutstatus and warnings mean partial results and are returned, not raised.- Parameters:
request- filter, limit (1..5000, default 100), sort and cursor- Returns:
- the page
- Throws:
ValidationException- for a limit outside 1..5000AuthenticationException- for a missing, invalid or under-privileged key (401/403)UnavailableException- for an answer without adataarray
-
searchLogsAsync
- Parameters:
request- the request- Returns:
- a future with the page
-
iterateLogs
Iterates over every matching event across pages (cursor pagination), lazily: each page is fetched when the previous one is consumed. The request limit caps the total number of events (default all); a repeated cursor raisesUnavailableException(protocol loop guard). Errors are thrown fromhasNext()/next().for (DatadogLogEvent e : query.iterateLogs(SearchLogsRequest.of("status:error"))) { System.out.println(e.message()); }- Parameters:
request- filter, total limit, page size (1..5000, default min(limit, 1000)), sort- Returns:
- an iterable that can be iterated once per call of
iterator() - Throws:
ValidationException- for a non-positive limit or a page size outside 1..5000
-
aggregateLogs
public DatadogAggregateResult aggregateLogs(List<DatadogCompute> compute, List<DatadogGroupBy> groupBy, AggregateLogsOptions options) Computescompute(results keyedc0,c1, …) over the logs matching the filter, optionally grouped by facets (POST /api/v2/logs/analytics/aggregate).DatadogAggregateResult r = query.aggregateLogs( List.of(DatadogCompute.of("count")), List.of(DatadogGroupBy.of("service")), AggregateLogsOptions.builder().query("env:prod").build());- Parameters:
compute- one or more computations (not empty)groupBy- facets to group by (may be empty)options- filter and cursor- Returns:
- the buckets
- Throws:
ValidationException- whencomputeis empty
-
aggregateLogs
aggregateLogs(java.util.List<codes.grow.packages.datadoglogs.DatadogCompute>, java.util.List<codes.grow.packages.datadoglogs.DatadogGroupBy>, codes.grow.packages.datadoglogs.AggregateLogsOptions)of one compute over the default filter.- Parameters:
compute- the computationgroupBy- facets to group by- Returns:
- the buckets
-
aggregateLogsAsync
public CompletableFuture<DatadogAggregateResult> aggregateLogsAsync(List<DatadogCompute> compute, List<DatadogGroupBy> groupBy, AggregateLogsOptions options) - Parameters:
compute- computationsgroupBy- facetsoptions- filter and cursor- Returns:
- a future with the buckets
-
search
Category search: one page ofsearchLogs(codes.grow.packages.datadoglogs.SearchLogsRequest)(start/endtofrom/to, default the last 15 minutes;orderto the sort;cursortopage.cursor).totalis never set (Datadog returns none).- Specified by:
searchin interfaceLogQueryClient- Parameters:
query- Datadog search queryoptions- window, limit (at most 5000), order and cursor- Returns:
- the records and the next cursor
-
searchAsync
Description copied from interface:LogQueryClientAsynchronousLogQueryClient.search(String, SearchOptions).- Specified by:
searchAsyncin interfaceLogQueryClient- Parameters:
query- query textoptions- options- Returns:
- future page
-
listIndexes
Returns the log indexes (GET /api/v1/logs/config/indexes; needs thelogs_read_configpermission).- Returns:
- the indexes
- Throws:
UnavailableException- for an answer without anindexesarray
-
listIndexesAsync
AsynchronouslistIndexes().- Returns:
- a future with the indexes
-
listStreams
Index names fromlistIndexes()(needs thelogs_read_configpermission).- Specified by:
listStreamsin interfaceLogQueryClient- Returns:
- the names
-
listStreamsAsync
Description copied from interface:LogQueryClientAsynchronousLogQueryClient.listStreams().- Specified by:
listStreamsAsyncin interfaceLogQueryClient- Returns:
- future names
-
listLabels
Datadog has no public API that lists facets or attributes.- Specified by:
listLabelsin interfaceLogQueryClient- Returns:
- never
- Throws:
UnsupportedException- always
-
listLabelsAsync
Description copied from interface:LogQueryClientAsynchronousLogQueryClient.listLabels().- Specified by:
listLabelsAsyncin interfaceLogQueryClient- Returns:
- future names
-
waitForLog
Pollssearch(java.lang.String, codes.grow.packages.datadoglogs.logging.SearchOptions)until a record matches (intervalDEFAULT_POLL_INTERVAL, timeout 30 s). Authentication and validation errors propagate at once;TimeoutExceptionat the deadline.- Specified by:
waitForLogin interfaceLogQueryClient- Parameters:
query- Datadog search query, ideally with a run-unique marker- Returns:
- the first matching record
-
waitForLogAsync
Description copied from interface:LogQueryClientAsynchronousLogQueryClient.waitForLog(String, WaitForLogOptions).- Specified by:
waitForLogAsyncin interfaceLogQueryClient- Parameters:
query- query textoptions- options- Returns:
- future record
-
tail
public DatadogLogsQuery.DatadogLogTail tail(String query, Consumer<LogRecord> onRecord, TailOptions options) Polling tail: searches everyoptions.interval()for logs matchingqueryfromoptions.start()(default now), oldest first, and callsonRecordonce per log id. Retryable errors keep the tail polling; other errors go tooptions.onError()and end it.DatadogLogsClient.close()stops it. Mind the search rate limit (an interval of 5 s or more is recommended).- Specified by:
tailin interfaceLogQueryClient- Parameters:
query- Datadog search queryonRecord- callback, called from the tail threadoptions- start, interval and error callback- Returns:
- the running tail
-