Search documentation of snmpkit

# SnmpKit.SnmpMgr (snmpkit v1.3.17)

Lightweight SNMP client library for Elixir.

This library provides a simple, stateless interface for SNMP operations without requiring heavyweight management processes or configurations.

# Summary

## Types

oid()
opts()
target()

## Functions

adaptive_walk(target, root_oid, opts \\ [])

Performs an adaptive bulk walk that automatically optimizes parameters.

analyze_table(table_data, opts \\ [])

Analyzes table structure and returns detailed metadata.

benchmark_device(target, test_oid, opts \\ [])

Benchmarks a device to determine optimal bulk parameters.

bulk_pretty(target, oid, opts \\ [])

Performs an SNMP BULK operation and returns formatted results.

bulk_walk(target, oid, opts \\ [])

Performs an SNMP BULK WALK operation and returns raw results with type information.

bulk_walk_pretty(target, oid, opts \\ [])

Performs an SNMP BULK WALK operation and returns formatted results with type information.

engine_batch(requests, opts \\ [])

Submits multiple requests as a batch through the streaming engine.

engine_request(request, opts \\ [])

Submits a request through the streaming engine.

ensure_started()

Ensures internal manager services are started.

get(target, oid, opts \\ [])

Performs an SNMP GET request.

get_async(target, oid, opts \\ [])

Performs an asynchronous SNMP GET request.

get_bulk(target, oid, opts \\ [])

Performs an SNMP GETBULK request (SNMPv2c only).

get_bulk_async(target, oid, opts \\ [])

Performs an asynchronous SNMP GETBULK request.

get_bulk_multi(targets_and_oids, opts \\ [])

Performs concurrent GETBULK operations against multiple targets.

get_column(target, table_oid, column, opts \\ [])

Gets a specific column from an SNMP table.

get_engine_stats(opts \\ [])

Gets comprehensive system metrics and statistics.

get_multi(targets_and_oids, opts \\ [])

Performs concurrent GET operations against multiple targets.

get_next(target, oid, opts \\ [])

Performs an SNMP GETNEXT request.

get_pretty(target, oid, opts \\ [])

Performs an SNMP GET operation and returns a formatted value.

get_table(target, table_oid, opts \\ [])

Gets all entries from an SNMP table and formats them as a structured table.

record_metric(metric_type, metric_name, value, tags \\ %{})

Records a custom metric.

set(target, oid, value, opts \\ [])

Performs an SNMP SET request.

start_engine(opts \\ [])

Starts the streaming PDU engine infrastructure.

table_stream(target, table_oid, opts \\ [])

Creates a stream for processing large SNMP tables.

walk(target, root_oid, opts \\ [])

Performs an SNMP walk operation using iterative GETNEXT requests.

walk_multi(targets_and_oids, opts \\ [])

Performs concurrent walk operations against multiple targets.

walk_pretty(target, oid, opts \\ [])

Performs an SNMP WALK operation and returns formatted results.

walk_stream(target, root_oid, opts \\ [])

Creates a stream for memory-efficient processing of large SNMP data.

walk_table(target, table_oid, opts \\ [])

Walks an SNMP table and returns all entries.

with_circuit_breaker(target, fun, opts \\ [])

Executes a function with circuit breaker protection.

# Types

# oid()

    @type oid() :: binary() | list()

# opts()

    @type opts() :: keyword()

# target()

    @type target() :: binary() | tuple() | map()

# Functions

# adaptive_walk(target, root_oid, opts \\ [])

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 device
- `root_oid` - Starting OID for the walk
- `opts` - 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
    # ]

# analyze_table(table_data, opts \\ [])

Analyzes table structure and returns detailed metadata.

## Parameters

- `table_data` - Table data as returned by get_table/3
- `opts` - 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 ratio

# benchmark_device(target, test_oid, opts \\ [])

Benchmarks a device to determine optimal bulk parameters.

## Parameters

- `target` - The target device to benchmark
- `test_oid` - OID to use for testing
- `opts` - Benchmark options

## Examples

    {:ok, results} = SnmpMgr.benchmark_device("192.0.2.1", "ifTable")
    optimal_size = results.optimal_bulk_size

# bulk_pretty(target, oid, opts \\ [])

    @spec bulk_pretty(target(), oid(), opts()) ::
      {:ok, [{String.t(), String.t()}]} | {:error, any()}

Performs 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"}, ...]

# bulk_walk(target, oid, opts \\ [])

    @spec bulk_walk(target(), oid(), opts()) ::
      {:ok, [{String.t(), atom(), any()}]} | {:error, any()}

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},
    #   ...
    # ]

# bulk_walk_pretty(target, oid, opts \\ [])

    @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"},
    #   ...
    # ]

# engine_batch(requests, opts \\ [])

Submits multiple requests as a batch through the streaming engine.

## Parameters

- `requests` - List of request specification maps
- `opts` - Batch options

## Examples

    requests = [
      %{type: :get, target: "device1", oid: "sysDescr.0"},
      %{type: :get, target: "device2", oid: "sysUpTime.0"}
    ]

    {:ok, results} = SnmpMgr.engine_batch(requests)

# engine_request(request, opts \\ [])

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 map
- `opts` - Request options

## Examples

    request = %{
      type: :get,
      target: "192.0.2.1",
      oid: "sysDescr.0",
      community: "public"
    }

    {:ok, result} = SnmpMgr.engine_request(request)

# ensure_started()

Ensures internal manager services are started.

Starts RequestIdGenerator, SocketManager, and EngineV2 if they are not running. Safe to call multiple times.

# get(target, oid, opts \\ [])

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 "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] 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 seconds

# get_async(target, oid, opts \\ [])

Performs an asynchronous SNMP GET request.

Returns immediately with a reference. The caller will receive a message with the result.

## Parameters

- `target` - The target device
- `oid` - The OID to retrieve (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
- `opts` - Options including :community, :timeout, :retries

## 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"

# get_bulk(target, oid, opts \\ [])

    @spec get_bulk(target(), oid(), opts()) ::
      {:ok, [{list(), atom(), any()}]} | {:error, any()}

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 device
- `oid` - The starting OID (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
- `opts` - 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
    # ]

# get_bulk_async(target, oid, opts \\ [])

Performs an asynchronous SNMP GETBULK request.

Returns immediately with a reference. The caller will receive a message with the result.

# get_bulk_multi(targets_and_oids, opts \\ [])

Performs concurrent GETBULK operations against multiple targets.

## Parameters

- `targets_and_oids` - List of {target, oid} tuples
- `opts` - Options applied to all requests including :max_repetitions

# get_column(target, table_oid, column, opts \\ [])

Gets a specific column from an SNMP table.

## Parameters

- `target` - The target device
- `table_oid` - The table OID
- `column` - The column number or name
- `opts` - Options including :community, :timeout

# get_engine_stats(opts \\ [])

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)

# get_multi(targets_and_oids, opts \\ [])

Performs concurrent GET operations against multiple targets.

## Parameters

- `targets_and_oids` - List of {target, oid} tuples
- `opts` - 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}}]

# get_next(target, oid, opts \\ [])

Performs an SNMP GETNEXT request.

## Parameters

- `target` - The target device
- `oid` - The starting OID (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
- `opts` - 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"}

# get_pretty(target, oid, opts \\ [])

    @spec get_pretty(target(), oid(), opts()) :: {:ok, String.t()} | {:error, any()}

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"

# get_table(target, table_oid, opts \\ [])

Gets all entries from an SNMP table and formats them as a structured table.

## Parameters

- `target` - The target device
- `table_oid` - The table OID
- `opts` - 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}
    #   ]
    # }

# record_metric(metric_type, metric_name, value, tags \\ %{})

Records a custom metric.

## Parameters

- `metric_type` - Type of metric (:counter, :gauge, :histogram)
- `metric_name` - Name of the metric
- `value` - Value to record
- `tags` - Optional tags

## Examples

    SnmpMgr.record_metric(:counter, :custom_requests, 1, %{device: "switch1"})
    SnmpMgr.record_metric(:histogram, :custom_latency, 150, %{operation: "bulk"})

# set(target, oid, value, opts \\ [])

Performs an SNMP SET request.

## Parameters

- `target` - The target device
- `oid` - The OID to set (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
- `value` - The value to set
- `opts` - 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)
    # :ok

# start_engine(opts \\ [])

Starts 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]
    )

# table_stream(target, table_oid, opts \\ [])

Creates a stream for processing large SNMP tables.

## Parameters

- `target` - The target device
- `table_oid` - The table OID to stream
- `opts` - 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...

# walk(target, root_oid, opts \\ [])

    @spec walk(target(), oid(), opts()) ::
      {:ok, [{list(), atom(), any()}]} | {:error, any()}

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 device
- `root_oid` - The starting OID for the walk
- `opts` - 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
    # ]

# walk_multi(targets_and_oids, opts \\ [])

Performs concurrent walk operations against multiple targets.

## Parameters

- `targets_and_oids` - List of {target, root_oid} tuples
- `opts` - Options applied to all requests

# walk_pretty(target, oid, opts \\ [])

    @spec walk_pretty(target(), oid(), opts()) ::
      {:ok, [{String.t(), String.t()}]} | {:error, any()}

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"}, ...]

# walk_stream(target, root_oid, opts \\ [])

Creates a stream for memory-efficient processing of large SNMP data.

## Parameters

- `target` - The target device
- `root_oid` - Starting OID for the walk
- `opts` - 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...

# walk_table(target, table_oid, opts \\ [])

    @spec walk_table(target(), oid(), opts()) ::
      {:ok, [{list(), atom(), any()}]} | {:error, any()}

Walks an SNMP table and returns all entries.

## Parameters

- `target` - The target device
- `table_oid` - The table OID to walk
- `opts` - 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
    # ]

# with_circuit_breaker(target, fun, opts \\ [])

Executes a function with circuit breaker protection.

## Parameters

- `target` - Target device identifier
- `fun` - Function to execute with protection
- `opts` - Circuit breaker options

## Examples

    result = SnmpMgr.with_circuit_breaker("192.0.2.1", fn ->
      SnmpMgr.get("192.0.2.1", "sysDescr.0")
    end)