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

POST https://chronicle.googleapis.com/v1alpha/{instance}:searchRawLogs

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 
{
  "baseline_query": string,
  "baseline_time_range": {
    object (Interval)
  },
  "snapshot_query": string,
  "snapshot_time_range": {
    object (Interval)
  },
  "case_sensitive": boolean,
  "log_types": [
    {
      object (LogType)
    }
  ],
  "max_aggregations_per_field": integer,
  "page_size": integer
}
Fields
baseline_query

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.
baseline_time_range

object (Interval)

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

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.
snapshot_time_range

object (Interval)

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

boolean

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

object (LogType)

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

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 max_values_per_field the top (max_values_per_field/2) values and the bottom (max_values_per_field/2) values by prevalence will be sent instead.
page_size

integer

Optional. The maximum number of results to return.

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)
  },
  "next_page_token": 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.
next_page_token

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,
  "log_type": {
    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.
log_type

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,
  "ingestion_time": string
}
Fields
id

string (bytes format)

ID of the raw log.

A base64-encoded string.
snippet

string

Snippet of the raw log.
ingestion_time

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)
    }
  ],
  "bucket_size": string
}
Fields
buckets[]

object (EventTimelineBucket)

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

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 
{
  "baseline_parsed_log_count": integer,
  "parsed_log_count": integer,
  "baseline_unparsed_log_count": integer,
  "unparsed_log_count": integer,
  "too_many_events": boolean,
  "baseline_event_count": integer,
  "event_count": integer,
  "baseline_entity_count": integer,
  "entity_count": integer
}
Fields
baseline_parsed_log_count

integer

Number of parsed logs in the baseline results.
parsed_log_count

integer

Number of parsed logs in the filtered results.
baseline_unparsed_log_count

integer

Number of unparsed logs in the baseline results.
unparsed_log_count

integer

Number of unparsed logs in the filtered results.
too_many_events

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.
baseline_event_count

integer

Number of events in the baseline results.
event_count

integer

Number of events in the filtered results.
baseline_entity_count

integer

Number of context events in the baseline results.
entity_count

integer

Number of context events in the filtered results.

Aggregations

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

JSON representation 
{
  "udm_field_aggregations": [
    {
      object (FieldAggregation)
    }
  ],
  "group_field_aggregations": [
    {
      object (FieldAggregation)
    }
  ],
  "entity_field_aggregations": [
    {
      object (FieldAggregation)
    }
  ],
  "raw_log_aggregations": [
    {
      object (FieldAggregation)
    }
  ]
}
Fields
udm_field_aggregations[]

object (FieldAggregation)

List of UDM fields with aggregated values.
group_field_aggregations[]

object (FieldAggregation)

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

object (FieldAggregation)

List of entity fields with aggregated values.
raw_log_aggregations[]

object (FieldAggregation)

List of raw logs with aggregated values.

FieldAggregation

All of the field values and their counts.

JSON representation 
{
  "field": string,
  "baseline_count": integer,
  "count": integer,
  "too_many_values": boolean,
  "value_count": integer,
  "all_values": [
    {
      object (ValueCount)
    }
  ],
  "top_values": [
    {
      object (ValueCount)
    }
  ],
  "bottom_values": [
    {
      object (ValueCount)
    }
  ]
}
Fields
field

string

Name of the field being aggregated.
baseline_count

integer

Number of baseline results with this field.
count

integer

Number of filtered results with this field.
too_many_values

boolean

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

integer

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

object (ValueCount)

Populated with all events if too_many_values is False.
top_values[]

object (ValueCount)

Populated with the top N/2 events if too_many_values is True. N is defined by max_aggregations_per_field.
bottom_values[]

object (ValueCount)

Populated with the bottom N/2 events if too_many_values is True. N is defined by max_aggregations_per_field.

ValueCount

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

JSON representation 
{
  "value": {
    object (FieldValue)
  },
  "baseline_result_count": integer,
  "result_count": integer
}
Fields
value

object (FieldValue)

Value of the field.
baseline_result_count

integer

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

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:
  "string_value": string,
  "int32_value": integer,
  "uint32_value": integer,
  "int64_value": string,
  "uint64_value": string,
  "float_value": number,
  "double_value": number,
  "enum_value": string,
  "bool_value": boolean,
  "bytes_value": string,
  "is_null": boolean,
  "timestamp_value": 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:
string_value

string

The value of a string field.
int32_value

integer

The value of a 32-bit integer field.
uint32_value

integer (uint32 format)

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

string (int64 format)

The value of a 64-bit integer field.
uint64_value

string

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

number

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

number

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

string

The value of an enum field.
bool_value

boolean

The value of a boolean field.
bytes_value

string (bytes format)

The value of a bytes field.

A base64-encoded string.
is_null

boolean

If true, the value is NULL.
timestamp_value

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".