graylog_search v1.0.1 GraylogSearch View Source

GraylogSearch constructs search queries in a composable manner.

It more or less follows Graylog's search query language.

Basic Usage

All queries start with a base URL to the graylog instance.

GraylogSearch.new("https://graylog.example.com")

And end with requesting the constructed URL.

GraylogSearch.url()

In between the start and end, the query can be composed in various ways.

GraylogSearch.new("https://graylog.example.com")
|> GraylogSearch.for("message", "ssh login")
|> GraylogSearch.and_for("hostname", "service*.example.com")
|> GraylogSearch.minutes_ago(5)
|> GraylogSearch.url()

See the API docs below for other ways to construct a query.

Link to this section Summary

API - Generic

new(url)

Given a base URL to the Graylog instance (i.e. scheme and host name, no path or query string), returns a URI for GraylogSearch pipelines.

show_fields(uri, fields)

Includes the given fields in the message results.

url(uri)

Returns a URL to perform the search

API - Boolean operators

and_for(uri, query)

Aliases for/2

and_for(uri, field, query)

Aliases for/3

and_not(uri, query)

Aliases not_for/2

and_not(uri, field, query)

Aliases not_for/3

for(uri, query)

Search for a message by the given query term or phrase. This function can be chained to combine queries with AND.

for(uri, field, query)

Searches for a term or phrase in a specific message field.

not_for(uri, query)

Search for messages that do not include a term or phrase.

not_for(uri, field, query)

Searches for messages that do not include a term or phrase in a specific field.

or_for(uri, query)

Search messages by another term or phrase.

or_for(uri, field, query)

Searches for another term or phrase in a specific message field.

API - Time frames

between(uri, from, to)

Search messages within an absolute time range.

days_ago(uri, n)

Search messages with a relative time range in days.

hours_ago(uri, n)

Search messages with a relative time range in hours.

minutes_ago(uri, n)

Search messages with a relative time range in minutes.

within(uri, date_expression)

Search messages within a time range specified by natural language.

Link to this section API - Generic

new(url)

Specs

new(String.t()) :: URI.t()

Given a base URL to the Graylog instance (i.e. scheme and host name, no path or query string), returns a URI for GraylogSearch pipelines.

show_fields(uri, fields)

Specs

show_fields(URI.t(), [atom()]) :: URI.t()

Includes the given fields in the message results.

Requires extractors to exist for the fields being specified.

url(uri)

Specs

url(URI.t() | {:error, atom()}) :: String.t() | {:error, atom()}

Returns a URL to perform the search

Link to this section API - Boolean operators

and_for(uri, query)

Specs

and_for(URI.t(), String.t()) :: URI.t()

Aliases for/2

and_for(uri, field, query)

Specs

and_for(URI.t(), atom(), String.t()) :: URI.t()

Aliases for/3

and_not(uri, query)

Aliases not_for/2

and_not(uri, field, query)

Aliases not_for/3

for(uri, query)

Specs

for(URI.t(), String.t()) :: URI.t()

Search for a message by the given query term or phrase. This function can be chained to combine queries with AND.

By default, all fields are included in the search when a field to search in is not specified.

for(uri, field, query)

Specs

for(URI.t(), atom(), String.t()) :: URI.t()

Searches for a term or phrase in a specific message field.

Unlike for/2 which searches all message fields.

not_for(uri, query)

Specs

not_for(URI.t(), String.t()) :: URI.t()

Search for messages that do not include a term or phrase.

Uses the NOT operator. Can be chained to combine queries with AND NOT.

not_for(uri, field, query)

Specs

not_for(URI.t(), atom(), String.t()) :: URI.t()

Searches for messages that do not include a term or phrase in a specific field.

Unlike not_for/2 which searches all message fields.

or_for(uri, query)

Specs

or_for(URI.t(), String.t()) :: URI.t()

Search messages by another term or phrase.

Uses the OR operator to combine queries.

or_for(uri, field, query)

Specs

or_for(URI.t(), atom(), String.t()) :: URI.t()

Searches for another term or phrase in a specific message field.

Unlike or_for/2 which searches all message fields.

Link to this section API - Time frames

between(uri, from, to)

Specs

between(URI.t(), String.t(), String.t()) :: URI.t() | {:error, atom()}

between(URI.t(), DateTime.t(), DateTime.t()) :: URI.t()

between(URI.t(), NaiveDateTime.t(), NaiveDateTime.t()) :: URI.t()

Search messages within an absolute time range.

Datetimes expected to be UTC in ISO 8601 format.

days_ago(uri, n)

Specs

days_ago(URI.t(), pos_integer()) :: URI.t()

Search messages with a relative time range in days.

From the given amount of days ago to the time the search is performed.

hours_ago(uri, n)

Specs

hours_ago(URI.t(), pos_integer()) :: URI.t()

Search messages with a relative time range in hours.

From the given amount of hours ago to the time the search is performed.

minutes_ago(uri, n)

Specs

minutes_ago(URI.t(), pos_integer()) :: URI.t()

Search messages with a relative time range in minutes.

From the given amount of minutes ago to the time the search is performed.

within(uri, date_expression)

Specs

within(URI.t(), String.t()) :: URI.t()

Search messages within a time range specified by natural language.

Consult the natty natural language parser for details on supported date/time formats.