1# OpenCensus Libraries for Go
2
3[![Build Status][travis-image]][travis-url]
4[![Windows Build Status][appveyor-image]][appveyor-url]
5[![GoDoc][godoc-image]][godoc-url]
6[![Gitter chat][gitter-image]][gitter-url]
7
8OpenCensus Go is a Go implementation of OpenCensus, a toolkit for
9collecting application performance and behavior monitoring data.
10Currently it consists of three major components: tags, stats and tracing.
11
12#### OpenCensus and OpenTracing have merged to form OpenTelemetry, which serves as the next major version of OpenCensus and OpenTracing. OpenTelemetry will offer backwards compatibility with existing OpenCensus integrations, and we will continue to make security patches to existing OpenCensus libraries for two years. Read more about the merger [here](https://medium.com/opentracing/a-roadmap-to-convergence-b074e5815289).
13
14## Installation
15
16```
17$ go get -u go.opencensus.io
18```
19
20The API of this project is still evolving, see: [Deprecation Policy](#deprecation-policy).
21The use of vendoring or a dependency management tool is recommended.
22
23## Prerequisites
24
25OpenCensus Go libraries require Go 1.8 or later.
26
27## Getting Started
28
29The easiest way to get started using OpenCensus in your application is to use an existing
30integration with your RPC framework:
31
32* [net/http](https://godoc.org/go.opencensus.io/plugin/ochttp)
33* [gRPC](https://godoc.org/go.opencensus.io/plugin/ocgrpc)
34* [database/sql](https://godoc.org/github.com/opencensus-integrations/ocsql)
35* [Go kit](https://godoc.org/github.com/go-kit/kit/tracing/opencensus)
36* [Groupcache](https://godoc.org/github.com/orijtech/groupcache)
37* [Caddy webserver](https://godoc.org/github.com/orijtech/caddy)
38* [MongoDB](https://godoc.org/github.com/orijtech/mongo-go-driver)
39* [Redis gomodule/redigo](https://godoc.org/github.com/orijtech/redigo)
40* [Redis goredis/redis](https://godoc.org/github.com/orijtech/redis)
41* [Memcache](https://godoc.org/github.com/orijtech/gomemcache)
42
43If you're using a framework not listed here, you could either implement your own middleware for your
44framework or use [custom stats](#stats) and [spans](#spans) directly in your application.
45
46## Exporters
47
48OpenCensus can export instrumentation data to various backends.
49OpenCensus has exporter implementations for the following, users
50can implement their own exporters by implementing the exporter interfaces
51([stats](https://godoc.org/go.opencensus.io/stats/view#Exporter),
52[trace](https://godoc.org/go.opencensus.io/trace#Exporter)):
53
54* [Prometheus][exporter-prom] for stats
55* [OpenZipkin][exporter-zipkin] for traces
56* [Stackdriver][exporter-stackdriver] Monitoring for stats and Trace for traces
57* [Jaeger][exporter-jaeger] for traces
58* [AWS X-Ray][exporter-xray] for traces
59* [Datadog][exporter-datadog] for stats and traces
60* [Graphite][exporter-graphite] for stats
61* [Honeycomb][exporter-honeycomb] for traces
62* [New Relic][exporter-newrelic] for stats and traces
63
64## Overview
65
66
67
68In a microservices environment, a user request may go through
69multiple services until there is a response. OpenCensus allows
70you to instrument your services and collect diagnostics data all
71through your services end-to-end.
72
73## Tags
74
75Tags represent propagated key-value pairs. They are propagated using `context.Context`
76in the same process or can be encoded to be transmitted on the wire. Usually, this will
77be handled by an integration plugin, e.g. `ocgrpc.ServerHandler` and `ocgrpc.ClientHandler`
78for gRPC.
79
80Package `tag` allows adding or modifying tags in the current context.
81
82[embedmd]:# (internal/readme/tags.go new)
83```go
84ctx, err := tag.New(ctx,
85 tag.Insert(osKey, "macOS-10.12.5"),
86 tag.Upsert(userIDKey, "cde36753ed"),
87)
88if err != nil {
89 log.Fatal(err)
90}
91```
92
93## Stats
94
95OpenCensus is a low-overhead framework even if instrumentation is always enabled.
96In order to be so, it is optimized to make recording of data points fast
97and separate from the data aggregation.
98
99OpenCensus stats collection happens in two stages:
100
101* Definition of measures and recording of data points
102* Definition of views and aggregation of the recorded data
103
104### Recording
105
106Measurements are data points associated with a measure.
107Recording implicitly tags the set of Measurements with the tags from the
108provided context:
109
110[embedmd]:# (internal/readme/stats.go record)
111```go
112stats.Record(ctx, videoSize.M(102478))
113```
114
115### Views
116
117Views are how Measures are aggregated. You can think of them as queries over the
118set of recorded data points (measurements).
119
120Views have two parts: the tags to group by and the aggregation type used.
121
122Currently three types of aggregations are supported:
123* CountAggregation is used to count the number of times a sample was recorded.
124* DistributionAggregation is used to provide a histogram of the values of the samples.
125* SumAggregation is used to sum up all sample values.
126
127[embedmd]:# (internal/readme/stats.go aggs)
128```go
129distAgg := view.Distribution(1<<32, 2<<32, 3<<32)
130countAgg := view.Count()
131sumAgg := view.Sum()
132```
133
134Here we create a view with the DistributionAggregation over our measure.
135
136[embedmd]:# (internal/readme/stats.go view)
137```go
138if err := view.Register(&view.View{
139 Name: "example.com/video_size_distribution",
140 Description: "distribution of processed video size over time",
141 Measure: videoSize,
142 Aggregation: view.Distribution(1<<32, 2<<32, 3<<32),
143}); err != nil {
144 log.Fatalf("Failed to register view: %v", err)
145}
146```
147
148Register begins collecting data for the view. Registered views' data will be
149exported via the registered exporters.
150
151## Traces
152
153A distributed trace tracks the progression of a single user request as
154it is handled by the services and processes that make up an application.
155Each step is called a span in the trace. Spans include metadata about the step,
156including especially the time spent in the step, called the span’s latency.
157
158Below you see a trace and several spans underneath it.
159
160
161
162### Spans
163
164Span is the unit step in a trace. Each span has a name, latency, status and
165additional metadata.
166
167Below we are starting a span for a cache read and ending it
168when we are done:
169
170[embedmd]:# (internal/readme/trace.go startend)
171```go
172ctx, span := trace.StartSpan(ctx, "cache.Get")
173defer span.End()
174
175// Do work to get from cache.
176```
177
178### Propagation
179
180Spans can have parents or can be root spans if they don't have any parents.
181The current span is propagated in-process and across the network to allow associating
182new child spans with the parent.
183
184In the same process, `context.Context` is used to propagate spans.
185`trace.StartSpan` creates a new span as a root if the current context
186doesn't contain a span. Or, it creates a child of the span that is
187already in current context. The returned context can be used to keep
188propagating the newly created span in the current context.
189
190[embedmd]:# (internal/readme/trace.go startend)
191```go
192ctx, span := trace.StartSpan(ctx, "cache.Get")
193defer span.End()
194
195// Do work to get from cache.
196```
197
198Across the network, OpenCensus provides different propagation
199methods for different protocols.
200
201* gRPC integrations use the OpenCensus' [binary propagation format](https://godoc.org/go.opencensus.io/trace/propagation).
202* HTTP integrations use Zipkin's [B3](https://github.com/openzipkin/b3-propagation)
203 by default but can be configured to use a custom propagation method by setting another
204 [propagation.HTTPFormat](https://godoc.org/go.opencensus.io/trace/propagation#HTTPFormat).
205
206## Execution Tracer
207
208With Go 1.11, OpenCensus Go will support integration with the Go execution tracer.
209See [Debugging Latency in Go](https://medium.com/observability/debugging-latency-in-go-1-11-9f97a7910d68)
210for an example of their mutual use.
211
212## Profiles
213
214OpenCensus tags can be applied as profiler labels
215for users who are on Go 1.9 and above.
216
217[embedmd]:# (internal/readme/tags.go profiler)
218```go
219ctx, err = tag.New(ctx,
220 tag.Insert(osKey, "macOS-10.12.5"),
221 tag.Insert(userIDKey, "fff0989878"),
222)
223if err != nil {
224 log.Fatal(err)
225}
226tag.Do(ctx, func(ctx context.Context) {
227 // Do work.
228 // When profiling is on, samples will be
229 // recorded with the key/values from the tag map.
230})
231```
232
233A screenshot of the CPU profile from the program above:
234
235
236
237## Deprecation Policy
238
239Before version 1.0.0, the following deprecation policy will be observed:
240
241No backwards-incompatible changes will be made except for the removal of symbols that have
242been marked as *Deprecated* for at least one minor release (e.g. 0.9.0 to 0.10.0). A release
243removing the *Deprecated* functionality will be made no sooner than 28 days after the first
244release in which the functionality was marked *Deprecated*.
245
246[travis-image]: https://travis-ci.org/census-instrumentation/opencensus-go.svg?branch=master
247[travis-url]: https://travis-ci.org/census-instrumentation/opencensus-go
248[appveyor-image]: https://ci.appveyor.com/api/projects/status/vgtt29ps1783ig38?svg=true
249[appveyor-url]: https://ci.appveyor.com/project/opencensusgoteam/opencensus-go/branch/master
250[godoc-image]: https://godoc.org/go.opencensus.io?status.svg
251[godoc-url]: https://godoc.org/go.opencensus.io
252[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
253[gitter-url]: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
254
255
256[new-ex]: https://godoc.org/go.opencensus.io/tag#example-NewMap
257[new-replace-ex]: https://godoc.org/go.opencensus.io/tag#example-NewMap--Replace
258
259[exporter-prom]: https://godoc.org/contrib.go.opencensus.io/exporter/prometheus
260[exporter-stackdriver]: https://godoc.org/contrib.go.opencensus.io/exporter/stackdriver
261[exporter-zipkin]: https://godoc.org/contrib.go.opencensus.io/exporter/zipkin
262[exporter-jaeger]: https://godoc.org/contrib.go.opencensus.io/exporter/jaeger
263[exporter-xray]: https://github.com/census-ecosystem/opencensus-go-exporter-aws
264[exporter-datadog]: https://github.com/DataDog/opencensus-go-exporter-datadog
265[exporter-graphite]: https://github.com/census-ecosystem/opencensus-go-exporter-graphite
266[exporter-honeycomb]: https://github.com/honeycombio/opencensus-exporter
267[exporter-newrelic]: https://github.com/newrelic/newrelic-opencensus-exporter-go
View as plain text