264 lines
9.5 KiB
Markdown
264 lines
9.5 KiB
Markdown
# OpenCensus Libraries for Go
|
||
|
||
[![Build Status][travis-image]][travis-url]
|
||
[![Windows Build Status][appveyor-image]][appveyor-url]
|
||
[![GoDoc][godoc-image]][godoc-url]
|
||
[![Gitter chat][gitter-image]][gitter-url]
|
||
|
||
OpenCensus Go is a Go implementation of OpenCensus, a toolkit for
|
||
collecting application performance and behavior monitoring data.
|
||
Currently it consists of three major components: tags, stats and tracing.
|
||
|
||
## Installation
|
||
|
||
```
|
||
$ go get -u go.opencensus.io
|
||
```
|
||
|
||
The API of this project is still evolving, see: [Deprecation Policy](#deprecation-policy).
|
||
The use of vendoring or a dependency management tool is recommended.
|
||
|
||
## Prerequisites
|
||
|
||
OpenCensus Go libraries require Go 1.8 or later.
|
||
|
||
## Getting Started
|
||
|
||
The easiest way to get started using OpenCensus in your application is to use an existing
|
||
integration with your RPC framework:
|
||
|
||
* [net/http](https://godoc.org/go.opencensus.io/plugin/ochttp)
|
||
* [gRPC](https://godoc.org/go.opencensus.io/plugin/ocgrpc)
|
||
* [database/sql](https://godoc.org/github.com/basvanbeek/ocsql)
|
||
* [Go kit](https://godoc.org/github.com/go-kit/kit/tracing/opencensus)
|
||
* [Groupcache](https://godoc.org/github.com/orijtech/groupcache)
|
||
* [Caddy webserver](https://godoc.org/github.com/orijtech/caddy)
|
||
* [MongoDB](https://godoc.org/github.com/orijtech/mongo-go-driver)
|
||
* [Redis gomodule/redigo](https://godoc.org/github.com/orijtech/redigo)
|
||
* [Redis goredis/redis](https://godoc.org/github.com/orijtech/redis)
|
||
* [Memcache](https://godoc.org/github.com/orijtech/gomemcache)
|
||
|
||
If you're using a framework not listed here, you could either implement your own middleware for your
|
||
framework or use [custom stats](#stats) and [spans](#spans) directly in your application.
|
||
|
||
## Exporters
|
||
|
||
OpenCensus can export instrumentation data to various backends.
|
||
OpenCensus has exporter implementations for the following, users
|
||
can implement their own exporters by implementing the exporter interfaces
|
||
([stats](https://godoc.org/go.opencensus.io/stats/view#Exporter),
|
||
[trace](https://godoc.org/go.opencensus.io/trace#Exporter)):
|
||
|
||
* [Prometheus][exporter-prom] for stats
|
||
* [OpenZipkin][exporter-zipkin] for traces
|
||
* [Stackdriver][exporter-stackdriver] Monitoring for stats and Trace for traces
|
||
* [Jaeger][exporter-jaeger] for traces
|
||
* [AWS X-Ray][exporter-xray] for traces
|
||
* [Datadog][exporter-datadog] for stats and traces
|
||
* [Graphite][exporter-graphite] for stats
|
||
* [Honeycomb][exporter-honeycomb] for traces
|
||
|
||
## Overview
|
||
|
||
|
||
|
||
In a microservices environment, a user request may go through
|
||
multiple services until there is a response. OpenCensus allows
|
||
you to instrument your services and collect diagnostics data all
|
||
through your services end-to-end.
|
||
|
||
## Tags
|
||
|
||
Tags represent propagated key-value pairs. They are propagated using `context.Context`
|
||
in the same process or can be encoded to be transmitted on the wire. Usually, this will
|
||
be handled by an integration plugin, e.g. `ocgrpc.ServerHandler` and `ocgrpc.ClientHandler`
|
||
for gRPC.
|
||
|
||
Package `tag` allows adding or modifying tags in the current context.
|
||
|
||
[embedmd]:# (internal/readme/tags.go new)
|
||
```go
|
||
ctx, err = tag.New(ctx,
|
||
tag.Insert(osKey, "macOS-10.12.5"),
|
||
tag.Upsert(userIDKey, "cde36753ed"),
|
||
)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
## Stats
|
||
|
||
OpenCensus is a low-overhead framework even if instrumentation is always enabled.
|
||
In order to be so, it is optimized to make recording of data points fast
|
||
and separate from the data aggregation.
|
||
|
||
OpenCensus stats collection happens in two stages:
|
||
|
||
* Definition of measures and recording of data points
|
||
* Definition of views and aggregation of the recorded data
|
||
|
||
### Recording
|
||
|
||
Measurements are data points associated with a measure.
|
||
Recording implicitly tags the set of Measurements with the tags from the
|
||
provided context:
|
||
|
||
[embedmd]:# (internal/readme/stats.go record)
|
||
```go
|
||
stats.Record(ctx, videoSize.M(102478))
|
||
```
|
||
|
||
### Views
|
||
|
||
Views are how Measures are aggregated. You can think of them as queries over the
|
||
set of recorded data points (measurements).
|
||
|
||
Views have two parts: the tags to group by and the aggregation type used.
|
||
|
||
Currently three types of aggregations are supported:
|
||
* CountAggregation is used to count the number of times a sample was recorded.
|
||
* DistributionAggregation is used to provide a histogram of the values of the samples.
|
||
* SumAggregation is used to sum up all sample values.
|
||
|
||
[embedmd]:# (internal/readme/stats.go aggs)
|
||
```go
|
||
distAgg := view.Distribution(0, 1<<32, 2<<32, 3<<32)
|
||
countAgg := view.Count()
|
||
sumAgg := view.Sum()
|
||
```
|
||
|
||
Here we create a view with the DistributionAggregation over our measure.
|
||
|
||
[embedmd]:# (internal/readme/stats.go view)
|
||
```go
|
||
if err := view.Register(&view.View{
|
||
Name: "example.com/video_size_distribution",
|
||
Description: "distribution of processed video size over time",
|
||
Measure: videoSize,
|
||
Aggregation: view.Distribution(0, 1<<32, 2<<32, 3<<32),
|
||
}); err != nil {
|
||
log.Fatalf("Failed to register view: %v", err)
|
||
}
|
||
```
|
||
|
||
Register begins collecting data for the view. Registered views' data will be
|
||
exported via the registered exporters.
|
||
|
||
## Traces
|
||
|
||
A distributed trace tracks the progression of a single user request as
|
||
it is handled by the services and processes that make up an application.
|
||
Each step is called a span in the trace. Spans include metadata about the step,
|
||
including especially the time spent in the step, called the span’s latency.
|
||
|
||
Below you see a trace and several spans underneath it.
|
||
|
||
|
||
|
||
### Spans
|
||
|
||
Span is the unit step in a trace. Each span has a name, latency, status and
|
||
additional metadata.
|
||
|
||
Below we are starting a span for a cache read and ending it
|
||
when we are done:
|
||
|
||
[embedmd]:# (internal/readme/trace.go startend)
|
||
```go
|
||
ctx, span := trace.StartSpan(ctx, "cache.Get")
|
||
defer span.End()
|
||
|
||
// Do work to get from cache.
|
||
```
|
||
|
||
### Propagation
|
||
|
||
Spans can have parents or can be root spans if they don't have any parents.
|
||
The current span is propagated in-process and across the network to allow associating
|
||
new child spans with the parent.
|
||
|
||
In the same process, `context.Context` is used to propagate spans.
|
||
`trace.StartSpan` creates a new span as a root if the current context
|
||
doesn't contain a span. Or, it creates a child of the span that is
|
||
already in current context. The returned context can be used to keep
|
||
propagating the newly created span in the current context.
|
||
|
||
[embedmd]:# (internal/readme/trace.go startend)
|
||
```go
|
||
ctx, span := trace.StartSpan(ctx, "cache.Get")
|
||
defer span.End()
|
||
|
||
// Do work to get from cache.
|
||
```
|
||
|
||
Across the network, OpenCensus provides different propagation
|
||
methods for different protocols.
|
||
|
||
* gRPC integrations use the OpenCensus' [binary propagation format](https://godoc.org/go.opencensus.io/trace/propagation).
|
||
* HTTP integrations use Zipkin's [B3](https://github.com/openzipkin/b3-propagation)
|
||
by default but can be configured to use a custom propagation method by setting another
|
||
[propagation.HTTPFormat](https://godoc.org/go.opencensus.io/trace/propagation#HTTPFormat).
|
||
|
||
## Execution Tracer
|
||
|
||
With Go 1.11, OpenCensus Go will support integration with the Go execution tracer.
|
||
See [Debugging Latency in Go](https://medium.com/observability/debugging-latency-in-go-1-11-9f97a7910d68)
|
||
for an example of their mutual use.
|
||
|
||
## Profiles
|
||
|
||
OpenCensus tags can be applied as profiler labels
|
||
for users who are on Go 1.9 and above.
|
||
|
||
[embedmd]:# (internal/readme/tags.go profiler)
|
||
```go
|
||
ctx, err = tag.New(ctx,
|
||
tag.Insert(osKey, "macOS-10.12.5"),
|
||
tag.Insert(userIDKey, "fff0989878"),
|
||
)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
tag.Do(ctx, func(ctx context.Context) {
|
||
// Do work.
|
||
// When profiling is on, samples will be
|
||
// recorded with the key/values from the tag map.
|
||
})
|
||
```
|
||
|
||
A screenshot of the CPU profile from the program above:
|
||
|
||
|
||
|
||
## Deprecation Policy
|
||
|
||
Before version 1.0.0, the following deprecation policy will be observed:
|
||
|
||
No backwards-incompatible changes will be made except for the removal of symbols that have
|
||
been marked as *Deprecated* for at least one minor release (e.g. 0.9.0 to 0.10.0). A release
|
||
removing the *Deprecated* functionality will be made no sooner than 28 days after the first
|
||
release in which the functionality was marked *Deprecated*.
|
||
|
||
[travis-image]: https://travis-ci.org/census-instrumentation/opencensus-go.svg?branch=master
|
||
[travis-url]: https://travis-ci.org/census-instrumentation/opencensus-go
|
||
[appveyor-image]: https://ci.appveyor.com/api/projects/status/vgtt29ps1783ig38?svg=true
|
||
[appveyor-url]: https://ci.appveyor.com/project/opencensusgoteam/opencensus-go/branch/master
|
||
[godoc-image]: https://godoc.org/go.opencensus.io?status.svg
|
||
[godoc-url]: https://godoc.org/go.opencensus.io
|
||
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
|
||
[gitter-url]: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
|
||
|
||
|
||
[new-ex]: https://godoc.org/go.opencensus.io/tag#example-NewMap
|
||
[new-replace-ex]: https://godoc.org/go.opencensus.io/tag#example-NewMap--Replace
|
||
|
||
[exporter-prom]: https://godoc.org/go.opencensus.io/exporter/prometheus
|
||
[exporter-stackdriver]: https://godoc.org/contrib.go.opencensus.io/exporter/stackdriver
|
||
[exporter-zipkin]: https://godoc.org/go.opencensus.io/exporter/zipkin
|
||
[exporter-jaeger]: https://godoc.org/go.opencensus.io/exporter/jaeger
|
||
[exporter-xray]: https://github.com/census-ecosystem/opencensus-go-exporter-aws
|
||
[exporter-datadog]: https://github.com/DataDog/opencensus-go-exporter-datadog
|
||
[exporter-graphite]: https://github.com/census-ecosystem/opencensus-go-exporter-graphite
|
||
[exporter-honeycomb]: https://github.com/honeycombio/opencensus-exporter
|