Documentation
¶
Overview ¶
Package o11y core of the ex observability system, currently backed by Honeycomb's libhoney.
There are automatic tracing wrappers for both the standard Go HTTP server and for Gin.
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 AddFlattenDepthToBaggage(ctx context.Context, d int) context.Context
- func AddResultToSpan(span Span, err error)
- func AllWarning(err error) error
- func DontErrorTrace(err error) bool
- func End(span Span, err *error)
- func FlattenDepthFromBaggage(ctx context.Context) int
- 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 LogError(ctx context.Context, name string, err error, fields ...Pair)
- func NewWarning(warn string) error
- func WithBaggage(ctx context.Context, b Baggage) context.Context
- func WithProvider(ctx context.Context, p Provider) context.Context
- type Baggage
- type ClosableMetricsProvider
- type Helpers
- 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 PropagationContext
- 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 AllWarning ¶
AllWarning returns the err wrapped such that if it has Joined errors, then each error must be a warning for the returned err to respond true to IsWarning.
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 FlattenDepthFromBaggage ¶
func HandlePanic ¶
func IsWarning ¶
IsWarning returns true if any error in the chain is a warning, or if any joined errors are a warning.
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 ClosableMetricsProvider ¶
type ClosableMetricsProvider interface {
MetricsProvider
io.Closer
}
type Helpers ¶
type Helpers interface {
// ExtractPropagation pulls propagation information out of the context
ExtractPropagation(ctx context.Context) PropagationContext
// InjectPropagation adds propagation header fields into the returned root span returning
// the context carrying that span
InjectPropagation(context.Context, PropagationContext) (context.Context, Span)
// TraceIDs return standard o11y ids - used for testing
TraceIDs(ctx context.Context) (traceID, parentID string)
}
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 {
// Histogram aggregates values agent side for a period of time.
// This is similar to TimeInMilliseconds, but not limited to timing data
Histogram(name string, value float64, tags []string, rate float64) error
// TimeInMilliseconds measures timing data only. For example, how long a network call takes
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 PropagationContext ¶
type PropagationContext struct {
// Parent contains single string serialisation of just the trace parent fields
Parent string
// Headers contains the map of all context propagation headers
Headers http.Header
}
PropagationContext contains trace context values that are propagated from service to service. Typically, the Parent field is also present as a value in the Headers map. This seeming DRY breakage is so the special value for the field name of the Parent trace ID is not leaked, and accidentally depended upon.
func PropagationContextFromHeader ¶
func PropagationContextFromHeader(h http.Header) PropagationContext
PropagationContextFromHeader is a helper constructs a PropagationContext from h. It is not filtered to the headers needed for propagation. It is expected to be used as the input to InjectPropagation.
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 active span in the given context. It will return nil if there is no span available.
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
// Helpers returns some specific helper functions. Temporary optional param during the cutover to otel
Helpers(disableW3c ...bool) Helpers
}
func FromContext ¶
FromContext returns the provider stored in the context, or the default noop provider 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)
// Flatten causes all child span attributes to be set on this span, with the given prefix
Flatten(prefix string)
// End sets the duration of the span and tells the related provider that the span is complete,
// so it can do its appropriate processing. The span should not be used after End is called.
End()
}
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package honeycomb implements o11y tracing.
|
Package honeycomb implements o11y tracing. |
|
Package otel contains an o11y.Provider that emits open telemetry gRPC.
|
Package otel contains an o11y.Provider that emits open telemetry gRPC. |
|
texttrace
Package texttrace is a span exporter for otel that outputs to the ex text console format
|
Package texttrace is a span exporter for otel that outputs to the ex text console format |
|
wrappers
|
|
|
baggage
Package baggage contains the internal implementation of the o11y baggage.
|
Package baggage contains the internal implementation of the o11y baggage. |
|
o11ygin
Package o11ygin contains middleware for the Gin router.
|
Package o11ygin contains middleware for the Gin router. |
|
o11ynethttp
Package o11ynethttp contains middleware for the standard Go HTTP server.
|
Package o11ynethttp contains middleware for the standard Go HTTP server. |