logstash-integration-snmp 4.4.1-java → 4.5.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66b6d3ed64fef4ea132eb28af384a760e37a7329e9d37b7246fda9dcbdf7ef6e
-  data.tar.gz: e889f678af61a031038e5ee1264f7a9ecf56e023f71a4473015a364223934534
+  metadata.gz: de5f1db167874981118fb7f26f3c5c60f68c0f1e8254201328960057e6f7ffd3
+  data.tar.gz: 98ea051464282e1ac1d9633f5c21bc5014aa3a9e9b8a4458bc2ab71d7c8067e5
 SHA512:
-  metadata.gz: 45a570a9cbc17e81139c45ecaa4418c5cc001becfb591798e07e159919b9d253c2f5b80ee61f6b908a5e25de8ea1b417b3790604d68842a51938aff5b79c2636
-  data.tar.gz: baba3b6c0be0212e7765a63b81bdcdf6a844e4f2ad3c4516a84cd9352ef6c39cade73e8df553c95ea1b5275b471beac62c532c205f8d59c02c36c6703eb1fdde
+  metadata.gz: b7c8077ac31d32e5e3dff1f792381f12051f71ce5f697d39bcc3a20cb0dfe29e853e9f2464166b42235c9f873c00315907317cf4cd0e7860352584edbe72407f
+  data.tar.gz: bc5d5cddb8f70b44cba17303def6e912c72ef7348724fafd66d97290b34924bd67dcc8af60209d89afc96e5025b90f9337f2c6792e4cb84c30612f078c227ff2

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.5.0
+  - Add `map_enum_values` option to replace integer values that have a MIB named-number (enum) definition with their textual name. [#99](https://github.com/logstash-plugins/logstash-integration-snmp/pull/99)
+  - Add `split_tables` option to emit one event per `tables` row instead of a single aggregated event. [#100](https://github.com/logstash-plugins/logstash-integration-snmp/pull/100)
+
 ## 4.4.1
   - Fix that avoids random null fields on table read. [#98](https://github.com/logstash-plugins/logstash-integration-snmp/pull/98)
 

data/VERSION

@@ -1 +1 @@
-4.4.1
+4.5.0

data/docs/input-snmp.asciidoc

@@ -78,6 +78,7 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-allow_partial_response>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-interval>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-local_engine_id>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-map_enum_values>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-max_repetitions>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-mib_paths>> |<<path,path>>|No
 | <<plugins-{type}s-{plugin}-oid_mapping_format>> |<<string,string>>, one of `["default", "ruby_snmp", "dotted_string"]`|No
@@ -87,6 +88,7 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-poll_hosts_timeout>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-tag_on_failure>> |<<array,array>>|No
 | <<plugins-{type}s-{plugin}-walk>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-split_tables>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-tables>> |<<array,array>>|No
 | <<plugins-{type}s-{plugin}-target>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-threads>> |<<number,number>>|No
@@ -244,6 +246,15 @@ input {
 }
 -----
 
+[id="plugins-{type}s-{plugin}-map_enum_values"]
+===== `map_enum_values`
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+When enabled, integer values that have a named-number (enum) definition in the loaded MIBs
+are replaced with their textual name (for example, `ifOperStatus` `1` becomes `"up"`).
+
 [id="plugins-{type}s-{plugin}-mib_paths"]
 ===== `mib_paths`
 
@@ -397,6 +408,20 @@ filter {
 }
 -----
 
+[id="plugins-{type}s-{plugin}-split_tables"]
+===== `split_tables`
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+When enabled, each <<plugins-{type}s-{plugin}-tables>> row is emitted as its own event
+instead of a single aggregated event. This is equivalent to using a `split` filter on the table
+field.
+
+The `get` and `walk` fields from the same poll are copied onto every row event. Keep them to
+device-level values, such as the `system` group. Walking table data (for example `ifTable`)
+alongside `split_tables` copies every row's walked values onto every row event.
+
 [id="plugins-{type}s-{plugin}-tables"]
 ===== `tables`
 

data/docs/input-snmptrap.asciidoc

@@ -94,6 +94,7 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-community>> |<<array,array>>|No
 | <<plugins-{type}s-{plugin}-ecs_compatibility>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-host>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-map_enum_values>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-mib_paths>> |<<path,path>>|No
 | <<plugins-{type}s-{plugin}-oid_mapping_format>> |<<string,string>>, one of `["default", "ruby_snmp", "dotted_string"]`|No
 | <<plugins-{type}s-{plugin}-oid_map_field_values>> |<<boolean,boolean>>|Yes
@@ -180,6 +181,15 @@ Controls this plugin's compatibility with the {ecs-ref}[Elastic Common Schema (E
 
 The address to listen on.
 
+[id="plugins-{type}s-{plugin}-map_enum_values"]
+===== `map_enum_values`
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+When enabled, integer values that have a named-number (enum) definition in the loaded MIBs
+are replaced with their textual name (for example, `ifOperStatus` `1` becomes `"up"`).
+
 [id="plugins-{type}s-{plugin}-mib_paths"]
 ===== `mib_paths`
 

data/lib/logstash/inputs/snmp.rb

@@ -79,6 +79,10 @@ class LogStash::Inputs::Snmp < LogStash::Inputs::Base
   # When disabled, only data from fully successful operations is included.
   config :allow_partial_response, :validate => :boolean, :default => false
 
+  # When enabled, emits one event per `tables` row instead of a single aggregated event.
+  # Each row event carries the `get`/`walk` scalar fields. Equivalent to using a `split` filter.
+  config :split_tables, :validate => :boolean, :default => false
+
   def initialize(params={})
     super(params)
 
@@ -97,6 +101,8 @@ class LogStash::Inputs::Snmp < LogStash::Inputs::Base
   def register
     validate_config!
 
+    @table_names = Array(@tables).map { |table_entry| table_entry['name'] }
+
     mib_manager = build_mib_manager!
 
     # setup client definitions per provided host
@@ -200,17 +206,15 @@ class LogStash::Inputs::Snmp < LogStash::Inputs::Base
       definition = req[:definition]
       result_consumer = lambda do |request_result|
         result = request_result.data
-        if result&.any? || request_result.has_errors
-          event = targeted_event_factory.new_event(result)
-          event.set(@host_protocol_field, definition[:host_protocol])
-          event.set(@host_address_field, definition[:host_address])
-          event.set(@host_port_field, definition[:host_port])
-          event.set(@host_community_field, definition[:host_community])
-          decorate(event)
-          @tag_on_failure.each { |tag| event.tag(tag) } if request_result.has_errors
-          queue << event
-        else
+        unless result&.any? || request_result.has_errors
           logger.debug? && logger.debug('No SNMP data retrieved', host: definition[:host_address])
+          next
+        end
+
+        if @split_tables && @table_names.any?
+          emit_split_table_events(queue, definition, request_result, result)
+        else
+          emit_event(queue, definition, request_result, result)
         end
       end
 
@@ -225,6 +229,37 @@ class LogStash::Inputs::Snmp < LogStash::Inputs::Base
     end
   end
 
+  def emit_event(queue, definition, request_result, fields)
+    event = targeted_event_factory.new_event(fields)
+    event.set(@host_protocol_field, definition[:host_protocol])
+    event.set(@host_address_field, definition[:host_address])
+    event.set(@host_port_field, definition[:host_port])
+    event.set(@host_community_field, definition[:host_community])
+    decorate(event)
+    @tag_on_failure.each { |tag| event.tag(tag) } if request_result.has_errors
+    queue << event
+  end
+
+  # Splits `tables` results into one event per row, keeping the `get`/`walk` scalar fields
+  # on each row event. With no rows, scalar data or a failed poll is emitted as a single event.
+  def emit_split_table_events(queue, definition, request_result, result)
+    scalars = {}
+    tables = {}
+    result.each do |key, value|
+      (@table_names.include?(key) ? tables : scalars)[key] = value
+    end
+
+    emitted = false
+    tables.each do |name, rows|
+      rows.each do |row|
+        emit_event(queue, definition, request_result, scalars.merge(name => row))
+        emitted = true
+      end
+    end
+
+    emit_event(queue, definition, request_result, scalars) if !emitted && (scalars.any? || request_result.has_errors)
+  end
+
   def poll_hosts_timeout(max_host_timeout)
     return @poll_hosts_timeout if @poll_hosts_timeout
 

data/lib/logstash/plugin_mixins/snmp/common.rb

@@ -52,6 +52,10 @@ module LogStash
           # set on the `oid_mapping_format`.
           base.config :oid_map_field_values, :validate => :boolean, :default => false
 
+          # Replaces integer values that have a named-number (enum) definition in the loaded
+          # MIBs with their textual name (e.g. `ifOperStatus` 1 -> "up").
+          base.config :map_enum_values, :validate => :boolean, :default => false
+
           # Number of OID root digits to ignore in event field name. For example, in a numeric OID
           # like 1.3.6.1.2.1.1.1.0" the first 5 digits could be ignored by setting oid_root_skip => 5
           # which would result in a field name "1.1.1.0". Similarly when a MIB is used an OID such
@@ -122,6 +126,7 @@ module LogStash
           end
 
           client_builder.setMapOidVariableValues(@oid_map_field_values)
+          client_builder.setMapEnumValues(@map_enum_values)
           client_builder.build
         end
 

data/lib/logstash-integration-snmp_jars.rb

@@ -4,4 +4,4 @@ require 'jar_dependencies'
 require_jar('org.snmp4j', 'snmp4j-log4j', '2.8.11')
 require_jar('org.snmp4j', 'snmp4j', '3.8.0')
 require_jar('org.snakeyaml', 'snakeyaml-engine', '2.7')
-require_jar('org.logstash.integrations', 'plugin', '4.4.1')
+require_jar('org.logstash.integrations', 'plugin', '4.5.0')

data/spec/integration/inputs/snmp_spec.rb

@@ -440,6 +440,42 @@ describe LogStash::Inputs::Snmp, :integration => true do
     end
   end
 
+  context 'with map_enum_values' do
+    let(:config) do
+      super().merge({
+        'hosts' => [{ 'host' => "udp:snmpsim/163", 'version' => '3' }],
+        'security_name' => 'testuser',
+        'auth_protocol' => 'sha',
+        'auth_pass' => 'authp123',
+        'priv_protocol' => 'aes256with3desKey',
+        'priv_pass' => 'privpass123',
+        'security_level' => 'authPriv',
+        'get' => ['1.3.6.1.2.1.2.2.1.8.1'], # ifOperStatus.1 = 1 (up)
+        'use_provided_mibs' => true,
+        'mib_paths' => [],
+        'map_enum_values' => map_enum_values
+      })
+    end
+
+    context 'set to false' do
+      let(:map_enum_values) { false }
+
+      it 'should not translate enum values' do
+        event = run_plugin_and_get_queue(plugin).pop
+        expect(event.get('iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifOperStatus.1')).to eq(1)
+      end
+    end
+
+    context 'set to true' do
+      let(:map_enum_values) { true }
+
+      it 'should translate enum values' do
+        event = run_plugin_and_get_queue(plugin).pop
+        expect(event.get('iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifOperStatus.1')).to eq('up')
+      end
+    end
+  end
+
   def run_plugin_and_get_queue(plugin, timeout: 30, register: true)
     poll_clients_latch = Concurrent::CountDownLatch.new(1)
 

data/spec/unit/inputs/common_spec.rb

@@ -161,6 +161,7 @@ shared_examples 'a common SNMP plugin' do
         it 'should not raise' do
           expect(client_builder).to receive(:addUsmUser)
           expect(client_builder).to receive(:setMapOidVariableValues)
+          expect(client_builder).to receive(:setMapEnumValues)
           expect(client_builder).to receive(:build)
           expect { plugin.build_snmp_client!(client_builder, validate_usm_user: true) }.to_not raise_error
         end
@@ -192,6 +193,7 @@ shared_examples 'a common SNMP plugin' do
           it 'should not raise' do
             expect(client_builder).to receive(:addUsmUser)
             expect(client_builder).to receive(:setMapOidVariableValues)
+            expect(client_builder).to receive(:setMapEnumValues)
             expect(client_builder).to receive(:build)
             expect { plugin.build_snmp_client!(client_builder, validate_usm_user: true) }.to_not raise_error
           end
@@ -203,6 +205,7 @@ shared_examples 'a common SNMP plugin' do
           it 'should not raise' do
             expect(client_builder).to receive(:addUsmUser)
             expect(client_builder).to receive(:setMapOidVariableValues)
+            expect(client_builder).to receive(:setMapEnumValues)
             expect(client_builder).to receive(:build)
             expect { plugin.build_snmp_client!(client_builder, validate_usm_user: true) }.to_not raise_error
           end

data/spec/unit/inputs/snmp_spec.rb

@@ -334,6 +334,150 @@ describe LogStash::Inputs::Snmp, :ecs_compatibility_support do
       end
     end
 
+    context 'mocked tables' do
+      before(:each) do
+        allow(mock_aggregator_request).to receive(:get)
+        allow(mock_aggregator_request).to receive(:table)
+      end
+
+      context 'with split_tables' do
+        let(:config) do
+          super().merge({
+            'hosts' => [{ 'host' => "udp:127.0.0.1/161" }],
+            'get' => ["1.3.6.1.2.1.1.5.0"],
+            'tables' => [{ 'name' => 'interfaces', 'columns' => ['1.3.6.1.2.1.2.2.1.2'] }],
+            'split_tables' => true
+          })
+        end
+
+        before(:each) do
+          expect(mock_aggregator_request).to receive(:get_result_async) do |consumer|
+            consumer.call(RequestResult.new({
+              'sysName' => 'test-agent',
+              'interfaces' => [{ 'index' => '1', 'ifDescr' => 'lo' }, { 'index' => '2', 'ifDescr' => 'eth0' }]
+            }, false))
+          end
+        end
+
+        it 'emits one event per row, with scalar fields on each' do
+          plugin.register
+          plugin.run(queue)
+          events = 2.times.map { queue.pop }
+
+          expect(events.map { |e| e.get('[interfaces][index]') }).to contain_exactly('1', '2')
+          events.each { |e| expect(e.get('sysName')).to eq('test-agent') }
+        end
+      end
+
+      context 'with split_tables and multiple tables' do
+        let(:config) do
+          super().merge({
+            'hosts' => [{ 'host' => "udp:127.0.0.1/161" }],
+            'tables' => [
+              { 'name' => 'interfaces', 'columns' => ['1.3.6.1.2.1.2.2.1.2'] },
+              { 'name' => 'cpu', 'columns' => ['1.3.6.1.2.1.25.3.3.1.2'] }
+            ],
+            'split_tables' => true
+          })
+        end
+
+        before(:each) do
+          expect(mock_aggregator_request).to receive(:get_result_async) do |consumer|
+            consumer.call(RequestResult.new({
+              'interfaces' => [{ 'index' => '1' }, { 'index' => '2' }],
+              'cpu' => [{ 'index' => '1' }]
+            }, false))
+          end
+        end
+
+        it 'emits rows per table without a cross-product' do
+          plugin.register
+          plugin.run(queue)
+          events = 3.times.map { queue.pop }
+
+          expect(events.count { |e| e.get('interfaces') }).to eq(2)
+          expect(events.count { |e| e.get('cpu') }).to eq(1)
+        end
+      end
+
+      context 'with split_tables and an empty table' do
+        let(:config) do
+          super().merge({
+            'hosts' => [{ 'host' => "udp:127.0.0.1/161" }],
+            'get' => ["1.3.6.1.2.1.1.5.0"],
+            'tables' => [{ 'name' => 'interfaces', 'columns' => ['1.3.6.1.2.1.2.2.1.2'] }],
+            'split_tables' => true
+          })
+        end
+
+        before(:each) do
+          expect(mock_aggregator_request).to receive(:get_result_async) do |consumer|
+            consumer.call(RequestResult.new({ 'sysName' => 'test-agent', 'interfaces' => [] }, false))
+          end
+        end
+
+        it 'emits a single event with the scalar fields' do
+          plugin.register
+          plugin.run(queue)
+          event = queue.pop
+
+          expect(event.get('sysName')).to eq('test-agent')
+          expect(event.get('interfaces')).to be_nil
+        end
+      end
+
+      context 'with split_tables when all operations fail' do
+        let(:config) do
+          super().merge({
+            'hosts' => [{ 'host' => "udp:127.0.0.1/161" }],
+            'tables' => [{ 'name' => 'interfaces', 'columns' => ['1.3.6.1.2.1.2.2.1.2'] }],
+            'split_tables' => true
+          })
+        end
+
+        before(:each) do
+          expect(mock_aggregator_request).to receive(:get_result_async) do |consumer|
+            consumer.call(RequestResult.new({}, true))
+          end
+        end
+
+        it 'emits a single event with the failure tag' do
+          plugin.register
+          plugin.run(queue)
+
+          expect(queue.size).to eq(1)
+          expect(queue.pop.get('tags')).to include('_snmpfailure')
+        end
+      end
+
+      context 'without split_tables (default)' do
+        let(:config) do
+          super().merge({
+            'hosts' => [{ 'host' => "udp:127.0.0.1/161" }],
+            'tables' => [{ 'name' => 'interfaces', 'columns' => ['1.3.6.1.2.1.2.2.1.2'] }]
+          })
+        end
+
+        before(:each) do
+          expect(mock_aggregator_request).to receive(:get_result_async) do |consumer|
+            consumer.call(RequestResult.new({
+              'interfaces' => [{ 'index' => '1' }, { 'index' => '2' }]
+            }, false))
+          end
+        end
+
+        it 'emits a single aggregated event' do
+          plugin.register
+          plugin.run(queue)
+
+          expect(queue.size).to eq(1)
+          event = queue.pop
+          expect(event.get('[interfaces][0][index]')).to eq('1')
+          expect(event.get('[interfaces][1][index]')).to eq('2')
+        end
+      end
+    end
+
     context 'mocked result with errors' do
       let(:config) do
         super().merge({

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: logstash-integration-snmp
 version: !ruby/object:Gem::Version
-  version: 4.4.1
+  version: 4.5.0
 platform: java
 authors:
 - Elastic
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logstash-core-plugin-api
@@ -468,7 +468,7 @@ files:
 - spec/unit/inputs/common_spec.rb
 - spec/unit/inputs/snmp_spec.rb
 - spec/unit/inputs/snmptrap_spec.rb
-- vendor/jar-dependencies/org/logstash/integrations/plugin/4.4.1/plugin-4.4.1.jar
+- vendor/jar-dependencies/org/logstash/integrations/plugin/4.5.0/plugin-4.5.0.jar
 - vendor/jar-dependencies/org/snakeyaml/snakeyaml-engine/2.7/snakeyaml-engine-2.7.jar
 - vendor/jar-dependencies/org/snmp4j/snmp4j-log4j/2.8.11/snmp4j-log4j-2.8.11.jar
 - vendor/jar-dependencies/org/snmp4j/snmp4j/3.8.0/snmp4j-3.8.0.jar