Method: instances.searchRawLogs

Full name: projects.locations.instances.searchRawLogs

Api to get events, entities, or unparsed raw logs matching the given raw log query. This api also returns the timeline, field aggregations over the results.

HTTP request


Path parameters

Parameters
instance

string

Required. Chronicle instance this request is sent to. Format: projects/{project}/locations/{location}/instances/{instance}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "baselineQuery": string,
  "baselineTimeRange": {
    object (Interval)
  },
  "snapshotQuery": string,
  "snapshotTimeRange": {
    object (Interval)
  },
  "caseSensitive": boolean,
  "logTypes": [
    {
      object (LogType)
    }
  ],
  "maxAggregationsPerField": integer,
  "pageSize": integer,
  "draftDataAccessScope": {
    object (DataAccessScope)
  }
}
Fields
baselineQuery

string

Required. Query to search for raw logs. Any matches will be returned in the normalized form or raw log snippet if they can't be normalized.
baselineTimeRange

object (Interval)

Required. The time range to search for [inclusive, exclusive).
snapshotQuery

string

Optional. Query to filter results. This is applied on top of the baseline query and doesn't fetch results outside of the baseline results restricted to the result limit.
snapshotTimeRange

object (Interval)

Optional. The time range to filter results [inclusive, exclusive). This time range must // be completely within baselineTimeRange. If not set, it is assumed to match baselineTimeRange.
caseSensitive

boolean

Optional. If true, the search should be performed in a case-sensitive manner. This applies to both baseline and snapshot queries.
logTypes[]

object (LogType)

Optional. If present, limit the result to the matching log types.
maxAggregationsPerField

integer

Optional. The maximum number of values a UDM field can have before resorting to only show the top and bottom values by prevalence. If the number of values is greater than maxValuesPerField the top (maxValuesPerField/2) values and the bottom (maxValuesPerField/2) values by prevalence will be sent instead.
pageSize

integer

Optional. The maximum number of results to return.
draftDataAccessScope

object (DataAccessScope)

Optional. Data access scope used to filter events. This is intended to be used by admins to preview in-development scopes. Should only be called by users with global access. If the caller does not have global access, the request will fail.

Response body

Response to SearchRawLogsRequest. Contains all the matches converted to normalized form when available, histogram of logs over time, field aggregations for top/bottom fields in all result types.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "matches": [
    {
      object (RawLogResult)
    }
  ],
  "progress": integer,
  "timeline": {
    object (EventTimeline)
  },
  "aggregations": {
    object (Aggregations)
  },
  "nextPageToken": string
}
Fields
matches[]

object (RawLogResult)

Results that match the raw log search.
progress

integer

Progress of the query represented as a percentage between 0 and 100.
timeline

object (EventTimeline)

Timeline of results counts broken into buckets.
aggregations

object (Aggregations)

Result fields with aggregated values.
nextPageToken

string

Currently, this field is used only to indicate whether more value matches are available. If it is empty, there are no more value matches.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the instance resource:

  • chronicle.events.searchRawLogs

For more information, see the IAM documentation.

RawLogResult

RawLogResult contains a single result match that is one of unparsed raw log, telemetry event, or entity context event. Along with that this contains summary, id, logType of the log that generated the result.

JSON representation 
{
  "summary": string,
  "id": string,
  "logType": {
    object (LogType)
  },

  // Union field result can be only one of the following:
  "event": {
    object (Event)
  },
  "entity": {
    object (Entity)
  },
  "snippet": {
    object (RawLogSnippet)
  }
  // End of list of possible types for union field result.
}
Fields
summary

string

If the result is unparsed log, summary will be a snippet for unparsed raw log. If the result is a telemetry event or a context event, it will be a description of the event.
id

string (bytes format)

Id for raw log / entity / event result.

A base64-encoded string.
logType

object (LogType)

Log type of the result.

Union field result.

result can be only one of the following:
event

object (Event)

Normalized UDM event from the raw log that matched search query.
entity

object (Entity)

Normalized entity context event from the raw log that matched search query.
snippet

object (RawLogSnippet)

Raw log snippet in case of unparsed log.

RawLogSnippet

RawLog contains raw log id, ingestion time, and a snippet of the log.

JSON representation 
{
  "id": string,
  "snippet": string,
  "ingestionTime": string
}
Fields
id

string (bytes format)

ID of the raw log.

A base64-encoded string.
snippet

string

Snippet of the raw log.
ingestionTime

string (Timestamp format)

Ingestion time of the raw log.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

EventTimeline

Timeline of results counts broken into buckets.

JSON representation 
{
  "buckets": [
    {
      object (EventTimelineBucket)
    }
  ],
  "bucketSize": string
}
Fields
buckets[]

object (EventTimelineBucket)

Complete list of buckets that represent the entire search window. Each bucket with duration of bucketSize. Time window of each bucket is [inclusive, exclusive).
bucketSize

string (Duration format)

Duration of each timeline bucket.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

EventTimelineBucket

Represents a single time bucket containing number of parsed, unparsed logs in baseline and filtered results.

JSON representation 
{
  "baselineParsedLogCount": integer,
  "parsedLogCount": integer,
  "baselineUnparsedLogCount": integer,
  "unparsedLogCount": integer,
  "tooManyEvents": boolean,
  "baselineEventCount": integer,
  "eventCount": integer,
  "baselineEntityCount": integer,
  "entityCount": integer
}
Fields
baselineParsedLogCount

integer

Number of parsed logs in the baseline results.
parsedLogCount

integer

Number of parsed logs in the filtered results.
baselineUnparsedLogCount

integer

Number of unparsed logs in the baseline results.
unparsedLogCount

integer

Number of unparsed logs in the filtered results.
tooManyEvents

boolean

Indicates that the bucket has events that couldn't be displayed due to event limits. If the flag is true and the other counters are > 0, it indicates that we reached the limit and had to truncate the results. If the counters are 0 and the flag is set, it indicates that there are >0 events in this bucket that couldn't be fetched due to limit being reached by other buckets.
baselineEventCount

integer

Number of events in the baseline results.
eventCount

integer

Number of events in the filtered results.
baselineEntityCount

integer

Number of context events in the baseline results.
entityCount

integer

Number of context events in the filtered results.

Aggregations

Aggregations contains field aggregations for udm, entity, raw log, and grouped fields.

JSON representation 
{
  "udmFieldAggregations": [
    {
      object (FieldAggregation)
    }
  ],
  "groupFieldAggregations": [
    {
      object (FieldAggregation)
    }
  ],
  "entityFieldAggregations": [
    {
      object (FieldAggregation)
    }
  ],
  "rawLogAggregations": [
    {
      object (FieldAggregation)
    }
  ]
}
Fields
udmFieldAggregations[]

object (FieldAggregation)

List of UDM fields with aggregated values.
groupFieldAggregations[]

object (FieldAggregation)

List of grouped UDM fields with aggregated values.
entityFieldAggregations[]

object (FieldAggregation)

List of entity fields with aggregated values.
rawLogAggregations[]

object (FieldAggregation)

List of raw logs with aggregated values.

FieldAggregation

All of the field values and their counts.

JSON representation 
{
  "field": string,
  "baselineCount": integer,
  "count": integer,
  "tooManyValues": boolean,
  "valueCount": integer,
  "allValues": [
    {
      object (ValueCount)
    }
  ],
  "topValues": [
    {
      object (ValueCount)
    }
  ],
  "bottomValues": [
    {
      object (ValueCount)
    }
  ]
}
Fields
field

string

Name of the field being aggregated.
baselineCount

integer

Number of baseline results with this field.
count

integer

Number of filtered results with this field.
tooManyValues

boolean

True, if there are too many values to be returned for this field.
valueCount

integer

Number of values with non-zero result count for this field.
allValues[]

object (ValueCount)

Populated with all events if tooManyValues is False.
topValues[]

object (ValueCount)

Populated with the top N/2 events if tooManyValues is True. N is defined by maxAggregationsPerField.
bottomValues[]

object (ValueCount)

Populated with the bottom N/2 events if tooManyValues is True. N is defined by maxAggregationsPerField.

ValueCount

The number of times a particular field value appears in the results.

JSON representation 
{
  "value": {
    object (FieldValue)
  },
  "baselineResultCount": integer,
  "resultCount": integer
}
Fields
value

object (FieldValue)

Value of the field.
baselineResultCount

integer

Number of events with value for this field in the baseline results.
resultCount

integer

Number of events with value for this field in the snapshot results.

FieldValue

The value of a field.

JSON representation 
{

  // Union field value can be only one of the following:
  "stringValue": string,
  "int32Value": integer,
  "uint32Value": integer,
  "int64Value": string,
  "uint64Value": string,
  "floatValue": number,
  "doubleValue": number,
  "enumValue": string,
  "boolValue": boolean,
  "bytesValue": string,
  "isNull": boolean,
  "timestampValue": string
  // End of list of possible types for union field value.
}
Fields
Union field value. The value of the field. value can be only one of the following:
stringValue

string

The value of a string field.
int32Value

integer

The value of a 32-bit integer field.
uint32Value

integer (uint32 format)

The value of a 32-bit unsigned integer field.
int64Value

string (int64 format)

The value of a 64-bit integer field.
uint64Value

string

The value of a 64-bit unsigned integer field.
floatValue

number

The value of a single-precision floating-point field.
doubleValue

number

The value of a double-precision floating-point field.
enumValue

string

The value of an enum field.
boolValue

boolean

The value of a boolean field.
bytesValue

string (bytes format)

The value of a bytes field.

A base64-encoded string.
isNull

boolean

If true, the value is NULL.
timestampValue

string (Timestamp format)

The value of a timestamp field.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".