Documentation
¶
Overview ¶
Package o11y provides observability in the form of tracing and metrics
Example (EndDefer) ¶
ExampleEndDefer shows the correct way to capture the error named return.
package main
import (
"context"
"fmt"
"net"
"github.com/circleci/ex/o11y"
)
type Worker struct{}
// Work must use named returns for the defer to capture the return value correctly.
func (w *Worker) Work(ctx context.Context) (err error) {
ctx, span := o11y.StartSpan(ctx, "job-store: job-info")
defer o11y.End(span, &err) // the pointer is needed to grab the changing content of the returned error.
span.AddField("add-other", "fields as needed")
o11y.AddField(ctx, "also-via", "context")
// Do some work, using the modified context
if _, err := (&net.Dialer{}).DialContext(ctx, "tcp", "localhost:80"); err != nil {
return fmt.Errorf("i am the error the span.End call will use: %w", err)
}
return nil
}
// ExampleEndDefer shows the correct way to capture the error named return.
func main() {
ctx := context.Background()
w := Worker{}
_ = w.Work(ctx)
}
Output:
Index ¶
- Constants
- func AddField(ctx context.Context, key string, val interface{})
- func AddFieldToTrace(ctx context.Context, key string, val interface{})
- func AddResultToSpan(span Span, err error)
- func DontErrorTrace(err error) bool
- func End(span Span, err *error)
- func HandlePanic(ctx context.Context, span Span, panic interface{}, r *http.Request) (err error)
- func IsWarning(err error) bool
- func IsWarningNoUnwrap(err error) bool
- func Log(ctx context.Context, name string, fields ...Pair)
- func NewWarning(warn string) error
- func WithBaggage(ctx context.Context, baggage Baggage) context.Context
- func WithProvider(ctx context.Context, p Provider) context.Context
- type Baggage
- type Metric
- func Count(name string, valueField string, fixedTag *Tag, tagFields ...string) Metric
- func Duration(name string, valueField string, fields ...string) Metric
- func Gauge(name string, valueField string, tagFields ...string) Metric
- func Incr(name string, fields ...string) Metric
- func Timing(name string, fields ...string) Metric
- type MetricType
- type MetricsProvider
- type Pair
- type Provider
- type Span
- type Tag
Examples ¶
Constants ¶
const ( MetricTimer = "timer" MetricGauge = "gauge" MetricCount = "count" )
Variables ¶
This section is empty.
Functions ¶
func AddFieldToTrace ¶
AddFieldToTrace adds a field to the currently active root span and all of its current and future child spans
func AddResultToSpan ¶
AddResultToSpan takes a possibly nil error, and updates the "error" and "result" fields of the span appropriately.
func DontErrorTrace ¶
DontErrorTrace returns true if all errors in the chain is a warning or context canceled or context deadline errors.
func End ¶
End completes a span, including using AddResultToSpan to set the error and result fields
The correct way to capture the returned error is given in the doc example, it is like this.. defer o11y.End(span, &err)
Using the unusual pointer to the interface means that clients can call defer on End early, typically on the next line after calling StartSpan as it will capture the address of the named return error at that point. Any further assignments are made to the pointed to data, so that when our End func dereferences the pointer we get the last assigned error as desired.
func HandlePanic ¶
func IsWarningNoUnwrap ¶
IsWarningNoUnwrap returns true if err itself is a warning. This will not check wrapped errors. This can be used in Is in other errors to check if it is being directly tested for warning.
func NewWarning ¶
NewWarning will return a generic error that can be tested for warning. No two errors created with NewWarning will be tested as equal with Is.
Types ¶
type Baggage ¶
Baggage is a map of values used for telemetry purposes. See: https://github.com/open-telemetry/opentelemetry-specification/blob/14b5b6a944e390e368dd2e2ef234d220d8287d19/specification/baggage/api.md
func DeserializeBaggage ¶
func GetBaggage ¶
type Metric ¶
type Metric struct {
Type MetricType
// Name is the metric name that will be emitted
Name string
// Field is the span field to use as the metric's value
Field string
// FixedTag is an optional tag added at Metric definition time
FixedTag *Tag
// TagFields are additional span fields to use as metric tags
TagFields []string
}
type MetricType ¶
type MetricType string
type MetricsProvider ¶
type MetricsProvider interface {
TimeInMilliseconds(name string, value float64, tags []string, rate float64) error
// Gauge measures the value of a metric at a particular time.
Gauge(name string, value float64, tags []string, rate float64) error
// Count sends an individual value in time.
Count(name string, value int64, tags []string, rate float64) error
}
type Pair ¶
type Pair struct {
Key string
Value interface{}
}
Pair is a key value pair used to add metadata to a span.
type Provider ¶
type Provider interface {
// AddGlobalField adds data which should apply to every span in the application
//
// eg. version, service, k8s_replicaset
AddGlobalField(key string, val interface{})
// StartSpan begins a new span that'll represent a unit of work
//
// `name` should be a short human readable identifier of the work.
// It can and should include some details to distinguish it from other
// similar spans - like the URL or the DB query name.
//
// The caller is responsible for calling End(), usually via defer:
//
// ctx, span := o11y.StartSpan(ctx, "GET /help")
// defer span.End()
StartSpan(ctx context.Context, name string) (context.Context, Span)
// GetSpan returns the currently active span
GetSpan(ctx context.Context) Span
// AddField is for adding application-level information to the currently active span
//
// Any field name will be prefixed with "app."
AddField(ctx context.Context, key string, val interface{})
// AddFieldToTrace is for adding useful information to the root span.
//
// This will be propagated onto every child span.
//
// eg. build-url, plan-id, project-id, org-id etc
AddFieldToTrace(ctx context.Context, key string, val interface{})
// Log sends a zero duration trace event.
Log(ctx context.Context, name string, fields ...Pair)
Close(ctx context.Context)
// MetricsProvider grants lower control over the metrics that o11y sends, allowing skipping spans.
MetricsProvider() MetricsProvider
}
func FromContext ¶
FromContext returns the provider stored in the context, or nil if none exists.
type Span ¶
type Span interface {
// AddField is for adding application-level information to the span
//
// Any field name will be prefixed with "app."
AddField(key string, val interface{})
// AddRawField is for adding useful information to the span in library/plumbing code
// Generally application code should prefer AddField() to avoid namespace clashes
//
// eg. result, http.status_code, db.system etc
//
// Refer to the opentelemetry draft spec for naming inspiration
// https://github.com/open-telemetry/opentelemetry-specification/tree/7ae3d066c95c716ef3086228ef955d84ba03ac88/specification/trace/semantic_conventions
AddRawField(key string, val interface{})
// RecordMetric tells the provider to emit a metric to its metric backend when the span ends
RecordMetric(metric Metric)
// End sets the duration of the span and tells the related provider that the span is complete
// so it can do it's appropriate processing. The span should not be used after End is called.
End()
SerializeHeaders() string
}
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package honeycomb implements o11y tracing.
|
Package honeycomb implements o11y tracing. |
|
wrappers
|
|
|
o11ynethttp
Package o11ynethttp provides common http middleware for tracing requests.
|
Package o11ynethttp provides common http middleware for tracing requests. |