SnmpKit.SnmpMgr (snmpkit v0.6.3)
Lightweight SNMP client library for Elixir.
This library provides a simple, stateless interface for SNMP operations without requiring heavyweight management processes or configurations.
Summary
Functions
Performs an adaptive bulk walk that automatically optimizes parameters.
Analyzes table structure and returns detailed metadata.
Benchmarks a device to determine optimal bulk parameters.
Performs an SNMP BULK operation and returns formatted results.
Performs an SNMP BULK WALK operation and returns raw results with type information.
Performs an SNMP BULK WALK operation and returns formatted results with type information.
Submits multiple requests as a batch through the streaming engine.
Submits a request through the streaming engine.
Performs an SNMP GET request.
Performs an asynchronous SNMP GET request.
Performs an SNMP GETBULK request (SNMPv2c only).
Performs an asynchronous SNMP GETBULK request.
Performs concurrent GETBULK operations against multiple targets.
Gets a specific column from an SNMP table.
Gets comprehensive system metrics and statistics.
Performs concurrent GET operations against multiple targets.
Performs an SNMP GETNEXT request.
Performs an SNMP GET-NEXT request and returns the result with type information.
Performs an SNMP GET operation and returns a formatted value.
Gets all entries from an SNMP table and formats them as a structured table.
Performs an SNMP GET request and returns the result in 3-tuple format.
Records a custom metric.
Performs an SNMP SET request.
Starts the streaming PDU engine infrastructure.
Creates a stream for processing large SNMP tables.
Performs an SNMP walk operation using iterative GETNEXT requests.
Performs concurrent walk operations against multiple targets.
Performs an SNMP WALK operation and returns formatted results.
Creates a stream for memory-efficient processing of large SNMP data.
Walks an SNMP table and returns all entries.
Executes a function with circuit breaker protection.
Types
Functions
Performs an adaptive bulk walk that automatically optimizes parameters.
Uses intelligent parameter tuning based on device response characteristics for optimal performance.
Parameters
target- The target deviceroot_oid- Starting OID for the walkopts- Options including :adaptive_tuning, :max_entries
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, results} = SnmpMgr.adaptive_walk("switch.local", "ifTable")
# Returns optimally retrieved interface table data:
# [
# {"1.3.6.1.2.1.2.2.1.1.1", 1}, # ifIndex.1
# {"1.3.6.1.2.1.2.2.1.2.1", "eth0"}, # ifDescr.1
# {"1.3.6.1.2.1.2.2.1.8.1", 1}, # ifOperStatus.1
# {"1.3.6.1.2.1.2.2.1.1.2", 2}, # ifIndex.2
# {"1.3.6.1.2.1.2.2.1.2.2", "eth1"}, # ifDescr.2
# {"1.3.6.1.2.1.2.2.1.8.2", 1} # ifOperStatus.2
# ]Analyzes table structure and returns detailed metadata.
Parameters
table_data- Table data as returned by get_table/3opts- Analysis options
Examples
{:ok, table} = SnmpMgr.get_table("192.0.2.1", "ifTable")
{:ok, analysis} = SnmpMgr.analyze_table(table)
IO.inspect(analysis.completeness) # Shows data completeness ratioBenchmarks a device to determine optimal bulk parameters.
Parameters
target- The target device to benchmarktest_oid- OID to use for testingopts- Benchmark options
Examples
{:ok, results} = SnmpMgr.benchmark_device("192.0.2.1", "ifTable")
optimal_size = results.optimal_bulk_sizePerforms an SNMP BULK operation and returns formatted results.
Returns a list of {oid, formatted_value} tuples where values are automatically formatted based on their SNMP types.
Examples
# Bulk operation with automatic formatting
{:ok, results} = SnmpMgr.bulk_pretty("192.168.1.1", "1.3.6.1.2.1.2.2", max_repetitions: 10)
# Returns: [{"1.3.6.1.2.1.2.2.1.2.1", "eth0"}, ...]Performs an SNMP BULK WALK operation and returns raw results with type information.
Returns a list of {oid_string, type, raw_value} tuples where:
- oid_string: OID formatted as dotted decimal string
- type: SNMP type atom (:string, :integer, :gauge32, etc.)
- raw_value: Raw unformatted value from SNMP response
Examples
# Bulk walk interface table with raw values
{:ok, results} = SnmpMgr.bulk_walk("192.168.1.1", "1.3.6.1.2.1.2.2")
# Returns: [
# {"1.3.6.1.2.1.2.2.1.2.1", :octet_string, "eth0"},
# {"1.3.6.1.2.1.2.2.1.5.1", :gauge32, 1000000000},
# ...
# ]@spec bulk_walk_pretty(target(), oid(), opts()) :: {:ok, [{String.t(), atom(), String.t()}]} | {:error, any()}
Performs an SNMP BULK WALK operation and returns formatted results with type information.
Returns a list of {oid_string, type, formatted_value} tuples where:
- oid_string: OID formatted as dotted decimal string
- type: SNMP type atom (:string, :integer, :gauge32, etc.)
- formatted_value: Human-readable formatted value
Examples
# Bulk walk interface table with automatic formatting
{:ok, results} = SnmpMgr.bulk_walk_pretty("192.168.1.1", "1.3.6.1.2.1.2.2")
# Returns: [
# {"1.3.6.1.2.1.2.2.1.2.1", :octet_string, "eth0"},
# {"1.3.6.1.2.1.2.2.1.5.1", :gauge32, "1 Gbps"},
# ...
# ]Submits multiple requests as a batch through the streaming engine.
Parameters
requests- List of request specification mapsopts- Batch options
Examples
requests = [
%{type: :get, target: "device1", oid: "sysDescr.0"},
%{type: :get, target: "device2", oid: "sysUpTime.0"}
]
{:ok, results} = SnmpMgr.engine_batch(requests)Submits a request through the streaming engine.
Routes the request through the high-performance engine infrastructure with automatic load balancing, circuit breaking, and metrics collection.
Parameters
request- Request specification mapopts- Request options
Examples
request = %{
type: :get,
target: "192.0.2.1",
oid: "sysDescr.0",
community: "public"
}
{:ok, result} = SnmpMgr.engine_request(request)Performs an SNMP GET request.
Parameters
target- The target device (e.g., "192.168.1.1:161" or "device.local")oid- The OID to retrieve (string format)opts- Options including :community, :timeout, :retries
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, value} = SnmpMgr.get("device.local:161", "sysDescr.0", community: "public")
# "Linux server 5.4.0-42-generic #46-Ubuntu SMP Fri Jul 10 00:24:02 UTC 2020 x86_64"
{:ok, uptime} = SnmpMgr.get("router.local", "sysUpTime.0")
# {:timeticks, 123456789} # System uptime in hundredths of secondsPerforms an asynchronous SNMP GET request.
Returns immediately with a reference. The caller will receive a message with the result.
Examples
# Note: This function makes actual network calls and is not suitable for doctests
ref = SnmpMgr.get_async("device.local", "sysDescr.0")
receive do
{^ref, {:ok, description}} -> description
{^ref, {:error, reason}} -> {:error, reason}
after
5000 -> {:error, :timeout}
end
# "Linux server 5.4.0-42-generic"Performs an SNMP GETBULK request (SNMPv2c only).
GETBULK is more efficient than multiple GETNEXT requests for retrieving large amounts of data. It can retrieve multiple variables in a single request.
Parameters
target- The target deviceoid- The starting OIDopts- Options including :non_repeaters, :max_repetitions, :community, :timeout
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, results} = SnmpMgr.get_bulk("switch.local", "ifTable", max_repetitions: 10)
# [
# {[1,3,6,1,2,1,2,2,1,1,1], :integer, 1}, # ifIndex.1
# {[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "FastEthernet0/1"}, # ifDescr.1
# {[1,3,6,1,2,1,2,2,1,8,1], :integer, 1}, # ifOperStatus.1 (up)
# {[1,3,6,1,2,1,2,2,1,1,2], :integer, 2}, # ifIndex.2
# {[1,3,6,1,2,1,2,2,1,2,2], :octet_string, "FastEthernet0/2"}, # ifDescr.2
# # ... up to max_repetitions entries
# ]Performs an asynchronous SNMP GETBULK request.
Returns immediately with a reference. The caller will receive a message with the result.
Performs concurrent GETBULK operations against multiple targets.
Parameters
targets_and_oids- List of {target, oid} tuplesopts- Options applied to all requests including :max_repetitions
Gets a specific column from an SNMP table.
Parameters
target- The target devicetable_oid- The table OIDcolumn- The column number or nameopts- Options including :community, :timeout
Gets comprehensive system metrics and statistics.
Parameters
opts- Options including which components to include
Examples
{:ok, stats} = SnmpMgr.get_engine_stats()
IO.inspect(stats.router.requests_routed)
IO.inspect(stats.metrics.current_metrics)Performs concurrent GET operations against multiple targets.
Parameters
targets_and_oids- List of {target, oid} tuplesopts- Options applied to all requests
Examples
# Note: Network operations will fail on unreachable hosts
iex> SnmpMgr.get_multi([{"device1", [1,3,6,1,2,1,1,1,0]}, {"device2", [1,3,6,1,2,1,1,3,0]}])
[{:error, {:network_error, :hostname_resolution_failed}}, {:error, {:network_error, :hostname_resolution_failed}}]Performs an SNMP GETNEXT request.
Parameters
target- The target deviceoid- The starting OIDopts- Options including :community, :timeout, :retries
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, {next_oid, value}} = SnmpMgr.get_next("switch.local", "1.3.6.1.2.1.1")
# {"1.3.6.1.2.1.1.1.0", "Cisco IOS Software, C2960 Software"}
{:ok, {oid, val}} = SnmpMgr.get_next("device.local", "sysDescr")
# {"1.3.6.1.2.1.1.1.0", "Linux hostname 5.4.0 #1 SMP"}Performs an SNMP GET-NEXT request and returns the result with type information.
Parameters
target- The target device (host:port format)oid- The OID to use as starting point for GET-NEXTopts- Options including :community, :timeout, :retries
Examples
{:ok, {oid, type, val}} = SnmpMgr.get_next_with_type("device.local", "1.3.6.1.2.1.1")
# {"1.3.6.1.2.1.1.1.0", :octet_string, "Linux hostname 5.4.0 #1 SMP"}Performs an SNMP GET operation and returns a formatted value.
This is a convenience function that combines get_with_type/3 and automatic
formatting based on the SNMP type. Returns just the formatted value since
the OID is already known.
Examples
# Get system uptime with automatic formatting
{:ok, formatted_uptime} = SnmpMgr.get_pretty("192.168.1.1", "1.3.6.1.2.1.1.3.0")
# Returns: "14 days 15 hours 55 minutes 13 seconds"Gets all entries from an SNMP table and formats them as a structured table.
Parameters
target- The target devicetable_oid- The table OIDopts- Options including :community, :timeout
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, table} = SnmpMgr.get_table("switch.local", "ifTable")
# %{
# columns: ["ifIndex", "ifDescr", "ifType", "ifMtu", "ifSpeed", "ifOperStatus"],
# rows: [
# %{"ifIndex" => 1, "ifDescr" => "GigabitEthernet0/1", "ifType" => 6,
# "ifMtu" => 1500, "ifSpeed" => 1000000000, "ifOperStatus" => 1},
# %{"ifIndex" => 2, "ifDescr" => "GigabitEthernet0/2", "ifType" => 6,
# "ifMtu" => 1500, "ifSpeed" => 1000000000, "ifOperStatus" => 2}
# ]
# }Performs an SNMP GET request and returns the result in 3-tuple format.
This function returns the same format as walk, bulk, and other operations:
{oid_string, type, value} for consistency across the library.
Parameters
target- The target device (e.g., "192.168.1.1:161" or "device.local")oid- The OID to retrieve (string format)opts- Options including :community, :timeout, :retries
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, {oid, type, value}} = SnmpMgr.get_with_type("device.local:161", "sysDescr.0", community: "public")
# {:ok, {"1.3.6.1.2.1.1.1.0", :octet_string, "Linux server 5.4.0-42-generic"}}
{:ok, {oid, type, uptime}} = SnmpMgr.get_with_type("router.local", "sysUpTime.0")
# {:ok, {"1.3.6.1.2.1.1.3.0", :timeticks, 123456789}}Records a custom metric.
Parameters
metric_type- Type of metric (:counter, :gauge, :histogram)metric_name- Name of the metricvalue- Value to recordtags- Optional tags
Examples
SnmpMgr.record_metric(:counter, :custom_requests, 1, %{device: "switch1"})
SnmpMgr.record_metric(:histogram, :custom_latency, 150, %{operation: "bulk"})Performs an SNMP SET request.
Parameters
target- The target deviceoid- The OID to setvalue- The value to setopts- Options including :community, :timeout, :retries
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, :ok} = SnmpMgr.set("device.local", "sysLocation.0", "Server Room A")
# :ok
{:ok, :ok} = SnmpMgr.set("switch.local", "sysContact.0", "admin@company.com",
community: "private", timeout: 3000)
# :okStarts the streaming PDU engine infrastructure.
Initializes all Phase 5 components including engines, routers, connection pools, circuit breakers, and metrics collection for high-performance SNMP operations.
Options
:engine- Engine configuration options:router- Router configuration options:pool- Connection pool options:circuit_breaker- Circuit breaker options:metrics- Metrics collection options
Examples
{:ok, _pid} = SnmpMgr.start_engine(
engine: [pool_size: 20, max_rps: 500],
router: [strategy: :least_connections],
pool: [pool_size: 50],
metrics: [window_size: 120]
)Creates a stream for processing large SNMP tables.
Parameters
target- The target devicetable_oid- The table OID to streamopts- Options including :chunk_size, :columns
Examples
# Note: Requires Erlang SNMP modules for actual operation
stream = SnmpMgr.table_stream("192.0.2.1", "ifTable")
# Process table stream...Performs an SNMP walk operation using iterative GETNEXT requests.
Walks the SNMP tree starting from the given OID and returns all OID/value pairs found under that subtree.
Parameters
target- The target deviceroot_oid- The starting OID for the walkopts- Options including :community, :timeout, :max_repetitions
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, results} = SnmpMgr.walk("device.local", "1.3.6.1.2.1.1")
# [
# {[1,3,6,1,2,1,1,1,0], :octet_string, "Linux hostname 5.4.0-42-generic"}, # sysDescr
# {[1,3,6,1,2,1,1,2,0], :object_identifier, [1,3,6,1,4,1,8072,3,2,10]}, # sysObjectID
# {[1,3,6,1,2,1,1,3,0], :timeticks, 12345678}, # sysUpTime
# {[1,3,6,1,2,1,1,4,0], :octet_string, "admin@company.com"}, # sysContact
# {[1,3,6,1,2,1,1,5,0], :octet_string, "server01.company.com"}, # sysName
# {[1,3,6,1,2,1,1,6,0], :octet_string, "Data Center Room 42"} # sysLocation
# ]Performs concurrent walk operations against multiple targets.
Parameters
targets_and_oids- List of {target, root_oid} tuplesopts- Options applied to all requests
Performs an SNMP WALK operation and returns formatted results.
Returns a list of {oid, formatted_value} tuples where values are automatically formatted based on their SNMP types.
Examples
# Walk system group with automatic formatting
{:ok, results} = SnmpMgr.walk_pretty("192.168.1.1", "1.3.6.1.2.1.1")
# Returns: [{"1.3.6.1.2.1.1.3.0", "14 days 15 hours"}, ...]Creates a stream for memory-efficient processing of large SNMP data.
Parameters
target- The target deviceroot_oid- Starting OID for the walkopts- Options including :chunk_size, :adaptive
Examples
# Note: Requires Erlang SNMP modules for actual operation
stream = SnmpMgr.walk_stream("192.0.2.1", "ifTable")
# Process stream lazily...Walks an SNMP table and returns all entries.
Parameters
target- The target devicetable_oid- The table OID to walkopts- Options including :community, :timeout
Examples
# Note: This function makes actual network calls and is not suitable for doctests
{:ok, entries} = SnmpMgr.walk_table("switch.local", "ifTable")
# [
# {[1,3,6,1,2,1,2,2,1,1,1], :integer, 1}, # ifIndex.1
# {[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "GigabitEthernet0/1"}, # ifDescr.1
# {[1,3,6,1,2,1,2,2,1,3,1], :integer, 6}, # ifType.1 (ethernetCsmacd)
# {[1,3,6,1,2,1,2,2,1,5,1], :gauge32, 1000000000}, # ifSpeed.1 (1 Gbps)
# # ... all interface table entries with type information
# ]Executes a function with circuit breaker protection.
Parameters
target- Target device identifierfun- Function to execute with protectionopts- Circuit breaker options
Examples
result = SnmpMgr.with_circuit_breaker("192.0.2.1", fn ->
SnmpMgr.get("192.0.2.1", "sysDescr.0")
end)