dockerstats

README

dockerstats

-- import "github.com/KyleBanks/dockerstats"

     

Package dockerstats provides the ability to get currently running Docker container statistics, including memory and CPU usage.

To get the statistics of running Docker containers, you can use the Current() function:

stats, err := dockerstats.Current()
if err != nil {
	panic(err)
}

for _, s := range stats {
	fmt.Println(s.Container) // 9f2656020722
	fmt.Println(s.Memory) // {Raw=221.7 MiB / 7.787 GiB, Percent=2.78%}
	fmt.Println(s.CPU) // 99.79%
}

Alternatively, you can use the NewMonitor() function to receive a constant stream of Docker container stats, available on the Monitor's Stream channel:

m := dockerstats.NewMonitor()

for res := range m.Stream {
	if res.Error != nil {
		panic(err)
	}

	for _, s := range res.Stats {
		fmt.Println(s.Container) // 9f2656020722
	}
}

Example

For a simple example of writing the statistics of each running Docker container to a file, see the example directory.

cd example
go run main.go "output.txt"

Usage

func Current

func Current() ([]Stats, error)

Current returns the current Stats of each running Docker container.

Current will always return a []Stats slice equal in length to the number of running Docker containers, or an error. No error is returned if there are no running Docker containers, simply an empty slice.

type CliCommunicator

type CliCommunicator struct {
	DockerPath string
	Command    []string
}

CliCommunicator uses the Docker CLI to retrieve stats for currently running Docker containers.

func (CliCommunicator) Stats

func (c CliCommunicator) Stats() ([]Stats, error)

Stats returns Docker container statistics using the Docker CLI.

type Communicator

type Communicator interface {
	Stats() ([]Stats, error)
}

Communicator provides an interface for communicating with and retrieving stats from Docker.

var DefaultCommunicator Communicator = CliCommunicator{
	DockerPath: defaultDockerPath,
	Command:    []string{defaultDockerCommand, defaultDockerNoStreamArg, defaultDockerFormatArg, defaultDockerFormat},
}

DefaultCommunicator is the default way of retrieving stats from Docker.

When calling Current(), the DefaultCommunicator is used, and when retriving a Monitor using NewMonitor(), it is initialized with the DefaultCommunicator.

type IOStats

type IOStats struct {
	Network string `json:"network"`
	Block   string `json:"block"`
}

IOStats contains the statistics of a running Docker container related to IO, including network and block.

func (IOStats) String

func (i IOStats) String() string

String returns a human-readable string containing the details of a IOStats value.

type MemoryStats

type MemoryStats struct {
	Raw     string `json:"raw"`
	Percent string `json:"percent"`
}

MemoryStats contains the statistics of a running Docker container related to memory usage.

func (MemoryStats) String

func (m MemoryStats) String() string

String returns a human-readable string containing the details of a MemoryStats value.

type Monitor

type Monitor struct {
	Stream chan *StatsResult
	Comm   Communicator
}

Monitor provides the ability to recieve a constant stream of statistics for each running Docker container.

Each StatsResult sent through the channel contains either an error or a Stats slice equal in length to the number of running Docker containers.

func NewMonitor

func NewMonitor() *Monitor

NewMonitor initializes and returns a Monitor which can recieve a stream of Docker container statistics.

func (*Monitor) Stop

func (m *Monitor) Stop()

Stop tells the monitor to stop streaming Docker container statistics.

type Stats

type Stats struct {
	Container string      `json:"container"`
	Memory    MemoryStats `json:"memory"`
	CPU       string      `json:"cpu"`
	IO        IOStats     `json:"io"`
	PIDs      int         `json:"pids"`
}

Stats contains the statistics of a currently running Docker container.

func (Stats) String

func (s Stats) String() string

String returns a human-readable string containing the details of a Stats value.

type StatsResult

type StatsResult struct {
	Stats []Stats `json:"stats"`
	Error error   `json:"error"`
}

StatsResult is the value recieved when using Monitor to listen for Docker statistics.

License

dockerstats is available under MIT license.

Documentation

Overview

Package dockerstats provides the ability to get currently running Docker container statistics, including memory and CPU usage.

To get the statistics of running Docker containers, you can use the `Current()` function:

stats, err := dockerstats.Current()
if err != nil {
	panic(err)
}

for _, s := range stats {
	fmt.Println(s.Container) // 9f2656020722
	fmt.Println(s.Memory) // {Raw=221.7 MiB / 7.787 GiB, Percent=2.78%}
	fmt.Println(s.CPU) // 99.79%
}

Alternatively, you can use the `NewMonitor()` function to receive a constant stream of Docker container stats, available on the Monitor's `Stream` channel:

m := dockerstats.NewMonitor()

for res := range m.Stream {
	if res.Error != nil {
		panic(err)
	}

	for _, s := range res.Stats {
		fmt.Println(s.Container) // 9f2656020722
	}
}

Index

• type CliCommunicator
  • func (c CliCommunicator) Stats() ([]Stats, error)
• type Communicator
• type IOStats
  • func (i IOStats) String() string
• type MemoryStats
  • func (m MemoryStats) String() string
• type Monitor
  • func NewMonitor() *Monitor
  • func (m *Monitor) Start()
  • func (m *Monitor) Stop()
• type Stats
  • func Current() ([]Stats, error)
  • func (s Stats) String() string
• type StatsResult

Types

type CliCommunicator

type CliCommunicator struct {
	DockerPath string
	Command    []string
}

CliCommunicator uses the Docker CLI to retrieve stats for currently running Docker containers.

func (CliCommunicator) Stats

func (c CliCommunicator) Stats() ([]Stats, error)

Stats returns Docker container statistics using the Docker CLI.

type Communicator

type Communicator interface {
	Stats() ([]Stats, error)
}

Communicator provides an interface for communicating with and retrieving stats from Docker.

var DefaultCommunicator Communicator = CliCommunicator{
	DockerPath: defaultDockerPath,
	Command:    []string{defaultDockerCommand, defaultDockerNoStreamArg, defaultDockerFormatArg, defaultDockerFormat},
}

DefaultCommunicator is the default way of retrieving stats from Docker.

When calling `Current()`, the `DefaultCommunicator` is used, and when retriving a `Monitor` using `NewMonitor()`, it is initialized with the `DefaultCommunicator`.

type IOStats

type IOStats struct {
	Network string `json:"network"`
	Block   string `json:"block"`
}

IOStats contains the statistics of a running Docker container related to IO, including network and block.

func (IOStats) String

func (i IOStats) String() string

String returns a human-readable string containing the details of a IOStats value.

type MemoryStats

type MemoryStats struct {
	Raw     string `json:"raw"`
	Percent string `json:"percent"`
}

MemoryStats contains the statistics of a running Docker container related to memory usage.

func (MemoryStats) String

func (m MemoryStats) String() string

String returns a human-readable string containing the details of a MemoryStats value.

type Monitor

type Monitor struct {
	Stream chan *StatsResult
	Comm   Communicator
	// contains filtered or unexported fields
}

Monitor provides the ability to recieve a constant stream of statistics for each running Docker container.

Each `StatsResult` sent through the channel contains either an `error` or a `Stats` slice equal in length to the number of running Docker containers.

func NewMonitor

func NewMonitor() *Monitor

NewMonitor initializes and returns a Monitor which can recieve a stream of Docker container statistics.

func (*Monitor) Start

func (m *Monitor) Start()

Start begins polling for Docker container statistics, and sends them through the Monitor's stream to be consumed.

func (*Monitor) Stop

func (m *Monitor) Stop()

Stop tells the monitor to stop streaming Docker container statistics.

type Stats

type Stats struct {
	Container string      `json:"container"`
	Name      string      `json:"name"`
	Memory    MemoryStats `json:"memory"`
	CPU       string      `json:"cpu"`
	IO        IOStats     `json:"io"`
	PIDs      int         `json:"pids"`
}

Stats contains the statistics of a currently running Docker container.

func Current

func Current() ([]Stats, error)

Current returns the current `Stats` of each running Docker container.

Current will always return a `[]Stats` slice equal in length to the number of running Docker containers, or an `error`. No error is returned if there are no running Docker containers, simply an empty slice.

func (Stats) String

func (s Stats) String() string

String returns a human-readable string containing the details of a Stats value.

type StatsResult

type StatsResult struct {
	Stats []Stats `json:"stats"`
	Error error   `json:"error"`
}

StatsResult is the value recieved when using Monitor to listen for Docker statistics.