mirror of
https://github.com/prometheus/node_exporter.git
synced 2024-12-21 07:56:07 +01:00
107 lines
5.0 KiB
Go
107 lines
5.0 KiB
Go
//
|
|
// Package kstat provides a Go interface to the Solaris/OmniOS
|
|
// kstat(s) system for user-level access to a lot of kernel
|
|
// statistics. For more documentation on kstats, see kstat(1) and
|
|
// kstat(3kstat).
|
|
//
|
|
// The package can retrieve what are called 'named' kstat statistics,
|
|
// IO statistics, and the most common additional types of 'raw'
|
|
// statistics, which covers almost all kstats you will normally find
|
|
// in the kernel. You can see the names and types of other kstats, but
|
|
// not currently retrieve data for them. Named statistics are the most
|
|
// common type for general information; IO statistics are exported by
|
|
// disks and some other things. Supported additional raw kstats are
|
|
// unix:0:sysinfo, unix:0:vminfo, unix:0:var, and mnt:*:mntinfo.
|
|
//
|
|
// General usage for named statistics: call Open() to obtain a Token,
|
|
// then call GetNamed() on it to obtain Named(s) for specific
|
|
// statistics. Note that this always gives you the very latest value
|
|
// for the statistic. If you want a number of statistics from the same
|
|
// module:inst:name triplet (eg several network counters from the same
|
|
// network interface) and you want them to all have been gathered at
|
|
// the same time, you need to call .Lookup() to obtain a KStat and
|
|
// then repeatedly call its .GetNamed() (this is also slightly more
|
|
// efficient).
|
|
//
|
|
// The short version: a kstat is a collection of some related
|
|
// statistics, eg various network counters for a particular network
|
|
// interface. A Token is a handle for a collection of kstats. You go
|
|
// collection (Token) -> kstat (KStat) -> specific statistic (Named)
|
|
// in order to retrieve the value of a specific statistic.
|
|
//
|
|
// (IO stats are retrieved all at once with GetIO(), because they come
|
|
// to us from the kernel as one single struct so that's what you get.)
|
|
//
|
|
// This is a cgo-based package. Cross compilation is up to you.
|
|
// Goroutine safety is in no way guaranteed because the underlying
|
|
// C kstat library is probably not thread or goroutine safe (and
|
|
// there are some all-Go concurrency races involving .Close()).
|
|
//
|
|
// This package may leak memory, especially since the Solaris kstat
|
|
// manpage is not clear on the requirements here. However I believe
|
|
// it's reasonably memory safe. It's possible to totally corrupt
|
|
// memory with use-after-free errors if you do operations on kstats
|
|
// after calling Token.Close(), although we try to avoid that.
|
|
//
|
|
// NOTE: this package is quite young. The API may well change as
|
|
// I (and other people) gain more experience with it.
|
|
//
|
|
// PERFORMANCE
|
|
//
|
|
// In general this is not going to be as lean and mean as calling
|
|
// C directly, partly because of intrinsic CGo overheads and partly
|
|
// because we do more memory allocation and deallocation than a C
|
|
// program would (partly because we prioritize not leaking memory).
|
|
//
|
|
// SUPPORTED AND UNSUPPORTED KSTAT TYPES
|
|
//
|
|
// We support named kstats and IO kstats (KSTAT_TYPE_NAMED and
|
|
// KSTAT_TYPE_IO / kstat_io_t respectively). kstat(1) also knows about
|
|
// a number of magic specific 'raw' stats (which are generally custom
|
|
// C structs); of these we support unix:0:sysinfo, unix:0:vminfo,
|
|
// unix:0:var, and mnt:*:mntinfo for NFS filesystem mounts.
|
|
//
|
|
// In theory kstat supports general timer and interrupt stats. In
|
|
// practice there is no use of KSTAT_TYPE_TIMER in the current Illumos
|
|
// kernel source and very little use of KSTAT_TYPE_INTR (mostly by
|
|
// very old hardware drivers, although the vioif driver uses it too).
|
|
// Since I can't test KSTAT_TYPE_INTR stats, we don't currently
|
|
// support it.
|
|
//
|
|
// There are also a few additional KSTAT_TYPE_RAW raw stats that we
|
|
// don't support, mostly because they seem to be effectively obsolete.
|
|
// These specific raw stats can be found listed in the Illumos source
|
|
// code in cmd/stat/kstat/kstat.h in the ks_raw_lookup array. See
|
|
// cmd/stat/kstat/kstat.c for how they're interpreted. If you need
|
|
// access to one of these kstats, the KStat.CopyTo() and KStat.Raw()
|
|
// methods give you an escape hatch to roll your own. You'll probably
|
|
// need to use cgo to generate an appropriate Go struct that matches
|
|
// the C struct you need. My notes on this process may be helpful:
|
|
//
|
|
// https://utcc.utoronto.ca/~cks/space/blog/programming/GoCGoCompatibleStructs
|
|
//
|
|
// Author: Chris Siebenmann
|
|
// https://github.com/siebenmann/go-kstat
|
|
//
|
|
// Copyright: standard Go copyright.
|
|
//
|
|
// (If you're reading this documentation on a non-Solaris platform,
|
|
// you're probably not seeing the detailed API documentation for
|
|
// constants, types, and so on because of tooling limitations in godoc
|
|
// et al.)
|
|
//
|
|
package kstat
|
|
|
|
//
|
|
// This exists in large part to give non-Solaris systems something
|
|
// that makes the package name visible. Otherwise eg goimports thinks
|
|
// that this is an empty package and deletes 'import ...' statements
|
|
// for it if you process a Go file that imports the package on a
|
|
// non-Solaris platform.
|
|
//
|
|
// Since this file exists, I've put the package-level documentation
|
|
// here to increase the odds that tools running on non-Solaris systems
|
|
// will be able to show you at least some documentation.
|
|
//
|
|
// This is a hack, and annoying.
|