README

FTDC-utils

This repository has a Go library and a command-line utility for using full-time diagnostic data capture files.

The command-line utility, ftdc, helps you:

  • decode decode diagnostic files into raw JSON output
  • stats read diagnostic file(s) into aggregated statistical output
  • compare compare statistical output

Installation

# for the ftdc command
go get github.com/10gen/ftdc-utils/cmd/ftdc
# for the Go library, imports as 'ftdc'
go get github.com/10gen/ftdc-utils

Usage

Decode

Usage:
  ftdc decode [OPTIONS] FILE...

        --start=<TIME>    clip data preceding start time (layout UnixDate)
        --end=<TIME>      clip data after end time (layout UnixDate)
    -m, --merge           merge chunks into one object
    -o, --out=<FILE>      write diagnostic output, in JSON, to given file
    -s, --silent          suppress chunk overview output
    FILE:                 diagnostic file(s)

Stats

Usage:
  ftdc stats [OPTIONS] FILE...

        --start=<TIME>    clip data preceding start time (layout UnixDate)
        --end=<TIME>      clip data after end time (layout UnixDate)
    -o, --out=<FILE>      write stats output, in JSON, to given file
    FILE:                 diagnostic file(s)

Compare

Usage:
  ftdc compare [OPTIONS] STAT1 STAT2

    -e, --explicit             show comparison values for all compared metrics;
                               sorted by score, descending
    -t, --threshold=<FLOAT>    threshold of deviation in comparison (default: 0.3)
    STAT1:                     statistical file (JSON)
    STAT2:                     statistical file (JSON)
Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var CmpThreshold float64 = 0.2

CmpThreshold is the threshold for comparison of metrics used by the Proximal function.

Functions

func Chunks 

func Chunks(r io.Reader, c chan<- Chunk) error

Chunks takes an FTDC diagnostic file in the form of an io.Reader, and yields chunks on the given channel. The channel is closed when there are no more chunks.

Types

type Chunk 

type Chunk struct {
	Metrics []Metric
	NDeltas int
}

Chunk represents a 'metric chunk' of data in the FTDC

func (*Chunk) Clip 

func (c *Chunk) Clip(start, end time.Time) bool

Clip trims the chunk to contain as little data as possible while keeping data within the given interval. If the chunk is entirely outside of the range, it is not modified and the return value is false.

func (*Chunk) Expand 

func (c *Chunk) Expand(includeKeys map[string]bool) []map[string]int

Expand accumulates all deltas to give values of diagnostic data for each sample represented by the Chunk. includeKeys specifies which items should be included in the output. If a value of includeKeys is false, it won't be shown even if the value for a parent document is set to true. If includeKeys is nil, data for every key is returned.

func (*Chunk) Map 

func (c *Chunk) Map() map[string]Metric

Map converts the chunk to a map representation.

func (*Chunk) Stats 

func (c *Chunk) Stats() (s Stats)

Stats produces Stats for the Chunk

type CmpScore 

type CmpScore struct {
	// Metric is the name of the metric being compared
	Metric string

	// Score is the value of the score, in the range [0, 1]
	Score float64

	// Error stores an error message if the threshold was not met
	Err error
}

CmpScore holds information for the comparison of a single metric.

type CmpScores 

type CmpScores []CmpScore

CmpScores implements sort.Interface for CmpScore slices

func Proximal 

func Proximal(a, b Stats) (score float64, scores CmpScores, ok bool)

Proximal computes a measure of deviation between two sets of metric statistics. It computes an aggregated score based on compareMetrics output, and compares it against the CmpThreshold.

Return values: score holds the numeric rating (1.0 = perfect), scores is the sorted list of scores for all compared metrics, and ok is whether the threshold was met.

func (CmpScores) Len 

func (s CmpScores) Len() int

func (CmpScores) Less 

func (s CmpScores) Less(i, j int) bool

func (CmpScores) Swap 

func (s CmpScores) Swap(i, j int)

type Metric 

type Metric struct {
	// Key is the dot-delimited key of the metric. The key is either
	// 'start', 'end', or starts with 'serverStatus.'.
	Key string

	// Value is the value of the metric at the beginning of the sample
	Value int

	// Deltas is the slice of deltas, which accumulate on Value to yield the
	// specific sample's value.
	Deltas []int
}

Metric represents an item in a chunk.

type MetricStat 

type MetricStat struct {
	// Avg is the mean of the metric's deltas. It is analogous to the first
	// derivative.
	Avg int

	// Var is the variance. It is related to the absolute second derivative.
	Var int
}

MetricStat represents basic statistics for a single metric

type Stats 

type Stats struct {
	Start    time.Time
	End      time.Time
	Metrics  map[string]MetricStat
	NSamples int
}

Stats represents basic statistics for a set of metric samples.

func ComputeStats 

func ComputeStats(r io.Reader) (cs []Stats, err error)

ComputeAllChunkStats takes an FTDC diagnostic file in the form of an io.Reader, and computes statistics for all metrics on each chunk.

func ComputeStatsInterval 

func ComputeStatsInterval(r io.Reader, start, end time.Time) (cs []Stats, err error)

ComputeStatsInterval takes an FTDC diagnostic file in the form of an io.Reader, and computes statistics for all metrics within the given time frame, clipping chunks to fit.

func MergeStats 

func MergeStats(cs ...Stats) (m Stats)

MergeStats computes a time-weighted merge of Stats.

Source Files

View all

Directories

Path Synopsis
cmd/ftdc