Class CloudWatchLogsQueryClient

java.lang.Object
codes.grow.packages.cloudwatchlogs.CloudWatchLogsQueryClient
All Implemented Interfaces:
LogQueryClient

public final class CloudWatchLogsQueryClient extends Object implements LogQueryClient
LogQueryClient over one log group (SPEC section 4, DECISIONS 2). search uses FilterLogEvents: SortOrder.ASC reads natively (oldest first, cursor = the service token); SortOrder.DESC (default) walks the time window backwards in slices (5 minutes, each 4 times wider), from one hour before the group's creation time (else 30 days), newest slice first, and sorts each slice newest first. tail uses Live Tail; listStreams uses DescribeLogStreams; listLabels is unsupported (no label inventory).
  • Field Details

    • ATTR_LOG_STREAM

      public static final String ATTR_LOG_STREAM
      Attribute holding the log stream of a record.
      See Also:
    • ATTR_EVENT_ID

      public static final String ATTR_EVENT_ID
      Attribute holding the event id of a record.
      See Also:
    • ATTR_LOG_GROUP

      public static final String ATTR_LOG_GROUP
      Attribute holding the log group of a plain live-tail record.
      See Also:
    • DEFAULT_SEARCH_LOOKBACK_MS

      public static final long DEFAULT_SEARCH_LOOKBACK_MS
      Look-back of a descending search without start when the creation time is unknown (30 d).
      See Also:
    • SEARCH_FIRST_SLICE_MS

      public static final long SEARCH_FIRST_SLICE_MS
      First time slice of a descending search (5 minutes); each further slice is 4 times wider.
      See Also:
    • SEARCH_MAX_SLICE_MS

      public static final long SEARCH_MAX_SLICE_MS
      Largest time slice of a descending search (30 days).
      See Also:
    • SEARCH_SCAN_CAP

      public static final int SEARCH_SCAN_CAP
      Events read per slice before the slice is narrowed (newest half kept).
      See Also:
    • MAX_SEARCH_LIMIT

      public static final int MAX_SEARCH_LIMIT
      Largest page size of search.
      See Also:
  • Method Details

    • group

      public String group()
      Returns the log group searched.
      Returns:
      the group
    • filterPattern

      public static String filterPattern(String query)
      Converts a search query to a CloudWatch filter pattern: empty matches everything; a query that starts with {, ?, [, - or " is passed through as a native pattern; anything else becomes an exact phrase ("…", inner quotes escaped).
      Parameters:
      query - the query
      Returns:
      the filter pattern
    • messageToRecord

      public static LogRecord messageToRecord(String message, Instant timestamp, Instant ingestionTime)
      Normalizes a CloudWatch message: a normalized LogRecord JSON document (with timestamp and body) is decoded; any other message becomes an INFO record with the message as body, timestamp as time and ingestionTime as observed time.
      Parameters:
      message - the message
      timestamp - event time
      ingestionTime - ingestion time, may be null
      Returns:
      the record
    • filteredEventToRecord

      public static LogRecord filteredEventToRecord(FilteredLogEvent e)
      Converts a FilterLogEvents event to a record (see messageToRecord(java.lang.String, java.time.Instant, java.time.Instant)) with the attributes aws.log.stream and aws.event.id.
      Parameters:
      e - the event
      Returns:
      the record
    • liveTailEventToRecord

      public static LogRecord liveTailEventToRecord(LiveTailEvent e)
      Converts a live-tail event to a record (see messageToRecord(java.lang.String, java.time.Instant, java.time.Instant)) with the attribute aws.log.stream and, for plain messages, aws.log.group.
      Parameters:
      e - the event
      Returns:
      the record
    • search

      public LogSearchResult search(String query, SearchOptions options)
      Description copied from interface: LogQueryClient
      Searches records matching a service query (full text or the service's query language).
      Specified by:
      search in interface LogQueryClient
      Parameters:
      query - query text
      options - range, limit, order, cursor
      Returns:
      one page of records
    • tail

      public TailHandle tail(String query, Consumer<LogRecord> onRecord, TailOptions options)
      Streams records with Live Tail (filter pattern built like search(java.lang.String, codes.grow.packages.cloudwatchlogs.logging.SearchOptions)). Errors and the end of the session are reported to options.onError; start and interval do not apply (the service pushes events).
      Specified by:
      tail in interface LogQueryClient
      Parameters:
      query - search query
      onRecord - called for every record
      options - error callback
      Returns:
      a handle that stops the session
    • listStreams

      public List<String> listStreams()
      Names of the streams of the group (DescribeLogStreams, all pages).
      Specified by:
      listStreams in interface LogQueryClient
      Returns:
      the stream names
    • listLabels

      public List<String> listLabels()
      Always throws: CloudWatch Logs has no label inventory.
      Specified by:
      listLabels in interface LogQueryClient
      Returns:
      never returns
      Throws:
      UnsupportedException - always