Search documentation of snmpkit

# SnmpKit.SnmpMgr.Format (snmpkit v1.3.17)

SNMP data formatting and presentation utilities.

This module provides user-friendly formatting functions for SNMP data types, delegating to the underlying SnmpKit.SnmpLib.Types functions while maintaining a clean SnmpMgr API surface.

All functions work with the 3-tuple format `{oid_string, type, value}` that SnmpMgr uses throughout the library.

Note: As of 1.1, enrichment helpers will also include `oid_list` alongside `oid` (string) and guarantee `formatted` is a String.t when requested.

## Examples

    # Format uptime from SNMP result
    {:ok, {_oid, :timeticks, ticks}} = SnmpKit.SnmpMgr.get("router.local", "sysUpTime.0")
    SnmpKit.SnmpMgr.Format.uptime(ticks)
    # => "5 days, 12 hours, 34 minutes, 56 seconds"

    # Format IP address
    SnmpKit.SnmpMgr.Format.ip_address(<<192, 168, 1, 1>>)
    # => "192.168.1.1"

    # Pretty print any SNMP result
    {:ok, result} = SnmpKit.SnmpMgr.get("router.local", "sysDescr.0")
    SnmpKit.SnmpMgr.Format.pretty_print(result)
    # => {"1.3.6.1.2.1.1.1.0", :octet_string, "Cisco IOS Router"}

# Summary

## Functions

bytes(byte_count)

Formats byte counts into human-readable sizes.

enrich_varbind(varbind, opts \\ [])

Enrich a single varbind tuple into a standardized map.

enrich_varbinds(list, opts \\ [])

Enrich a list of varbind tuples into standardized maps. Idempotent with respect to already-enriched maps.

format_by_type(arg1, value)

Automatically formats a value based on its SNMP type.

interface_status(other)

Formats SNMP interface status values into readable strings.

interface_type(other)

Formats SNMP interface types into readable strings.

ip_address(ip_bytes)

Formats IP address bytes into dotted decimal notation.

mac_address(mac)

Formats MAC addresses into standard colon-separated hex format.

pretty_print(arg)

Pretty prints an SNMP result with type-aware formatting.

pretty_print_all(results)

Pretty prints a list of SNMP results.

speed(bps)

Formats network speeds (bits per second) into human-readable rates.

uptime(ticks)

Formats timeticks (hundredths of seconds) into human-readable uptime.

# Functions

# bytes(byte_count)

Formats byte counts into human-readable sizes.

## Examples

    iex> SnmpKit.SnmpMgr.Format.bytes(1024)
    "1.0 KB"

    iex> SnmpKit.SnmpMgr.Format.bytes(1073741824)
    "1.0 GB"

# enrich_varbind(varbind, opts \\ [])

Enrich a single varbind tuple into a standardized map.

Accepts {oid, type, value} where oid may be a list or dotted string. Options:

- include_names (default true)
- include_formatted (default true)

# enrich_varbinds(list, opts \\ [])

Enrich a list of varbind tuples into standardized maps. Idempotent with respect to already-enriched maps.

# format_by_type(arg1, value)

    @spec format_by_type(atom(), any()) :: String.t()

Automatically formats a value based on its SNMP type.

This function provides a single entry point for type-aware formatting, automatically choosing the appropriate formatting function based on the type.

## Examples

    iex> SnmpKit.SnmpMgr.Format.format_by_type(:timeticks, 126691300)
    "14 days 15 hours 55 minutes 13 seconds"

    iex> SnmpKit.SnmpMgr.Format.format_by_type(:gauge32, 1000000000)
    "1 GB"

    iex> SnmpKit.SnmpMgr.Format.format_by_type(:octet_string, "Hello")
    "Hello"

# interface_status(other)

Formats SNMP interface status values into readable strings.

## Examples

    iex> SnmpKit.SnmpMgr.Format.interface_status(1)
    "up"

    iex> SnmpKit.SnmpMgr.Format.interface_status(2)
    "down"

# interface_type(other)

Formats SNMP interface types into readable strings.

## Examples

    iex> SnmpKit.SnmpMgr.Format.interface_type(6)
    "ethernetCsmacd"

    iex> SnmpKit.SnmpMgr.Format.interface_type(24)
    "softwareLoopback"

# ip_address(ip_bytes)

Formats IP address bytes into dotted decimal notation.

## Examples

    iex> SnmpKit.SnmpMgr.Format.ip_address(<<192, 168, 1, 1>>)
    "192.168.1.1"

    iex> SnmpKit.SnmpMgr.Format.ip_address({10, 0, 0, 1})
    "10.0.0.1"

# mac_address(mac)

    @spec mac_address(binary() | list() | String.t()) :: String.t()

Formats MAC addresses into standard colon-separated hex format.

Handles both binary and list representations of MAC addresses commonly found in SNMP responses.

## Examples

    iex> SnmpKit.SnmpMgr.Format.mac_address(<<0x00, 0x1B, 0x21, 0x3C, 0x4D, 0x5E>>)
    "00:1b:21:3c:4d:5e"

    iex> SnmpKit.SnmpMgr.Format.mac_address([0, 27, 33, 60, 77, 94])
    "00:1b:21:3c:4d:5e"

    iex> SnmpKit.SnmpMgr.Format.mac_address("\x00\x1B\x21\x3C\x4D\x5E")
    "00:1b:21:3c:4d:5e"

# pretty_print(arg)

Pretty prints an SNMP result with type-aware formatting.

Takes a 3-tuple `{oid_string, type, value}` and returns a formatted version with human-readable values based on the SNMP type.

## Examples

    iex> SnmpKit.SnmpMgr.Format.pretty_print({"1.3.6.1.2.1.1.3.0", :timeticks, 12345678})
    {"1.3.6.1.2.1.1.3.0", :timeticks, "1 day, 10 hours, 17 minutes, 36 seconds"}

    iex> SnmpKit.SnmpMgr.Format.pretty_print({"1.3.6.1.2.1.4.20.1.1.192.168.1.1", :ip_address, <<192, 168, 1, 1>>})
    {"1.3.6.1.2.1.4.20.1.1.192.168.1.1", :ip_address, "192.168.1.1"}

# pretty_print_all(results)

Pretty prints a list of SNMP results.

## Examples

    iex> results = [
    ...>   {"1.3.6.1.2.1.1.3.0", :timeticks, 12345678},
    ...>   {"1.3.6.1.2.1.1.1.0", :octet_string, "Router"}
    ...> ]
    iex> SnmpKit.SnmpMgr.Format.pretty_print_all(results)
    [
      {"1.3.6.1.2.1.1.3.0", :timeticks, "1 day, 10 hours, 17 minutes, 36 seconds"},
      {"1.3.6.1.2.1.1.1.0", :octet_string, ""Router""}
    ]

# speed(bps)

Formats network speeds (bits per second) into human-readable rates.

## Examples

    iex> SnmpKit.SnmpMgr.Format.speed(100_000_000)
    "100.0 Mbps"

    iex> SnmpKit.SnmpMgr.Format.speed(1_000_000_000)
    "1.0 Gbps"

# uptime(ticks)

Formats timeticks (hundredths of seconds) into human-readable uptime.

## Examples

    iex> SnmpKit.SnmpMgr.Format.uptime(12345678)
    "1 day, 10 hours, 17 minutes, 36 seconds"

    iex> SnmpKit.SnmpMgr.Format.uptime(4200)
    "42 seconds"