dtracing

package module
v0.0.0-...-3f74543 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2022 License: Apache-2.0 Imports: 21 Imported by: 11

README

StreamingFast Tracing Library

reference License 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

Apache 2.0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetTraceID

func GetTraceID(ctx context.Context) (out trace.TraceID)

GetTraceID try to find from the context the correct TraceID associated with it. When none is found, returns an randomly generated one.

func GetTraceIDOrEmpty

func GetTraceIDOrEmpty(ctx context.Context) (out trace.TraceID)

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

func NewFixedTraceID(hexTraceID string) (out trace.TraceID)

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

func NewFixedTraceIDInContext(ctx context.Context, hexTraceID string) context.Context

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

func NewRandomTraceID() trace.TraceID

NewRandomTraceID returns a random trace ID using OpenCensus default config IDGenerator.

func NewZeroedTraceID

func NewZeroedTraceID() trace.TraceID

NewZeroedTraceID returns a mocked, fixed trace ID containing only 0s.

func NewZeroedTraceIDInContext

func NewZeroedTraceIDInContext(ctx context.Context) context.Context

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

func RegisterDevelopmentExportersFromEnv(serviceName string, sampler trace.Sampler) error

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

func RegisterZipkinExporter(serviceName string, zipkinURL string) error

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

func SetupTracing(serviceName string, options ...interface{}) error

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{}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL