SnmpKit Examples
This directory contains practical examples demonstrating SnmpKit's features and capabilities.
Quick Start
If you're new to SnmpKit, start with:
- getting_started.exs - Comprehensive introduction to all major features
- unified_api_demo.exs - Overview of the unified API design
Examples Overview
Basic Usage
- getting_started.exs - Complete introduction with simulated device
- unified_api_demo.exs - Demonstrates the clean, organized API
Device Simulation
- cable_modem_simulation.exs - DOCSIS cable modem simulation
- quick_cable_modem.exs - Simple cable modem example
- cable_modem_profile.json - Device profile configuration
DOCSIS/Cable Networks
- docsis_mib_example.exs - Working with DOCSIS MIBs
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.
- 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.
SnmpKit.SNMP
for protocol operationsSnmpKit.MIB
for MIB managementSnmpKit.Sim
for device simulation- Direct access functions for convenience
🖥️ Device Simulation
Learn how to create realistic SNMP devices for testing.
- Comprehensive DOCSIS cable modem simulation
- Realistic device behavior and responses
- Integration with testing frameworks
- Simple cable modem setup
- Quick testing scenarios
- Basic DOCSIS operations
📡 DOCSIS/Cable Networks
Specialized examples for cable network management.
- 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
- Documentation: https://hexdocs.pm/snmpkit
- Interactive Tour: ../livebooks/snmpkit_tour.livemd
- Guides: ../docs/
- Issues: GitHub Issues
Contributing Examples
We welcome contributions of new examples! Please:
- Follow the existing code style
- Include comprehensive comments
- Add error handling
- Test your example before submitting
- Update this README if adding new categories
See ../CONTRIBUTING.md for detailed guidelines.
Happy SNMP monitoring with SnmpKit! 🚀