Class: LogStash::PluginMetadata

Inherits:
Object
  • Object
show all
Includes:
Util::Loggable
Defined in:
lib/logstash/plugin_metadata.rb

Overview

‘PluginMetadata` provides a space to store key/value metadata about a plugin, typically metadata about external resources that can be gleaned during plugin registration.

Data should not be persisted across pipeline reloads, and should be cleaned up after a pipeline reload

- It MUST NOT be used to store processing state
- It SHOULD NOT be updated frequently.
- Individual metadata keys MUST be Symbols and SHOULD NOT be dynamically generated

USAGE FROM PLUGINS


Since we allow plugins to be updated, it is important to introduce bindings to new Logstash features in a way that doesn’t break when installed onto a Logstash that doesn’t have those features, e.g.:

~~~

plugin_metadata.set(:foo, bar) if defined?(plugin_metadata?)

~~~

Since:

  • 7.1

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initializePluginMetadata

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of PluginMetadata.

See Also:

  • LogStash::PluginMetadata.[LogStash[LogStash::PluginMetadata[LogStash::PluginMetadata#for_plugin(String)]

Since:

  • 7.1



81
82
83
# File 'lib/logstash/plugin_metadata.rb', line 81

def initialize
  @datastore = ThreadSafe::Cache.new
end

Class Method Details

.delete_for_plugin(plugin_id) ⇒ Boolean

Deletes, and then clears the contents of an existing PluginMetadata object for the given plugin id if one exists

Parameters:

  • plugin_id (String)

Returns:

  • (Boolean)

Since:

  • 7.1



65
66
67
68
69
# File 'lib/logstash/plugin_metadata.rb', line 65

def delete_for_plugin(plugin_id)
  logger.debug("Removing metadata for plugin #{plugin_id}")
  old_registry = @registry.delete(plugin_id)
  old_registry.clear unless old_registry.nil?
end

.exists?(plugin_id) ⇒ Boolean

Determine if we have an existing PluginMetadata object for the given plugin id This allows us to avoid creating a metadata object if we don’t already have one.

Parameters:

  • plugin_id (String)

Returns:

  • (Boolean)

Since:

  • 7.1



55
56
57
# File 'lib/logstash/plugin_metadata.rb', line 55

def exists?(plugin_id)
  @registry.key?(plugin_id)
end

.for_plugin(plugin_id) ⇒ PluginMetadata

Get the PluginMetadata object corresponding to the given plugin id

Parameters:

  • plugin_id (String)

Returns:

  • (PluginMetadata)

    : the metadata object for the provided ‘plugin_id`; if no metadata object exists, it will be created.

Since:

  • 7.1



44
45
46
# File 'lib/logstash/plugin_metadata.rb', line 44

def for_plugin(plugin_id)
  @registry.compute_if_absent(plugin_id) { PluginMetadata.new }
end

.reset!Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 7.1



73
74
75
# File 'lib/logstash/plugin_metadata.rb', line 73

def reset!
  @registry.clear
end

Instance Method Details

#clearObject

Clear all metadata keys for this plugin

Returns:

  • (Object)

Since:

  • 7.1



135
136
137
# File 'lib/logstash/plugin_metadata.rb', line 135

def clear
  @datastore.clear
end

#delete(key) ⇒ Object

Delete the metadata key for this plugin, returning the previous value (if any)

Parameters:

  • key (Symbol)

Returns:

  • (Object)

Since:

  • 7.1



127
128
129
# File 'lib/logstash/plugin_metadata.rb', line 127

def delete(key)
  @datastore.delete(key)
end

#get(key) ⇒ Object

Get the metadata value for the given key on this plugin

Parameters:

  • key (Symbol)

Returns:

  • (Object)

    : the value object associated with the given key on this plugin, or nil if no value is associated

Since:

  • 7.1



107
108
109
# File 'lib/logstash/plugin_metadata.rb', line 107

def get(key)
  @datastore.get(key)
end

#set(key, value) ⇒ Object

Set the metadata key for this plugin, returning the previous value (if any)

Parameters:

  • key (Symbol)
  • value (Object)

Returns:

  • (Object)

Since:

  • 7.1



92
93
94
95
96
97
98
# File 'lib/logstash/plugin_metadata.rb', line 92

def set(key, value)
  if value.nil?
    @datastore.delete(key)
  else
    @datastore.get_and_set(key, value)
  end
end

#set?(key) ⇒ Boolean

Determine whether specific key/value metadata exists for this plugin

Parameters:

  • key (Symbol)

    : the key

Returns:

  • (Boolean)

    : true if the plugin includes metadata for the key

Since:

  • 7.1



117
118
119
# File 'lib/logstash/plugin_metadata.rb', line 117

def set?(key)
  @datastore.key?(key)
end