Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision

Target

Select target project
  • ai3/tools/acmeserver
  • godog/acmeserver
  • svp-bot/acmeserver
3 results
Select Git revision
Show changes
Showing
with 30 additions and 1541 deletions
// Copyright 2019 The OpenZipkin Authors // Copyright 2022 The OpenZipkin Authors
// //
// Licensed under the Apache License, Version 2.0 (the "License"); // Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License. // you may not use this file except in compliance with the License.
......
// Copyright 2019 The OpenZipkin Authors // Copyright 2022 The OpenZipkin Authors
// //
// Licensed under the Apache License, Version 2.0 (the "License"); // Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License. // you may not use this file except in compliance with the License.
...@@ -28,6 +28,25 @@ var ( ...@@ -28,6 +28,25 @@ var (
ErrValidDurationRequired = errors.New("valid duration required") ErrValidDurationRequired = errors.New("valid duration required")
) )
// BaggageFields holds the interface for consumers needing to interact with
// the fields in application logic.
type BaggageFields interface {
// Get returns the values for a field identified by its key.
Get(key string) []string
// Add adds the provided values to a header designated by key. If not
// accepted by the baggage implementation, it will return false.
Add(key string, value ...string) bool
// Set sets the provided values to a header designated by key. If not
// accepted by the baggage implementation, it will return false.
Set(key string, value ...string) bool
// Delete removes the field data designated by key. If not accepted by the
// baggage implementation, it will return false.
Delete(key string) bool
// Iterate will iterate over the available fields and for each one it will
// trigger the callback function.
Iterate(f func(key string, values []string))
}
// SpanContext holds the context of a Span. // SpanContext holds the context of a Span.
type SpanContext struct { type SpanContext struct {
TraceID TraceID `json:"traceId"` TraceID TraceID `json:"traceId"`
...@@ -36,6 +55,7 @@ type SpanContext struct { ...@@ -36,6 +55,7 @@ type SpanContext struct {
Debug bool `json:"debug,omitempty"` Debug bool `json:"debug,omitempty"`
Sampled *bool `json:"-"` Sampled *bool `json:"-"`
Err error `json:"-"` Err error `json:"-"`
Baggage BaggageFields `json:"-"`
} }
// SpanModel structure. // SpanModel structure.
......
// Copyright 2019 The OpenZipkin Authors // Copyright 2022 The OpenZipkin Authors
// //
// Licensed under the Apache License, Version 2.0 (the "License"); // Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License. // you may not use this file except in compliance with the License.
......
// Copyright 2019 The OpenZipkin Authors // Copyright 2022 The OpenZipkin Authors
// //
// Licensed under the Apache License, Version 2.0 (the "License"); // Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License. // you may not use this file except in compliance with the License.
......
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
Package http implements a HTTP reporter to send spans to Zipkin V2 collectors.
*/
package http
import (
"bytes"
"context"
"log"
"net/http"
"os"
"sync"
"time"
"github.com/openzipkin/zipkin-go/model"
"github.com/openzipkin/zipkin-go/reporter"
)
// defaults
const (
defaultTimeout = 5 * time.Second // timeout for http request in seconds
defaultBatchInterval = 1 * time.Second // BatchInterval in seconds
defaultBatchSize = 100
defaultMaxBacklog = 1000
)
// HTTPDoer will do a request to the Zipkin HTTP Collector
type HTTPDoer interface {
Do(req *http.Request) (*http.Response, error)
}
// httpReporter will send spans to a Zipkin HTTP Collector using Zipkin V2 API.
type httpReporter struct {
url string
client HTTPDoer
logger *log.Logger
batchInterval time.Duration
batchSize int
maxBacklog int
batchMtx *sync.Mutex
batch []*model.SpanModel
spanC chan *model.SpanModel
sendC chan struct{}
quit chan struct{}
shutdown chan error
reqCallback RequestCallbackFn
reqTimeout time.Duration
serializer reporter.SpanSerializer
}
// Send implements reporter
func (r *httpReporter) Send(s model.SpanModel) {
r.spanC <- &s
}
// Close implements reporter
func (r *httpReporter) Close() error {
close(r.quit)
return <-r.shutdown
}
func (r *httpReporter) loop() {
var (
nextSend = time.Now().Add(r.batchInterval)
ticker = time.NewTicker(r.batchInterval / 10)
tickerChan = ticker.C
)
defer ticker.Stop()
for {
select {
case span := <-r.spanC:
currentBatchSize := r.append(span)
if currentBatchSize >= r.batchSize {
nextSend = time.Now().Add(r.batchInterval)
r.enqueueSend()
}
case <-tickerChan:
if time.Now().After(nextSend) {
nextSend = time.Now().Add(r.batchInterval)
r.enqueueSend()
}
case <-r.quit:
close(r.sendC)
return
}
}
}
func (r *httpReporter) sendLoop() {
for range r.sendC {
_ = r.sendBatch()
}
r.shutdown <- r.sendBatch()
}
func (r *httpReporter) enqueueSend() {
select {
case r.sendC <- struct{}{}:
default:
// Do nothing if there's a pending send request already
}
}
func (r *httpReporter) append(span *model.SpanModel) (newBatchSize int) {
r.batchMtx.Lock()
r.batch = append(r.batch, span)
if len(r.batch) > r.maxBacklog {
dispose := len(r.batch) - r.maxBacklog
r.logger.Printf("backlog too long, disposing %d spans", dispose)
r.batch = r.batch[dispose:]
}
newBatchSize = len(r.batch)
r.batchMtx.Unlock()
return
}
func (r *httpReporter) sendBatch() error {
// Select all current spans in the batch to be sent
r.batchMtx.Lock()
sendBatch := r.batch[:]
r.batchMtx.Unlock()
if len(sendBatch) == 0 {
return nil
}
body, err := r.serializer.Serialize(sendBatch)
if err != nil {
r.logger.Printf("failed when marshalling the spans batch: %s\n", err.Error())
return err
}
req, err := http.NewRequest("POST", r.url, bytes.NewReader(body))
if err != nil {
r.logger.Printf("failed when creating the request: %s\n", err.Error())
return err
}
// By default we send b3:0 header to mitigate trace reporting amplification in
// service mesh environments where the sidecar proxies might trace the call
// we do here towards the Zipkin collector.
req.Header.Set("b3", "0")
req.Header.Set("Content-Type", r.serializer.ContentType())
if r.reqCallback != nil {
r.reqCallback(req)
}
ctx, cancel := context.WithTimeout(req.Context(), r.reqTimeout)
defer cancel()
resp, err := r.client.Do(req.WithContext(ctx))
if err != nil {
r.logger.Printf("failed to send the request: %s\n", err.Error())
return err
}
_ = resp.Body.Close()
if resp.StatusCode < 200 || resp.StatusCode > 299 {
r.logger.Printf("failed the request with status code %d\n", resp.StatusCode)
}
// Remove sent spans from the batch even if they were not saved
r.batchMtx.Lock()
r.batch = r.batch[len(sendBatch):]
r.batchMtx.Unlock()
return nil
}
// RequestCallbackFn receives the initialized request from the Collector before
// sending it over the wire. This allows one to plug in additional headers or
// do other customization.
type RequestCallbackFn func(*http.Request)
// ReporterOption sets a parameter for the HTTP Reporter
type ReporterOption func(r *httpReporter)
// Timeout sets maximum timeout for the http request through its context.
func Timeout(duration time.Duration) ReporterOption {
return func(r *httpReporter) { r.reqTimeout = duration }
}
// BatchSize sets the maximum batch size, after which a collect will be
// triggered. The default batch size is 100 traces.
func BatchSize(n int) ReporterOption {
return func(r *httpReporter) { r.batchSize = n }
}
// MaxBacklog sets the maximum backlog size. When batch size reaches this
// threshold, spans from the beginning of the batch will be disposed.
func MaxBacklog(n int) ReporterOption {
return func(r *httpReporter) { r.maxBacklog = n }
}
// BatchInterval sets the maximum duration we will buffer traces before
// emitting them to the collector. The default batch interval is 1 second.
func BatchInterval(d time.Duration) ReporterOption {
return func(r *httpReporter) { r.batchInterval = d }
}
// Client sets a custom http client to use under the interface HTTPDoer
// which includes a `Do` method with same signature as the *http.Client
func Client(client HTTPDoer) ReporterOption {
return func(r *httpReporter) { r.client = client }
}
// RequestCallback registers a callback function to adjust the reporter
// *http.Request before it sends the request to Zipkin.
func RequestCallback(rc RequestCallbackFn) ReporterOption {
return func(r *httpReporter) { r.reqCallback = rc }
}
// Logger sets the logger used to report errors in the collection
// process.
func Logger(l *log.Logger) ReporterOption {
return func(r *httpReporter) { r.logger = l }
}
// Serializer sets the serialization function to use for sending span data to
// Zipkin.
func Serializer(serializer reporter.SpanSerializer) ReporterOption {
return func(r *httpReporter) {
if serializer != nil {
r.serializer = serializer
}
}
}
// NewReporter returns a new HTTP Reporter.
// url should be the endpoint to send the spans to, e.g.
// http://localhost:9411/api/v2/spans
func NewReporter(url string, opts ...ReporterOption) reporter.Reporter {
r := httpReporter{
url: url,
logger: log.New(os.Stderr, "", log.LstdFlags),
client: &http.Client{},
batchInterval: defaultBatchInterval,
batchSize: defaultBatchSize,
maxBacklog: defaultMaxBacklog,
batch: []*model.SpanModel{},
spanC: make(chan *model.SpanModel),
sendC: make(chan struct{}, 1),
quit: make(chan struct{}, 1),
shutdown: make(chan error, 1),
batchMtx: &sync.Mutex{},
serializer: reporter.JSONSerializer{},
reqTimeout: defaultTimeout,
}
for _, opt := range opts {
opt(&r)
}
go r.loop()
go r.sendLoop()
return &r
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package reporter
import (
"encoding/json"
"github.com/openzipkin/zipkin-go/model"
)
// SpanSerializer describes the methods needed for allowing to set Span encoding
// type for the various Zipkin transports.
type SpanSerializer interface {
Serialize([]*model.SpanModel) ([]byte, error)
ContentType() string
}
// JSONSerializer implements the default JSON encoding SpanSerializer.
type JSONSerializer struct{}
// Serialize takes an array of Zipkin SpanModel objects and returns a JSON
// encoding of it.
func (JSONSerializer) Serialize(spans []*model.SpanModel) ([]byte, error) {
return json.Marshal(spans)
}
// ContentType returns the ContentType needed for this encoding.
func (JSONSerializer) ContentType() string {
return "application/json"
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package zipkin
import (
"fmt"
"math"
"math/rand"
"sync"
"time"
)
// Sampler functions return if a Zipkin span should be sampled, based on its
// traceID.
type Sampler func(id uint64) bool
// NeverSample will always return false. If used by a service it will not allow
// the service to start traces but will still allow the service to participate
// in traces started upstream.
func NeverSample(_ uint64) bool { return false }
// AlwaysSample will always return true. If used by a service it will always start
// traces if no upstream trace has been propagated. If an incoming upstream trace
// is not sampled the service will adhere to this and only propagate the context.
func AlwaysSample(_ uint64) bool { return true }
// NewModuloSampler provides a generic type Sampler.
func NewModuloSampler(mod uint64) Sampler {
if mod < 2 {
return AlwaysSample
}
return func(id uint64) bool {
return (id % mod) == 0
}
}
// NewBoundarySampler is appropriate for high-traffic instrumentation who
// provision random trace ids, and make the sampling decision only once.
// It defends against nodes in the cluster selecting exactly the same ids.
func NewBoundarySampler(rate float64, salt int64) (Sampler, error) {
if rate == 0.0 {
return NeverSample, nil
}
if rate == 1.0 {
return AlwaysSample, nil
}
if rate < 0.0001 || rate > 1 {
return nil, fmt.Errorf("rate should be 0.0 or between 0.0001 and 1: was %f", rate)
}
var (
boundary = int64(rate * 10000)
usalt = uint64(salt)
)
return func(id uint64) bool {
return int64(math.Abs(float64(id^usalt)))%10000 < boundary
}, nil
}
// NewCountingSampler is appropriate for low-traffic instrumentation or
// those who do not provision random trace ids. It is not appropriate for
// collectors as the sampling decision isn't idempotent (consistent based
// on trace id).
func NewCountingSampler(rate float64) (Sampler, error) {
if rate == 0.0 {
return NeverSample, nil
}
if rate == 1.0 {
return AlwaysSample, nil
}
if rate < 0.01 || rate > 1 {
return nil, fmt.Errorf("rate should be 0.0 or between 0.01 and 1: was %f", rate)
}
var (
i = 0
outOf100 = int(rate*100 + math.Copysign(0.5, rate*100)) // for rounding float to int conversion instead of truncation
decisions = randomBitSet(100, outOf100, rand.New(rand.NewSource(time.Now().UnixNano())))
mtx = &sync.Mutex{}
)
return func(_ uint64) bool {
mtx.Lock()
result := decisions[i]
i++
if i == 100 {
i = 0
}
mtx.Unlock()
return result
}, nil
}
/**
* Reservoir sampling algorithm borrowed from Stack Overflow.
*
* http://stackoverflow.com/questions/12817946/generate-a-random-bitset-with-n-1s
*/
func randomBitSet(size int, cardinality int, rnd *rand.Rand) []bool {
result := make([]bool, size)
chosen := make([]int, cardinality)
var i int
for i = 0; i < cardinality; i++ {
chosen[i] = i
result[i] = true
}
for ; i < size; i++ {
j := rnd.Intn(i + 1)
if j < cardinality {
result[chosen[j]] = false
result[i] = true
chosen[j] = i
}
}
return result
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package zipkin
import (
"time"
"github.com/openzipkin/zipkin-go/model"
)
// Span interface as returned by Tracer.StartSpan()
type Span interface {
// Context returns the Span's SpanContext.
Context() model.SpanContext
// SetName updates the Span's name.
SetName(string)
// SetRemoteEndpoint updates the Span's Remote Endpoint.
SetRemoteEndpoint(*model.Endpoint)
// Annotate adds a timed event to the Span.
Annotate(time.Time, string)
// Tag sets Tag with given key and value to the Span. If key already exists in
// the Span the value will be overridden except for error tags where the first
// value is persisted.
Tag(string, string)
// Finish the Span and send to Reporter. If DelaySend option was used at
// Span creation time, Finish will not send the Span to the Reporter. It then
// becomes the user's responsibility to get the Span reported (by using
// span.Flush).
Finish()
// Finish the Span with duration and send to Reporter. If DelaySend option was used at
// Span creation time, FinishedWithDuration will not send the Span to the Reporter. It then
// becomes the user's responsibility to get the Span reported (by using
// span.Flush).
FinishedWithDuration(duration time.Duration)
// Flush the Span to the Reporter (regardless of being finished or not).
// This can be used if the DelaySend SpanOption was set or when dealing with
// one-way RPC tracing where duration might not be measured.
Flush()
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package zipkin
import (
"sync"
"sync/atomic"
"time"
"github.com/openzipkin/zipkin-go/model"
)
type spanImpl struct {
mtx sync.RWMutex
model.SpanModel
tracer *Tracer
mustCollect int32 // used as atomic bool (1 = true, 0 = false)
flushOnFinish bool
}
func (s *spanImpl) Context() model.SpanContext {
return s.SpanContext
}
func (s *spanImpl) SetName(name string) {
s.mtx.Lock()
s.Name = name
s.mtx.Unlock()
}
func (s *spanImpl) SetRemoteEndpoint(e *model.Endpoint) {
s.mtx.Lock()
if e == nil {
s.RemoteEndpoint = nil
} else {
s.RemoteEndpoint = &model.Endpoint{}
*s.RemoteEndpoint = *e
}
s.mtx.Unlock()
}
func (s *spanImpl) Annotate(t time.Time, value string) {
a := model.Annotation{
Timestamp: t,
Value: value,
}
s.mtx.Lock()
s.Annotations = append(s.Annotations, a)
s.mtx.Unlock()
}
func (s *spanImpl) Tag(key, value string) {
s.mtx.Lock()
if key == string(TagError) {
if _, found := s.Tags[key]; found {
s.mtx.Unlock()
return
}
}
s.Tags[key] = value
s.mtx.Unlock()
}
func (s *spanImpl) Finish() {
if atomic.CompareAndSwapInt32(&s.mustCollect, 1, 0) {
s.Duration = time.Since(s.Timestamp)
if s.flushOnFinish {
s.tracer.reporter.Send(s.SpanModel)
}
}
}
func (s *spanImpl) FinishedWithDuration(d time.Duration) {
if atomic.CompareAndSwapInt32(&s.mustCollect, 1, 0) {
s.Duration = d
if s.flushOnFinish {
s.tracer.reporter.Send(s.SpanModel)
}
}
}
func (s *spanImpl) Flush() {
if s.SpanModel.Debug || (s.SpanModel.Sampled != nil && *s.SpanModel.Sampled) {
s.tracer.reporter.Send(s.SpanModel)
}
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package zipkin
import (
"time"
"github.com/openzipkin/zipkin-go/model"
)
// SpanOption allows for functional options to adjust behavior and payload of
// the Span to be created with tracer.StartSpan().
type SpanOption func(t *Tracer, s *spanImpl)
// Kind sets the kind of the span being created..
func Kind(kind model.Kind) SpanOption {
return func(t *Tracer, s *spanImpl) {
s.Kind = kind
}
}
// Parent will use provided SpanContext as parent to the span being created.
func Parent(sc model.SpanContext) SpanOption {
return func(t *Tracer, s *spanImpl) {
if sc.Err != nil {
// encountered an extraction error
switch t.extractFailurePolicy {
case ExtractFailurePolicyRestart:
case ExtractFailurePolicyError:
panic(s.SpanContext.Err)
case ExtractFailurePolicyTagAndRestart:
s.Tags["error.extract"] = sc.Err.Error()
default:
panic(ErrInvalidExtractFailurePolicy)
}
/* don't use provided SpanContext, but restart trace */
return
}
s.SpanContext = sc
}
}
// StartTime uses a given start time for the span being created.
func StartTime(start time.Time) SpanOption {
return func(t *Tracer, s *spanImpl) {
s.Timestamp = start
}
}
// RemoteEndpoint sets the remote endpoint of the span being created.
func RemoteEndpoint(e *model.Endpoint) SpanOption {
return func(t *Tracer, s *spanImpl) {
s.RemoteEndpoint = e
}
}
// Tags sets initial tags for the span being created. If default tracer tags
// are present they will be overwritten on key collisions.
func Tags(tags map[string]string) SpanOption {
return func(t *Tracer, s *spanImpl) {
for k, v := range tags {
s.Tags[k] = v
}
}
}
// FlushOnFinish when set to false will disable span.Finish() to send the Span
// to the Reporter automatically (which is the default behavior). If set to
// false, having the Span be reported becomes the responsibility of the user.
// This is available if late tag data is expected to be only available after the
// required finish time of the Span.
func FlushOnFinish(b bool) SpanOption {
return func(t *Tracer, s *spanImpl) {
s.flushOnFinish = b
}
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package zipkin
// Tag holds available types
type Tag string
// Common Tag values
const (
TagHTTPMethod Tag = "http.method"
TagHTTPPath Tag = "http.path"
TagHTTPUrl Tag = "http.url"
TagHTTPRoute Tag = "http.route"
TagHTTPStatusCode Tag = "http.status_code"
TagHTTPRequestSize Tag = "http.request.size"
TagHTTPResponseSize Tag = "http.response.size"
TagGRPCStatusCode Tag = "grpc.status_code"
TagSQLQuery Tag = "sql.query"
TagError Tag = "error"
)
// Set a standard Tag with a payload on provided Span.
func (t Tag) Set(s Span, value string) {
s.Tag(string(t), value)
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package zipkin
import (
"context"
"sync/atomic"
"time"
"github.com/openzipkin/zipkin-go/idgenerator"
"github.com/openzipkin/zipkin-go/model"
"github.com/openzipkin/zipkin-go/propagation"
"github.com/openzipkin/zipkin-go/reporter"
)
// Tracer is our Zipkin tracer implementation. It should be initialized using
// the NewTracer method.
type Tracer struct {
defaultTags map[string]string
extractFailurePolicy ExtractFailurePolicy
sampler Sampler
generate idgenerator.IDGenerator
reporter reporter.Reporter
localEndpoint *model.Endpoint
noop int32 // used as atomic bool (1 = true, 0 = false)
sharedSpans bool
unsampledNoop bool
}
// NewTracer returns a new Zipkin Tracer.
func NewTracer(rep reporter.Reporter, opts ...TracerOption) (*Tracer, error) {
// set default tracer options
t := &Tracer{
defaultTags: make(map[string]string),
extractFailurePolicy: ExtractFailurePolicyRestart,
sampler: AlwaysSample,
generate: idgenerator.NewRandom64(),
reporter: rep,
localEndpoint: nil,
noop: 0,
sharedSpans: true,
unsampledNoop: false,
}
// if no reporter was provided we default to noop implementation.
if t.reporter == nil {
t.reporter = reporter.NewNoopReporter()
t.noop = 1
}
// process functional options
for _, opt := range opts {
if err := opt(t); err != nil {
return nil, err
}
}
return t, nil
}
// StartSpanFromContext creates and starts a span using the span found in
// context as parent. If no parent span is found a root span is created.
func (t *Tracer) StartSpanFromContext(ctx context.Context, name string, options ...SpanOption) (Span, context.Context) {
if parentSpan := SpanFromContext(ctx); parentSpan != nil {
options = append(options, Parent(parentSpan.Context()))
}
span := t.StartSpan(name, options...)
return span, NewContext(ctx, span)
}
// StartSpan creates and starts a span.
func (t *Tracer) StartSpan(name string, options ...SpanOption) Span {
if atomic.LoadInt32(&t.noop) == 1 {
return &noopSpan{}
}
s := &spanImpl{
SpanModel: model.SpanModel{
Kind: model.Undetermined,
Name: name,
LocalEndpoint: t.localEndpoint,
Annotations: make([]model.Annotation, 0),
Tags: make(map[string]string),
},
flushOnFinish: true,
tracer: t,
}
// add default tracer tags to span
for k, v := range t.defaultTags {
s.Tag(k, v)
}
// handle provided functional options
for _, option := range options {
option(t, s)
}
if s.TraceID.Empty() {
// create root span
s.SpanContext.TraceID = t.generate.TraceID()
s.SpanContext.ID = t.generate.SpanID(s.SpanContext.TraceID)
} else {
// valid parent context found
if t.sharedSpans && s.Kind == model.Server {
// join span
s.Shared = true
} else {
// regular child span
parentID := s.SpanContext.ID
s.SpanContext.ParentID = &parentID
s.SpanContext.ID = t.generate.SpanID(model.TraceID{})
}
}
if !s.SpanContext.Debug && s.Sampled == nil {
// deferred sampled context found, invoke sampler
sampled := t.sampler(s.SpanContext.TraceID.Low)
s.SpanContext.Sampled = &sampled
if sampled {
s.mustCollect = 1
}
} else {
if s.SpanContext.Debug || *s.Sampled {
s.mustCollect = 1
}
}
if t.unsampledNoop && s.mustCollect == 0 {
// trace not being sampled and noop requested
return &noopSpan{
SpanContext: s.SpanContext,
}
}
// add start time
if s.Timestamp.IsZero() {
s.Timestamp = time.Now()
}
return s
}
// Extract extracts a SpanContext using the provided Extractor function.
func (t *Tracer) Extract(extractor propagation.Extractor) (sc model.SpanContext) {
if atomic.LoadInt32(&t.noop) == 1 {
return
}
psc, err := extractor()
if psc != nil {
sc = *psc
}
sc.Err = err
return
}
// SetNoop allows for killswitch behavior. If set to true the tracer will return
// noopSpans and all data is dropped. This allows operators to stop tracing in
// risk scenarios. Set back to false to resume tracing.
func (t *Tracer) SetNoop(noop bool) {
if noop {
atomic.CompareAndSwapInt32(&t.noop, 0, 1)
} else {
atomic.CompareAndSwapInt32(&t.noop, 1, 0)
}
}
// LocalEndpoint returns a copy of the currently set local endpoint of the
// tracer instance.
func (t *Tracer) LocalEndpoint() *model.Endpoint {
if t.localEndpoint == nil {
return nil
}
ep := *t.localEndpoint
return &ep
}
// Copyright 2019 The OpenZipkin Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package zipkin
import (
"errors"
"github.com/openzipkin/zipkin-go/idgenerator"
"github.com/openzipkin/zipkin-go/model"
)
// Tracer Option Errors
var (
ErrInvalidEndpoint = errors.New("requires valid local endpoint")
ErrInvalidExtractFailurePolicy = errors.New("invalid extract failure policy provided")
)
// ExtractFailurePolicy deals with Extraction errors
type ExtractFailurePolicy int
// ExtractFailurePolicyOptions
const (
ExtractFailurePolicyRestart ExtractFailurePolicy = iota
ExtractFailurePolicyError
ExtractFailurePolicyTagAndRestart
)
// TracerOption allows for functional options to adjust behavior of the Tracer
// to be created with NewTracer().
type TracerOption func(o *Tracer) error
// WithLocalEndpoint sets the local endpoint of the tracer.
func WithLocalEndpoint(e *model.Endpoint) TracerOption {
return func(o *Tracer) error {
if e == nil {
o.localEndpoint = nil
return nil
}
ep := *e
o.localEndpoint = &ep
return nil
}
}
// WithExtractFailurePolicy allows one to set the ExtractFailurePolicy.
func WithExtractFailurePolicy(p ExtractFailurePolicy) TracerOption {
return func(o *Tracer) error {
if p < 0 || p > ExtractFailurePolicyTagAndRestart {
return ErrInvalidExtractFailurePolicy
}
o.extractFailurePolicy = p
return nil
}
}
// WithNoopSpan if set to true will switch to a NoopSpan implementation
// if the trace is not sampled.
func WithNoopSpan(unsampledNoop bool) TracerOption {
return func(o *Tracer) error {
o.unsampledNoop = unsampledNoop
return nil
}
}
// WithSharedSpans allows to place client-side and server-side annotations
// for a RPC call in the same span (Zipkin V1 behavior) or different spans
// (more in line with other tracing solutions). By default this Tracer
// uses shared host spans (so client-side and server-side in the same span).
func WithSharedSpans(val bool) TracerOption {
return func(o *Tracer) error {
o.sharedSpans = val
return nil
}
}
// WithSampler allows one to set a Sampler function
func WithSampler(sampler Sampler) TracerOption {
return func(o *Tracer) error {
o.sampler = sampler
return nil
}
}
// WithTraceID128Bit if set to true will instruct the Tracer to start traces
// with 128 bit TraceID's. If set to false the Tracer will start traces with
// 64 bits.
func WithTraceID128Bit(val bool) TracerOption {
return func(o *Tracer) error {
if val {
o.generate = idgenerator.NewRandom128()
} else {
o.generate = idgenerator.NewRandom64()
}
return nil
}
}
// WithIDGenerator allows one to set a custom ID Generator
func WithIDGenerator(generator idgenerator.IDGenerator) TracerOption {
return func(o *Tracer) error {
o.generate = generator
return nil
}
}
// WithTags allows one to set default tags to be added to each created span
func WithTags(tags map[string]string) TracerOption {
return func(o *Tracer) error {
for k, v := range tags {
o.defaultTags[k] = v
}
return nil
}
}
// WithNoopTracer allows one to start the Tracer as Noop implementation.
func WithNoopTracer(tracerNoop bool) TracerOption {
return func(o *Tracer) error {
if tracerNoop {
o.noop = 1
} else {
o.noop = 0
}
return nil
}
}
/.idea/
# go.opencensus.io/exporter/aws
/exporter/aws/
# Exclude vendor, use dep ensure after checkout:
/vendor/github.com/
/vendor/golang.org/
/vendor/google.golang.org/
language: go
go_import_path: go.opencensus.io
go:
- 1.11.x
env:
global:
GO111MODULE=on
before_script:
- make install-tools
script:
- make travis-ci
- go run internal/check/version.go # TODO move this to makefile
Google Inc.
# How to contribute
We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.
## Contributor License Agreement
Contributions to this project must be accompanied by a Contributor License
Agreement. You (or your employer) retain the copyright to your contribution,
this simply gives us permission to use and redistribute your contributions as
part of the project. Head over to <https://cla.developers.google.com/> to see
your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.
## Code reviews
All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult [GitHub Help] for more
information on using pull requests.
[GitHub Help]: https://help.github.com/articles/about-pull-requests/
## Instructions
Fork the repo, checkout the upstream repo to your GOPATH by:
```
$ go get -d go.opencensus.io
```
Add your fork as an origin:
```
cd $(go env GOPATH)/src/go.opencensus.io
git remote add fork git@github.com:YOUR_GITHUB_USERNAME/opencensus-go.git
```
Run tests:
```
$ make install-tools # Only first time.
$ make
```
Checkout a new branch, make modifications and push the branch to your fork:
```
$ git checkout -b feature
# edit files
$ git commit
$ git push fork feature
```
Open a pull request against the main opencensus-go repo.
## General Notes
This project uses Appveyor and Travis for CI.
The dependencies are managed with `go mod` if you work with the sources under your
`$GOPATH` you need to set the environment variable `GO111MODULE=on`.
\ No newline at end of file
# TODO: Fix this on windows.
ALL_SRC := $(shell find . -name '*.go' \
-not -path './vendor/*' \
-not -path '*/gen-go/*' \
-type f | sort)
ALL_PKGS := $(shell go list $(sort $(dir $(ALL_SRC))))
GOTEST_OPT?=-v -race -timeout 30s
GOTEST_OPT_WITH_COVERAGE = $(GOTEST_OPT) -coverprofile=coverage.txt -covermode=atomic
GOTEST=go test
GOIMPORTS=goimports
GOLINT=golint
GOVET=go vet
EMBEDMD=embedmd
# TODO decide if we need to change these names.
TRACE_ID_LINT_EXCEPTION="type name will be used as trace.TraceID by other packages"
TRACE_OPTION_LINT_EXCEPTION="type name will be used as trace.TraceOptions by other packages"
README_FILES := $(shell find . -name '*README.md' | sort | tr '\n' ' ')
.DEFAULT_GOAL := imports-lint-vet-embedmd-test
.PHONY: imports-lint-vet-embedmd-test
imports-lint-vet-embedmd-test: imports lint vet embedmd test
# TODO enable test-with-coverage in tavis
.PHONY: travis-ci
travis-ci: imports lint vet embedmd test test-386
all-pkgs:
@echo $(ALL_PKGS) | tr ' ' '\n' | sort
all-srcs:
@echo $(ALL_SRC) | tr ' ' '\n' | sort
.PHONY: test
test:
$(GOTEST) $(GOTEST_OPT) $(ALL_PKGS)
.PHONY: test-386
test-386:
GOARCH=386 $(GOTEST) -v -timeout 30s $(ALL_PKGS)
.PHONY: test-with-coverage
test-with-coverage:
$(GOTEST) $(GOTEST_OPT_WITH_COVERAGE) $(ALL_PKGS)
.PHONY: imports
imports:
@IMPORTSOUT=`$(GOIMPORTS) -l $(ALL_SRC) 2>&1`; \
if [ "$$IMPORTSOUT" ]; then \
echo "$(GOIMPORTS) FAILED => goimports the following files:\n"; \
echo "$$IMPORTSOUT\n"; \
exit 1; \
else \
echo "Imports finished successfully"; \
fi
.PHONY: lint
lint:
@LINTOUT=`$(GOLINT) $(ALL_PKGS) | grep -v $(TRACE_ID_LINT_EXCEPTION) | grep -v $(TRACE_OPTION_LINT_EXCEPTION) 2>&1`; \
if [ "$$LINTOUT" ]; then \
echo "$(GOLINT) FAILED => clean the following lint errors:\n"; \
echo "$$LINTOUT\n"; \
exit 1; \
else \
echo "Lint finished successfully"; \
fi
.PHONY: vet
vet:
# TODO: Understand why go vet downloads "github.com/google/go-cmp v0.2.0"
@VETOUT=`$(GOVET) ./... | grep -v "go: downloading" 2>&1`; \
if [ "$$VETOUT" ]; then \
echo "$(GOVET) FAILED => go vet the following files:\n"; \
echo "$$VETOUT\n"; \
exit 1; \
else \
echo "Vet finished successfully"; \
fi
.PHONY: embedmd
embedmd:
@EMBEDMDOUT=`$(EMBEDMD) -d $(README_FILES) 2>&1`; \
if [ "$$EMBEDMDOUT" ]; then \
echo "$(EMBEDMD) FAILED => embedmd the following files:\n"; \
echo "$$EMBEDMDOUT\n"; \
exit 1; \
else \
echo "Embedmd finished successfully"; \
fi
.PHONY: install-tools
install-tools:
go get -u golang.org/x/lint/golint
go get -u golang.org/x/tools/cmd/cover
go get -u golang.org/x/tools/cmd/goimports
go get -u github.com/rakyll/embedmd
# 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.
#### 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).
## 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/opencensus-integrations/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
* [New Relic][exporter-newrelic] for stats and traces
## Overview
![OpenCensus Overview](https://i.imgur.com/cf4ElHE.jpg)
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(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(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.
![Traces and spans](https://i.imgur.com/7hZwRVj.png)
### 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:
![CPU profile](https://i.imgur.com/jBKjlkw.png)
## 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/contrib.go.opencensus.io/exporter/prometheus
[exporter-stackdriver]: https://godoc.org/contrib.go.opencensus.io/exporter/stackdriver
[exporter-zipkin]: https://godoc.org/contrib.go.opencensus.io/exporter/zipkin
[exporter-jaeger]: https://godoc.org/contrib.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
[exporter-newrelic]: https://github.com/newrelic/newrelic-opencensus-exporter-go
version: "{build}"
platform: x64
clone_folder: c:\gopath\src\go.opencensus.io
environment:
GOPATH: 'c:\gopath'
GO111MODULE: 'on'
CGO_ENABLED: '0' # See: https://github.com/appveyor/ci/issues/2613
stack: go 1.11
before_test:
- go version
- go env
build: false
deploy: false
test_script:
- cd %APPVEYOR_BUILD_FOLDER%
- go build -v .\...
- go test -v .\... # No -race because cgo is disabled