Package Usage: go: github.com/illumos/go-kstat
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.
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).
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.)
1 version
Latest release: about 4 years ago
34 dependent packages
View more package details: https://packages.ecosystem.code.gouv.fr/registries/proxy.golang.org/packages/github.com/illumos/go-kstat