re
/
client_golang
forked from mirror/client_golang
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
client_golang/README.md

97 lines
4.0 KiB
Markdown
Raw Normal View History

Initial commit into version control.
2012-05-20 01:59:25 +04:00
# Overview
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
These [Go](http://golang.org) packages are an extraction of pieces of
Initial commit into version control.
2012-05-20 01:59:25 +04:00
instrumentation code I whipped-up for a personal project that a friend of mine
and I are working on. We were in need for some rudimentary statistics to
observe behaviors of the server's various components, so this was written.
The code here is not a verbatim copy thereof but rather a thoughtful
re-implementation should other folks need to consume and analyze such telemetry.
N.B. --- I have spent a bit of time working through the model in my head and
probably haven't elucidated my ideas as clearly as I need to. If you examine
- Provide an example of this working with a uniform distribution.
2012-05-21 13:05:41 +04:00
examples/{simple,uniform_random}/main.go and registry.go, you'll find several
examples of what types of potential instrumentation use cases this package
addresses. There are probably numerous Go language idiomatic changes that need
to be made, but this task has been deferred for now.
Initial commit into version control.
2012-05-20 01:59:25 +04:00
# Continuous Integration
Update wrong Travis CI path.
2013-01-25 21:06:33 +04:00
[![Build Status](https://secure.travis-ci.org/prometheus/client_golang.png?branch=master)](http://travis-ci.org/prometheus/client_golang)
Initial commit into version control.
2012-05-20 01:59:25 +04:00
- Separate out the packages' files' documentation into a separate documentation file per package. - Provide better examples in the examples subdirectory. - Make the comments consistent in terms of using multi-line format for future-proofing. - Extract major constants out.
2012-05-24 22:02:44 +04:00
# Documentation
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
Please read the [generated documentation](http://go.pkgdoc.org/github.com/prometheus/client_golang)
- Separate out the packages' files' documentation into a separate documentation file per package. - Provide better examples in the examples subdirectory. - Make the comments consistent in terms of using multi-line format for future-proofing. - Extract major constants out.
2012-05-24 22:02:44 +04:00
for the project's documentation from source code.
# Basic Overview
## Metrics
Initial commit into version control.
2012-05-20 01:59:25 +04:00
A metric is a measurement mechanism.
- Separate out the packages' files' documentation into a separate documentation file per package. - Provide better examples in the examples subdirectory. - Make the comments consistent in terms of using multi-line format for future-proofing. - Extract major constants out.
2012-05-24 22:02:44 +04:00
### Gauge
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
A _Gauge_ is a metric that exposes merely an instantaneous value or some
snapshot thereof.
### Counter
A _Counter_ is a metric that exposes merely a sum or tally of things.
Initial commit into version control.
2012-05-20 01:59:25 +04:00
- Separate out the packages' files' documentation into a separate documentation file per package. - Provide better examples in the examples subdirectory. - Make the comments consistent in terms of using multi-line format for future-proofing. - Extract major constants out.
2012-05-24 22:02:44 +04:00
### Histogram
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
A _Histogram_ is a metric that captures events or samples into _Buckets_. It
Initial commit into version control.
2012-05-20 01:59:25 +04:00
exposes its values via percentile estimations.
- Separate out the packages' files' documentation into a separate documentation file per package. - Provide better examples in the examples subdirectory. - Make the comments consistent in terms of using multi-line format for future-proofing. - Extract major constants out.
2012-05-24 22:02:44 +04:00
#### Buckets
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
A _Bucket_ is a generic container that collects samples and their values. It
Initial commit into version control.
2012-05-20 01:59:25 +04:00
prescribes no behavior on its own aside from merely accepting a value,
leaving it up to the concrete implementation to what to do with the injected
values.
- Separate out the packages' files' documentation into a separate documentation file per package. - Provide better examples in the examples subdirectory. - Make the comments consistent in terms of using multi-line format for future-proofing. - Extract major constants out.
2012-05-24 22:02:44 +04:00
##### Accumulating Bucket
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
An _Accumulating Bucket_ is a _Bucket_ that appends the new sample to a queue
such that the eldest values are evicted according to a given policy.
Initial commit into version control.
2012-05-20 01:59:25 +04:00
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
###### Eviction Policies
Once an _Accumulating Bucket_ reaches capacity, its eviction policy is invoked.
Initial commit into version control.
2012-05-20 01:59:25 +04:00
This reaps the oldest N objects subject to certain behavior.
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
####### Remove Oldest
Initial commit into version control.
2012-05-20 01:59:25 +04:00
This merely removes the oldest N items without performing some aggregation
replacement operation on them.
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
####### Aggregate Oldest
Initial commit into version control.
2012-05-20 01:59:25 +04:00
This removes the oldest N items while performing some summary aggregation
operation thereupon, which is then appended to the list in the former values'
place.
- Separate out the packages' files' documentation into a separate documentation file per package. - Provide better examples in the examples subdirectory. - Make the comments consistent in terms of using multi-line format for future-proofing. - Extract major constants out.
2012-05-24 22:02:44 +04:00
##### Tallying Bucket
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
A _Tallying Bucket_ differs from an _Accumulating Bucket_ in that it never
stores any of the values emitted into it but rather exposes a simplied summary
Initial commit into version control.
2012-05-20 01:59:25 +04:00
representation thereof. For instance, if a values therein is requested,
it may situationally emit a minimum, maximum, an average, or any other
reduction mechanism requested.
Include link to generated API documentation. Include mailing list.
2013-03-28 13:44:20 +04:00
# Getting Started
* The source code is periodically indexed: [Go Exposition Client](http://godoc.org/github.com/prometheus/client_golang).
* All of the core developers are accessible via the [Prometheus Developers Mailinglist](https://groups.google.com/forum/?fromgroups#!forum/prometheus-developers).
Initial commit into version control.
2012-05-20 01:59:25 +04:00
# Testing
This package employs [gocheck](http://labix.org/gocheck) for testing. Please
ensure that all tests pass by running the following from the project root:
$ go test ./...
Fix documentation after reading via server. Examining the existing documentation over the standard Go documentation server revealed some serious formatting flaws. Everything should be readable now.
2013-02-18 08:09:21 +04:00
The use of gocheck is summarily being phased out; however, old tests that use it
Include link to generated API documentation. Include mailing list.
2013-03-28 13:44:20 +04:00
still exist.
Eliminate a number of style-guide violations. Change-Id: Iedcd611e5c7ad24c84c004d8d6c551d1734e443c
2014-04-25 14:50:18 +04:00
# Contributing
Same as for the `prometheus/prometheus` repository, we are using
Gerrit to manage reviews of pull-requests for this repository. See
[`CONTRIBUTING.md`](https://github.com/prometheus/prometheus/blob/master/CONTRIBUTING.md)
in the `prometheus/prometheus` repository for details (but replace the
`prometheus` repository name by `client_golang`).
Please try to avoid warnings flagged by [`go
vet`](https://godoc.org/code.google.com/p/go.tools/cmd/vet) and by
[`golint`](https://github.com/golang/lint), and pay attention to the
[Go Code Review
Comments](https://code.google.com/p/go-wiki/wiki/CodeReviewComments).