README
¶
dfuse Tracing Library
This repository contains all common stuff around trace(s) handling across our
various services
Philosophy
The package provides a quick setup function with sensible defaults that can be used across all our micro-services in one shot.
The SetupTracing function make sensible decisions to setup tracing exporters based
on the environment. If in production, registers the StackDriver exporter
with a probability sampler of 1/4. In development, registers exporters based on environment
variables TRACING_ZAP_EXPORTER (zap exporter) and TRACING_ZIPKIN_EXPORTER=zipkinURL for
ZipKin exporter.
For easier customization in package, we also exposes all Register* functions so it's possible
to easily customize the behavior.
Contributing
Issues and PR in this repo related strictly to the dtracing library.
Report any protocol-specific issues in their respective repositories
Please first refer to the general dfuse contribution guide, if you wish to contribute to this code base.
License
Documentation
¶
Index ¶
- func GetTraceID(ctx context.Context) (out trace.TraceID)
- func IsProductionEnvironment() bool
- func NewFixedTraceID(hexTraceID string) (out trace.TraceID)
- func NewFixedTraceIDInContext(ctx context.Context, hexTraceID string) context.Context
- func NewRandomTraceID() trace.TraceID
- func NewZeroedTraceID() trace.TraceID
- func NewZeroedTraceIDInContext(ctx context.Context) context.Context
- func RegisterDevelopmentExportersFromEnv(serviceName string, sampler trace.Sampler) error
- func RegisterStackDriverExporter(serviceName string, sampler trace.Sampler, options stackdriver.Options) error
- func RegisterZapExporter()
- func RegisterZipkinExporter(serviceName string, zipkinURL string) error
- func SetupTracing(serviceName string, options ...interface{}) error
- func StartFreshSpan(ctx context.Context, name string, keyedAttributes ...interface{}) (context.Context, *trace.Span)
- func StartFreshSpanA(ctx context.Context, name string, attributes ...trace.Attribute) (context.Context, *trace.Span)
- func StartFreshSpanWithSampler(ctx context.Context, name string, sampler trace.Sampler, ...) (context.Context, *trace.Span)
- func StartFreshSpanWithSamplerA(ctx context.Context, name string, sampler trace.Sampler, ...) (context.Context, *trace.Span)
- func StartSpan(ctx context.Context, name string, keyedAttributes ...interface{}) (context.Context, *trace.Span)
- func StartSpanA(ctx context.Context, name string, attributes ...trace.Attribute) (context.Context, *trace.Span)
- func StartSpanWithSampler(ctx context.Context, name string, sampler trace.Sampler, ...) (context.Context, *trace.Span)
- func StartSpanWithSamplerA(ctx context.Context, name string, sampler trace.Sampler, ...) (context.Context, *trace.Span)
- type TraceAttributes
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetTraceID ¶
GetTraceID try to find from the context the correct TraceID associated with it. When none is found, returns an randomly generated one.
func IsProductionEnvironment ¶
func IsProductionEnvironment() bool
IsProductionEnvironment determines if we are in a production or a development environment. When file `/.dockerenv` is present, assuming it's production, development otherwise
func NewFixedTraceID ¶
NewFixedTraceID returns a mocked, fixed trace ID from an hexadecimal string. The string in question must be a valid hexadecimal string containing exactly 32 characters (16 bytes). Any invalid input results in a panic.
func NewFixedTraceIDInContext ¶
NewFixedTraceIDInContext is similar to NewFixedTraceID but will actually insert the span straight into a context that can later be used to ensure the trace id is controlled.
This should be use only in testing to provide a fixed trace ID instead of generating a new one each time.
func NewRandomTraceID ¶
NewRandomTraceID returns a random trace ID using OpenCensus default config IDGenerator.
func NewZeroedTraceID ¶
NewZeroedTraceID returns a mocked, fixed trace ID containing only 0s.
func NewZeroedTraceIDInContext ¶
NewZeroedTraceIDInContext is similar to NewZeroedTraceID but will actually insert the span straight into a context that can later be used to ensure the trace id is controlled.
This should be use only in testing to provide a fixed trace ID instead of generating a new one each time.
func RegisterDevelopmentExportersFromEnv ¶
RegisterDevelopmentExportersFromEnv registers exporters based on environment variables "TRACING_ZAP_EXPORTER" (zap exporter) and `TRACING_ZIPKIN_EXPORTER=zipkinURL` for Zipkin exporter.
func RegisterStackDriverExporter ¶
func RegisterStackDriverExporter(serviceName string, sampler trace.Sampler, options stackdriver.Options) error
RegisterStackDriverExporter registers the production `StackDriver` exporter for all traces. Uses the `sampler` as the default sampler for all traces. The service name is also added a a label to all traces created.
func RegisterZapExporter ¶
func RegisterZapExporter()
RegisterZapExporter registers a Zap exporter that exports all traces to zlog instance of this package.
func RegisterZipkinExporter ¶
RegisterZipkinExporter registers a ZipKin exporter that exports all traces to a zipkin instance pointed by `zipkinURL`. Note the `zipkinURL` must be the full path of the export function.
func SetupTracing ¶
SetupTracing make sensible decision to setup tracing exporters based on the environment.
If in production, registers the `StackDriver` exporter. It defines two pre-defined attribute for all traces. It defines `serviceName` attribute (receiver in parameter here) and it defiens `pod` which corresponds to `hostname` resolution.
In development, registers exporters based on environment variables "TRACING_ZAP_EXPORTER" (zap exporter) and `TRACING_ZIPKIN_EXPORTER=zipkinURL` for Zipkin exporter.
Options: - A `trace.Sampler` instance: sets `trace` default config `DefaultSampler` value to this value (defaults `1/4.0`) - A `dtracing.TraceAttributes` instance: sets additional StackDriver default attributes (defaults to `nil`)
func StartFreshSpan ¶
func StartFreshSpan(ctx context.Context, name string, keyedAttributes ...interface{}) (context.Context, *trace.Span)
StartFreshSpan has exact same behavior as StartSpan expect it always starts new fresh trace & span
func StartFreshSpanA ¶
func StartFreshSpanA(ctx context.Context, name string, attributes ...trace.Attribute) (context.Context, *trace.Span)
StartFreshSpanWithSamplerA has exact same behavior as StartSpanWithSamplerA expect it always starts new fresh trace & span
func StartFreshSpanWithSampler ¶
func StartFreshSpanWithSampler(ctx context.Context, name string, sampler trace.Sampler, keyedAttributes ...interface{}) (context.Context, *trace.Span)
StartFreshSpanWithSampler has exact same behavior as StartSpanWithSampler expect it always starts new fresh trace & span
func StartFreshSpanWithSamplerA ¶
func StartFreshSpanWithSamplerA(ctx context.Context, name string, sampler trace.Sampler, attributes ...trace.Attribute) (context.Context, *trace.Span)
StartFreshSpanWithSamplerA has exact same behavior as StartSpanWithSamplerA expect it always starts new fresh trace & span
func StartSpan ¶
func StartSpan(ctx context.Context, name string, keyedAttributes ...interface{}) (context.Context, *trace.Span)
StartSpan starts a `trace.Span` using a sugaring way of adding attributes. This has some drawback since we peform some computation to correctly resolve the attribute to their `trace.*Attribute(..., ...)` values.
If you are creating your span in a tight loop, you are better off using `StartSpanA` which accepts `trace.Attribute` directly.
func StartSpanA ¶
func StartSpanA(ctx context.Context, name string, attributes ...trace.Attribute) (context.Context, *trace.Span)
StartSpanA starts a `trace.Span` which accepts a variadic list of `trace.Attribute` directly.
func StartSpanWithSampler ¶
func StartSpanWithSampler(ctx context.Context, name string, sampler trace.Sampler, keyedAttributes ...interface{}) (context.Context, *trace.Span)
StartSpanWithSampler starts a `trace.Span` just like `StartSpan` accepting the same set of arguments alongside a new `sampler`.
func StartSpanWithSamplerA ¶
func StartSpanWithSamplerA(ctx context.Context, name string, sampler trace.Sampler, attributes ...trace.Attribute) (context.Context, *trace.Span)
StartSpanWithSamplerA starts a `trace.Span` just like `StartSpanA` accepting the same set of arguments alongside a new `sampler` value for the trace.
Types ¶
type TraceAttributes ¶
type TraceAttributes map[string]interface{}
Source Files