dockerstats

package module
v0.0.0-...-5a20400 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 25, 2023 License: MIT Imports: 6 Imported by: 13

README

dockerstats

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

Build Status   GoDoc   Go Report Card  Coverage Status

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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`.

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

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) 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 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.

Directories

Path Synopsis
Package main is a sample use of dockerstats that infinitely listens for Docker stats, and writes the output to a file.
Package main is a sample use of dockerstats that infinitely listens for Docker stats, and writes the output to a file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL