A TCP connection monitoring tool written in Go.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
cli/monconn use channel instead of atomic to collect stats Nov 2, 2018
examples use channel instead of atomic to collect stats Nov 2, 2018
README.md stable enough Nov 8, 2018
conn.go refactor Nov 1, 2018
ip.go refactor Nov 1, 2018
service.go fix ticker bug Nov 8, 2018
service_manager.go use channel instead of atomic to collect stats Nov 2, 2018



A TCP connection monitoring tool written in Go.


This is a tool(a library and a command line) for monitoring and debugging network services.

I built this for the purpose of facilitating debugging and monitoring the network connections of IoT devices. At this stage, it is just an experimental tool.

Note: For each tcp connection, an additional goroutine is used for monitoring, and uses a MonConn struct to store the monitored info, which takes up a bit more memory. For 5000 long connections, it takes up about 80~100MB of memory.

So it's not recommended to use it in high performance production environment.


  • reject remote ip by managing an ip blacklist
  • limit ip connections
  • record upload/download traffics of all connections
  • check idle tcp connection
  • show connecting ip connections count
  • show read and write bytes(hex array) on a connection
  • gracefull stop a tcp listener




go get -u -v github.com/gihnius/monconn

command line:

go get -u -v github.com/gihnius/monconn/cli/monconn

then run: monconn -h


for library

import "github.com/gihnius/monconn"

// --------------- global setup
monconn.Debug = true // enable debug log
monconn.DebugFunc = func(format string, v ...interface{}) {
    // custom log function

// set net.Conn buffer size, default 4k
monconn.ReadBufSize = 4 << 10
monconn.WriteBufSize = 4 << 10

// set how many concurrency clients(ip) can connect to a service
// default 64
monconn.MaxIPLimit = 1000

// --------------- service setup
// set net.Conn read write timeout
service.ReadTimeout = 600
service.WriteTimeout = 600
// close wait timeout
service.WaitTimeout = 60
// max idle check in seconds
service.MaxIdle = 900
// connections count to a service, default 0, no limit
service.ConnLimit = 0 // ConnLimit changes need to restart service
// ips count to service, default 0, no limit
service.IPLimit = 0
// set tcp connection keepalive, default true
service.KeepAlive = true
// Print read write bytes in hex format, default false
service.PrintBytes = false

for command line

please checkout monconn/cli/monconn/config.yaml.

simple usage as a port forwarder:

# use as ssh and web frontend to monitor traffics
$ monconn -p :22= -p
# here 2222 and 8080 are the real ssh and web services

more configurable options:

# monconn config.yaml
service_1: # service name
  # service listen on
  listen_ip: ""
  # monconn listen on 80
  listen_port: 80
  # forward requests to this backend
  backend_ip: ""
  # the real web listen on 8080
  backend_port: 8080
  # service config
  read_timeout: 600 # 10 minutes
  write_timeout: 600 # 10 minutes
  wait_timeout: 60 # 1 minute
  max_idle: 900 # 15 minutes
  conn_limit: 0 # zero means no limit
  ip_limit: 0 # zero means no limit
  keepalive: true
  print_bytes: true


// create service by given a sid: ""
// a service is binding to a tcp listener, so normally
// use a listen address as sid to identify a service
// you can also choose a uniqe string as sid.
service := monconn.NewService("")
// configure service like above
// service.ReadTimeout = ...
// listen a tcp port
// start the service monitor on ln
service.Listen("tcp", "")

// accept connection and monitor the connection
conn, err := service.AcquireConn()
if err != nil {
    // handle err
} else {
    go HandleConn(conn)

// when everything done, usually before program exit,
// call service.Stop() to stop the listener as well as service
// or call Shutdown() to Stop all services if there are multiple started.

// or pls checkout the example code in examples/

// checkout the API to see how to grab the monitored infomation.

// ... that's all


monconn package api

  • NewService(sid) to create a service
  • GetService(sid) get service by sid
  • DelService(sid) delete a service
  • Shutdown() Stop all services

Service instance method

  • RejectIP(ip) add ip to blacklist
  • ReleaseIP(ip) remove ip from blacklist
  • Listen() start monitor the listener
  • AcquireConn() return monitored new connection
  • Close() stop service
  • WrapMonConn()
  • EliminateBytes(r, w) see godoc
  • ReadWriteBytes() return how many bytes read or write in a service
  • IPs() service's connecting ip
  • Uptime() service's uptime, in seconds
  • Sid() service's sid getter
  • AccessAt() latest client connect time
  • BootAt() service start from time
  • ConnCount() how many realtime connections
  • IPCount() realtime ips
  • Stats() json format stats
  • Log()

MonConn instance method

  • Idle() tell if client read idle
  • Stats()
  • Log()

see godoc


  • a session wrapper
  • improve logger
  • Implement ReadFrom and WriteTo methods


In development (alpha).