Module: Systemd::Journal::Filterable

Included in:
Systemd::Journal
Defined in:
lib/systemd/journal/filterable.rb

Instance Method Summary collapse

Instance Method Details

#add_conjunction ⇒ nil

Add an AND condition to the filter. All previously added terms will be ANDed together with terms following the conjunction. Navigable#move_next or Navigable#move_previous must be invoked after adding a match before attempting to read from the journal.

Examples:

Filter entries returned using an AND condition

j = Systemd::Journal.new
j.add_filter('PRIORITY', 5)
j.add_conjunction
j.add_filter('_EXE', '/usr/bin/sshd')
while j.move_next
  # current_entry is an sshd event with priority 5
end

Returns:

  • (nil)

Raises:



94
95
96
97
98
99
 
# File 'lib/systemd/journal/filterable.rb', line 94

def add_conjunction
  @reopen_filter_conditions << :conjunction

  rc = Native.sd_journal_add_conjunction(@ptr)
  raise JournalError, rc if rc < 0
end

#add_disjunction ⇒ nil

Add an OR condition to the filter. All previously added matches will be ORed with the terms following the disjunction. Navigable#move_next or Navigable#move_previous must be invoked after adding a match before attempting to read from the journal.

Examples:

Filter entries returned using an OR condition

j = Systemd::Journal.new
j.add_filter('PRIORITY', 5)
j.add_disjunction
j.add_filter('_EXE', '/usr/bin/sshd')
while j.move_next
  # current_entry is either an sshd event or
  # has priority 5
end

Returns:

  • (nil)

Raises:



74
75
76
77
78
79
 
# File 'lib/systemd/journal/filterable.rb', line 74

def add_disjunction
  @reopen_filter_conditions << :disjunction

  rc = Native.sd_journal_add_disjunction(@ptr)
  raise JournalError, rc if rc < 0
end

#add_filter(field, value) ⇒ nil

Add a filter to journal, such that only entries where the given filter matches are returned. Navigable#move_next or Navigable#move_previous must be invoked after adding a filter before attempting to read from the journal.

Parameters:

  • field (String) —

    the column to filter on, e.g. _PID, _EXE.

  • value (String) —

    the match to search for, e.g. ‘/usr/bin/sshd’

Returns:

  • (nil)

Raises:



38
39
40
41
42
43
44
 
# File 'lib/systemd/journal/filterable.rb', line 38

def add_filter(field, value)
  @reopen_filter_conditions << {field => value}

  match = "#{field.to_s.upcase}=#{value}"
  rc = Native.sd_journal_add_match(@ptr, match, match.length)
  raise JournalError, rc if rc < 0
end

#add_filters(filters) ⇒ Object

Add a set of filters to the journal, such that only entries where the given filters match are returned.

Examples:

Filter by PID and EXE

j.add_filters(_pid: 6700, _exe: '/usr/bin/sshd')

Parameters:

  • filters (Hash) —

    a set of field/filter value pairs. If the filter value is an array, each value in the array is added and entries where the specified field matches any of the values is returned.



54
55
56
57
58
 
# File 'lib/systemd/journal/filterable.rb', line 54

def add_filters(filters)
  filters.each do |field, value|
    Array(value).each { |v| add_filter(field, v) }
  end
end

#clear_filters ⇒ nil

Remove all filters and conjunctions/disjunctions.

Returns:

  • (nil) 


103
104
105
106
107
 
# File 'lib/systemd/journal/filterable.rb', line 103

def clear_filters
  @reopen_filter_conditions = []

  Native.sd_journal_flush_matches(@ptr)
end

#filter(*conditions) ⇒ Object

Filter the journal at a high level. Takes any number of arguments; each argument should be a hash representing a condition to filter based on. Fields inside the hash will be ANDed together. Each hash will be ORed with the others. Fields in hashes with Arrays as values are treated as an OR statement, since otherwise they would never match.

Examples:

j = Systemd::Journal.filter(
  {_systemd_unit: 'session-4.scope'},
  {priority: [4, 6]},
  {_exe: '/usr/bin/sshd', priority: 1}
)
# equivalent to
(_systemd_unit == 'session-4.scope') ||
(priority == 4 || priority == 6)     ||
(_exe == '/usr/bin/sshd' && priority == 1)


20
21
22
23
24
25
26
27
28
29
 
# File 'lib/systemd/journal/filterable.rb', line 20

def filter(*conditions)
  clear_filters

  last_index = conditions.length - 1

  conditions.each_with_index do |condition, index|
    add_filters(condition)
    add_disjunction unless index == last_index
  end
end