README
¶
StreamingFast 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 StreamingFast contribution guide, if you wish to contribute to this code base.
License
Documentation
¶
Index ¶
- func GetTraceID(ctx context.Context) (out trace.TraceID)
- func GetTraceIDOrEmpty(ctx context.Context) (out trace.TraceID)
- func IsProductionEnvironment() bool
- func NewAddTraceIDAwareLoggerMiddleware(next http.Handler, rootLogger *zap.Logger, propagation propagation.HTTPFormat) *addTraceIDMiddleware
- 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 GetTraceIDOrEmpty ¶
GetTraceIDOrEmpty tries to extract the TraceID from context or returns an empty one otherwise.
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 NewAddTraceIDAwareLoggerMiddleware ¶
func NewAddTraceIDAwareLoggerMiddleware(next http.Handler, rootLogger *zap.Logger, propagation propagation.HTTPFormat) *addTraceIDMiddleware
NewAddTraceIDAwareLoggerMiddleware returns a http.Handler wrapper so that all requests of processed by your HTTP handlers will an attached a `zap.Logger` (via the `request.Context()` value, extractable using `logging.Logger(ctx, <fallbackLogger>)` that is properly instrumented with the TraceID extracted from the actual HTTP request if present.
This handler is aware of the incoming request's trace id, reading it from request headers as configured using the Propagation field. The extracted trace id if present is used to configure the actual logger with the field `trace_id`.
If the trace id cannot be extracted from the request, a random request id is generated and used under the field `trace_id`.
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