SnmpKit Examples

This directory contains practical examples demonstrating SnmpKit's features and capabilities.

Quick Start

If you're new to SnmpKit, start with:

  1. getting_started.exs - Comprehensive introduction to all major features
  2. unified_api_demo.exs - Overview of the unified API design

Examples Overview

Basic Usage

Device Simulation

DOCSIS/Cable Networks

Running Examples

Prerequisites

Make sure you have Elixir 1.14+ installed:

elixir --version

Running Individual Examples

Most examples are self-contained and can be run directly:

# Run the getting started example
elixir examples/getting_started.exs

# Run the unified API demo
elixir examples/unified_api_demo.exs

# Run the cable modem simulation
elixir examples/cable_modem_simulation.exs

Adding SnmpKit to Your Project

Add SnmpKit to your mix.exs dependencies:

def deps do
  [
    {:snmpkit, "~> 0.3.4"}
  ]
end

Then run:

mix deps.get

Example Categories

🚀 Getting Started

Perfect for newcomers to SnmpKit or SNMP in general.

getting_started.exs

  • Creates a simulated SNMP device
  • Demonstrates GET, WALK, and bulk operations
  • Shows MIB resolution and reverse lookup
  • Includes error handling examples
  • Performance timing demonstrations

🎯 Unified API

Shows the clean, context-based API design.

unified_api_demo.exs

🖥️ Device Simulation

Learn how to create realistic SNMP devices for testing.

cable_modem_simulation.exs

  • Comprehensive DOCSIS cable modem simulation
  • Realistic device behavior and responses
  • Integration with testing frameworks

quick_cable_modem.exs

  • Simple cable modem setup
  • Quick testing scenarios
  • Basic DOCSIS operations

📡 DOCSIS/Cable Networks

Specialized examples for cable network management.

docsis_mib_example.exs

  • Loading DOCSIS MIBs
  • Cable modem status monitoring
  • Signal quality measurements
  • Upstream/downstream channel information

Code Patterns

Basic SNMP Operations

# Simple GET
{:ok, description} = SnmpKit.SNMP.get("192.168.1.1", "sysDescr.0")

# Walk a subtree
{:ok, interfaces} = SnmpKit.SNMP.walk("192.168.1.1", "ifTable")

# Bulk operations for efficiency
{:ok, results} = SnmpKit.SNMP.bulk_walk("192.168.1.1", "system")

MIB Operations

# Resolve OID names
{:ok, oid} = SnmpKit.MIB.resolve("sysDescr.0")

# Reverse lookup
{:ok, name} = SnmpKit.MIB.reverse_lookup([1, 3, 6, 1, 2, 1, 1, 1, 0])

# Tree navigation
{:ok, children} = SnmpKit.MIB.children([1, 3, 6, 1, 2, 1, 1])

Device Simulation

# Create device profile
profile = %{
  name: "Test Device",
  objects: %{
    [1, 3, 6, 1, 2, 1, 1, 1, 0] => "Test Device Description"
  }
}

# Start simulated device
{:ok, device} = SnmpKit.Sim.start_device(profile, port: 1161)

Testing Integration

Many examples show how to integrate SnmpKit with testing frameworks:

defmodule MyAppTest do
  use ExUnit.Case
  
  setup do
    # Start simulated device for testing
    {:ok, profile} = load_device_profile(:router)
    {:ok, device} = SnmpKit.Sim.start_device(profile, port: 30161)
    
    %{target: "127.0.0.1:30161", device: device}
  end
  
  test "can query device", %{target: target} do
    {:ok, description} = SnmpKit.SNMP.get(target, "sysDescr.0")
    assert String.contains?(description, "Router")
  end
end

Performance Examples

Several examples include performance measurements and optimization techniques:

# Measure operation timing
{time, {:ok, results}} = :timer.tc(fn ->
  SnmpKit.SNMP.walk("192.168.1.1", "interfaces")
end)

IO.puts("Walk completed in #{time/1000}ms")

# Concurrent operations
tasks = for target <- targets do
  Task.async(fn -> SnmpKit.SNMP.get(target, "sysDescr.0") end)
end

results = Task.await_many(tasks, 10_000)

Error Handling Patterns

Examples demonstrate robust error handling:

case SnmpKit.SNMP.get(target, oid) do
  {:ok, value} -> 
    process_value(value)
  {:error, :timeout} ->
    Logger.warn("Device #{target} timeout")
    {:error, :device_unreachable}
  {:error, :no_such_name} ->
    Logger.warn("OID #{oid} not found on #{target}")
    {:error, :oid_not_found}
  {:error, reason} ->
    Logger.error("SNMP error: #{inspect(reason)}")
    {:error, reason}
end

Advanced Features

Streaming Large Results

# Stream large walks to avoid memory issues
SnmpKit.SNMP.walk_stream("192.168.1.1", "largeTable")
|> Stream.take(1000)
|> Enum.each(&process_entry/1)

Circuit Breakers

# Automatic failure handling
{:ok, result} = SnmpKit.SNMP.with_circuit_breaker("unreliable.host", fn ->
  SnmpKit.SNMP.get("unreliable.host", "sysDescr.0")
end)

Custom Device Profiles

# Load device behavior from files
{:ok, profile} = SnmpKit.SnmpSim.ProfileLoader.load_profile(
  :custom_device,
  {:walk_file, "priv/walks/device.walk"}
)

Getting Help

Contributing Examples

We welcome contributions of new examples! Please:

  1. Follow the existing code style
  2. Include comprehensive comments
  3. Add error handling
  4. Test your example before submitting
  5. Update this README if adding new categories

See ../CONTRIBUTING.md for detailed guidelines.


Happy SNMP monitoring with SnmpKit! 🚀