Documentation ¶
Overview ¶
Package splunktracing implements the Splunk OpenTracing client for Go.
Index ¶
- Constants
- func Close(ctx context.Context, tracer opentracing.Tracer)
- func CloseTracer(tracer opentracing.Tracer) error
- func Flush(ctx context.Context, tracer opentracing.Tracer)
- func FlushSplunkTracer(tracer opentracing.Tracer) error
- func GetSplunkAccessToken(tracer opentracing.Tracer) (string, error)
- func GetSplunkReporterID(tracer opentracing.Tracer) (uint64, error)
- func SetGlobalEventHandler(handler EventHandler)
- type Connection
- type ConnectorFactory
- type Endpoint
- type ErrorEvent
- type Event
- type EventConnectionError
- type EventFlushError
- type EventFlushErrorState
- type EventHandler
- type EventStartError
- type EventStatusReport
- type EventTracerDisabled
- type EventUnsupportedTracer
- type EventUnsupportedValue
- type Options
- type RawSpan
- type SetParentSpanID
- type SetSpanID
- type SetTraceID
- type SpanContext
- type SpanRecorder
- type Tracer
- type Tracerv0_14
Constants ¶
const ( DefaultCollectorPath = "/services/collector/events" DefaultPlainPort = 8088 DefaultSecurePort = 8088 DefaultCollectorHost = "127.0.0.1" DefaultMaxReportingPeriod = 2500 * time.Millisecond DefaultMinReportingPeriod = 500 * time.Millisecond DefaultMaxSpans = 1000 DefaultReportTimeout = 30 * time.Second DefaultReconnectPeriod = 5 * time.Minute DefaultMaxLogKeyLen = 256 DefaultMaxLogValueLen = 1024 DefaultMaxLogsPerSpan = 500 DefaultMaxCallSendMsgSizeBytes = math.MaxInt32 )
Default Option values.
const ( ParentSpanGUIDKey = "parent_span_id" // ParentSpanGUIDKey is the tag key used to record the relationship between child and parent spans. ComponentNameKey = "component_name" GUIDKey = "guid" // <- runtime guid, not span guid HostnameKey = "device" CommandLineKey = "command_line" TracerPlatformKey = "tracer_platform" TracerPlatformValue = "go" TracerPlatformVersionKey = "tracer_platform_version" TracerVersionKey = "tracer_version" // Note: TracerVersionValue is generated from ./VERSION )
Tag and Tracer Attribute keys.
const SPLMetaEvent_ExtractOperation = "splunk.extract_span"
operation names for splunk meta span events
const SPLMetaEvent_InjectOperation = "splunk.inject_span"
const SPLMetaEvent_MetaEventKey = "splunk.meta_event"
keys for splunk meta span events
const SPLMetaEvent_PropagationFormatKey = "splunk.propagation_format"
const SPLMetaEvent_SpanFinishOperation = "splunk.span_finish"
const SPLMetaEvent_SpanIdKey = "splunk.span_id"
const SPLMetaEvent_SpanStartOperation = "splunk.span_start"
const SPLMetaEvent_TraceIdKey = "splunk.trace_id"
const SPLMetaEvent_TracerCreateOperation = "splunk.tracer_create"
const SPLMetaEvent_TracerGuidKey = "splunk.tracer_guid"
const TracerVersionValue = "0.1.0"
TracerVersionValue provides the current version of the splunk-tracer-go release
Variables ¶
This section is empty.
Functions ¶
func CloseTracer ¶
func CloseTracer(tracer opentracing.Tracer) error
CloseTracer closes the tracer DEPRECATED: use Close instead.
func FlushSplunkTracer ¶
func FlushSplunkTracer(tracer opentracing.Tracer) error
FlushSplunkTracer flushes the tracer DEPRECATED: use Flush instead.
func GetSplunkAccessToken ¶
GetSplunkAccessToken returns the currently configured AccessToken.
func GetSplunkReporterID ¶
GetSplunkReporterID returns the currently configured Reporter ID.
func SetGlobalEventHandler ¶
func SetGlobalEventHandler(handler EventHandler)
SetGlobalEventHandler sets a global handler to receive tracer events as they occur. Events may be emitted by the tracer, or by calls to static functions in this package. It is suggested that you set your EventHandler before starting your tracer, but it is safe to set a new handler at any time. Setting a new handler removes the previous one.
The EventHandler is called synchronously – do not block in your handler as it may interfere with the tracer. If no EventHandler handler is set, a LogOnceOnError handler is set by default.
NOTE: Event handling is for reporting purposes only. It is not intended as a mechanism for controling or restarting the tracer. Connection issues, retry logic, and other transient errors are handled internally by the tracer.
Types ¶
type Connection ¶
Connection describes a closable connection. Exposed for testing.
type ConnectorFactory ¶
type ConnectorFactory func() (interface{}, Connection, error)
ConnectorFactory is for testing purposes.
type Endpoint ¶
type Endpoint struct { Scheme string `yaml:"scheme" json:"scheme" usage:"scheme to use for the endpoint, defaults to appropriate one if no custom one is required"` Host string `yaml:"host" json:"host" usage:"host on which the endpoint is running"` Port int `yaml:"port" json:"port" usage:"port on which the endpoint is listening"` Plaintext bool `yaml:"plaintext" json:"plaintext" usage:"whether or not to encrypt data send to the endpoint"` CustomCACertFile string `` /* 136-byte string literal not displayed */ }
Endpoint describes a collector or web API host/port and whether or not to use plaintext communication.
func (Endpoint) SocketAddress ¶
SocketAddress returns an address suitable for dialing grpc connections
type ErrorEvent ¶
The ErrorEvent type can be used to filter events. The `Err` method retuns the underlying error.
type Event ¶
type Event interface { Event() String() string }
An Event is emitted by the LightStep tracer as a reporting mechanism. They are handled by registering an EventHandler callback via SetGlobalEventHandler. The emitted events may be cast to specific event types in order access additional information.
NOTE: To ensure that events can be accurately identified, each event type contains a sentinel method matching the name of the type. This method is a no-op, it is only used for type coersion.
type EventConnectionError ¶
type EventConnectionError interface { ErrorEvent EventConnectionError() }
EventConnectionError occurs when the tracer fails to maintain it's connection with the Collector.
type EventFlushError ¶
type EventFlushError interface { ErrorEvent EventFlushError() State() EventFlushErrorState }
EventFlushError occurs when a flush fails to send. Call the `State` method to determine the type of error.
type EventFlushErrorState ¶
type EventFlushErrorState string
EventFlushErrorState lists the possible causes for a flush to fail.
const ( FlushErrorTracerClosed EventFlushErrorState = "flush failed, the tracer is closed." FlushErrorTracerDisabled EventFlushErrorState = "flush failed, the tracer is disabled." FlushErrorTransport EventFlushErrorState = "flush failed, could not send report to Collector" FlushErrorReport EventFlushErrorState = "flush failed, report contained errors" FlushErrorTranslate EventFlushErrorState = "flush failed, could not translate report" )
Constant strings corresponding to flush errors
type EventHandler ¶
type EventHandler func(Event)
An EventHandler can be registered with SetGlobalEventHandler to
func NewEventChannel ¶
func NewEventChannel(buffer int) (EventHandler, <-chan Event)
NewEventChannel returns an SetGlobalEventHandler callback handler, and a channel that produces the errors. When the channel buffer is full, subsequent errors will be dropped. A buffer size of less than one is incorrect, and will be adjusted to a buffer size of one.
func NewEventLogOneError ¶
func NewEventLogOneError() EventHandler
NewEventLogOneError logs the first error event that occurs.
func NewEventLogger ¶
func NewEventLogger() EventHandler
NewEventLogger logs events using the standard go logger.
type EventStartError ¶
type EventStartError interface { ErrorEvent EventStartError() }
EventStartError occurs if the Options passed to NewTracer are invalid, and the Tracer has failed to start.
type EventStatusReport ¶
type EventStatusReport interface { Event EventStatusReport() StartTime() time.Time FinishTime() time.Time Duration() time.Duration SentSpans() int DroppedSpans() int EncodingErrors() int }
EventStatusReport occurs on every successful flush. It contains all metrics collected since the previous succesful flush.
type EventTracerDisabled ¶
type EventTracerDisabled interface { Event EventTracerDisabled() }
EventTracerDisabled occurs when a tracer is disabled by either the user or the collector.
type EventUnsupportedTracer ¶
type EventUnsupportedTracer interface { ErrorEvent EventUnsupportedTracer() Tracer() opentracing.Tracer }
EventUnsupportedTracer occurs when a tracer being passed to a helper function fails to typecast as a LightStep tracer.
type EventUnsupportedValue ¶
type EventUnsupportedValue interface { ErrorEvent EventUnsupportedValue() Key() string Value() interface{} }
EventUnsupportedValue occurs when a tracer encounters an unserializable tag or log field.
type Options ¶
type Options struct { // AccessToken is the unique API key for your Splunk project. It is // available on your account page at https://app.splunk.com/account AccessToken string `yaml:"access_token" usage:"access token for reporting to Splunk"` // Collector is the host, port, and plaintext option to use // for the collector. Collector Endpoint `yaml:"collector"` // Tags are arbitrary key-value pairs that apply to all spans generated by // this Tracer. Tags opentracing.Tags // Splunk is the host, port, and plaintext option to use // for the Splunk HEC API. SplunkAPI Endpoint `yaml:"splunk_hec_api"` // MaxBufferedSpans is the maximum number of spans that will be buffered // before sending them to a collector. MaxBufferedSpans int `yaml:"max_buffered_spans"` // MaxLogKeyLen is the maximum allowable size (in characters) of an // OpenTracing logging key. Longer keys are truncated. MaxLogKeyLen int `yaml:"max_log_key_len"` // MaxLogValueLen is the maximum allowable size (in characters) of an // OpenTracing logging value. Longer values are truncated. Only applies to // variable-length value types (strings, interface{}, etc). MaxLogValueLen int `yaml:"max_log_value_len"` // MaxLogsPerSpan limits the number of logs in a single span. MaxLogsPerSpan int `yaml:"max_logs_per_span"` // GRPCMaxCallSendMsgSizeBytes limits the size in bytes of grpc messages // sent by a client. MaxCallSendMsgSizeBytes int `yaml:"max_call_send_msg_size_bytes"` // ReportingPeriod is the maximum duration of time between sending spans // to a collector. If zero, the default will be used. ReportingPeriod time.Duration `yaml:"reporting_period"` // MinReportingPeriod is the minimum duration of time between sending spans // to a collector. If zero, the default will be used. It is strongly // recommended to use the default. MinReportingPeriod time.Duration `yaml:"min_reporting_period"` ReportTimeout time.Duration `yaml:"report_timeout"` // DropSpanLogs turns log events on all Spans into no-ops. DropSpanLogs bool `yaml:"drop_span_logs"` // DEPRECATED: The Splunk library prints the first error to stdout by default. // See the documentation on the SetGlobalEventHandler function for guidance on // how to integrate tracer diagnostics with your application's logging and // metrics systems. Verbose bool `yaml:"verbose"` // Force the use of a specific transport protocol. If multiple are set to true, // the following order is used to select for the first option: http, grpc. // If none are set to true, GRPC is defaulted to. UseHttp bool `yaml:"use_http"` ReconnectPeriod time.Duration `yaml:"reconnect_period"` // A hook for receiving finished span events Recorder SpanRecorder `yaml:"-" json:"-"` // For testing purposes only ConnFactory ConnectorFactory `yaml:"-" json:"-"` // Enable Splunk Meta Event Logging MetaEventReportingEnabled bool `yaml:"meta_event_reporting_enabled" json:"meta_event_reporting_enabled"` }
Options control how the Splunk Tracer behaves.
func (*Options) Initialize ¶
Initialize validates options, and sets default values for unset options. This is called automatically when creating a new Tracer.
type RawSpan ¶
type RawSpan struct { // Those recording the RawSpan should also record the contents of its // SpanContext. Context SpanContext // The SpanID of this SpanContext's first intra-trace reference (i.e., // "parent"), or 0 if there is no parent. ParentSpanID uint64 // The name of the "operation" this span is an instance of. (Called a "span // name" in some implementations) Operation string // We store <start, duration> rather than <start, end> so that only // one of the timestamps has global clock uncertainty issues. Start time.Time Duration time.Duration // Essentially an extension mechanism. Can be used for many purposes, // not to be enumerated here. Tags opentracing.Tags // The span's "microlog". Logs []opentracing.LogRecord }
RawSpan encapsulates all state associated with a (finished) Splunk Span.
type SetParentSpanID ¶
type SetParentSpanID uint64
SetParentSpanID is an opentracing.StartSpanOption that sets an explicit parent SpanID. It must be used in conjunction with SetTraceID or the result is undefined. If the value is zero, it will be disregarded. If a ChildOf or FollowsFrom span relation is also set in the start options, it will override this value.
func (SetParentSpanID) Apply ¶
func (sid SetParentSpanID) Apply(sso *opentracing.StartSpanOptions)
Apply satisfies the StartSpanOption interface.
type SetSpanID ¶
type SetSpanID uint64
SetSpanID is a opentracing.StartSpanOption that sets an explicit SpanID. It must be used in conjunction with SetTraceID or the result is undefined.
type SetTraceID ¶
type SetTraceID uint64
SetTraceID is an opentracing.StartSpanOption that sets an explicit TraceID. It must be used in order to set an explicit SpanID or ParentSpanID. If a ChildOf or FollowsFrom span relation is also set in the start options, it will override this value.
func (SetTraceID) Apply ¶
func (sid SetTraceID) Apply(sso *opentracing.StartSpanOptions)
Apply satisfies the StartSpanOption interface.
type SpanContext ¶
type SpanContext struct { // A probabilistically unique identifier for a [multi-span] trace. TraceID uint64 // A probabilistically unique identifier for a span. SpanID uint64 // The span's associated baggage. Baggage map[string]string // initialized on first use }
SpanContext holds Splunk-specific Span metadata.
func (SpanContext) ForeachBaggageItem ¶
func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)
ForeachBaggageItem belongs to the opentracing.SpanContext interface
func (SpanContext) WithBaggageItem ¶
func (c SpanContext) WithBaggageItem(key, val string) SpanContext
WithBaggageItem returns an entirely new basictracer SpanContext with the given key:value baggage pair set.
type SpanRecorder ¶
type SpanRecorder interface {
RecordSpan(RawSpan)
}
A SpanRecorder handles all of the `RawSpan` data generated via an associated `Tracer` instance.
type Tracer ¶
type Tracer interface { opentracing.Tracer // Close flushes and then terminates the Splunk collector Close(context.Context) // Flush sends all spans currently in the buffer to the LighStep collector Flush(context.Context) // Options gets the Options used in New() or NewWithOptions(). Options() Options // Disable prevents the tracer from recording spans or flushing Disable() }
Tracer extends the `opentracing.Tracer` interface with methods for manual flushing and closing. To access these methods, you can take the global tracer and typecast it to a `splunktracing.Tracer`. As a convenience, the splunktracing package provides static functions which perform the typecasting.
type Tracerv0_14 ¶
type Tracerv0_14 interface { opentracing.Tracer // DEPRECATED: error is always nil. Equivalent to Tracer.Close(context.Background()) Close() error // DEPRECATED: error is always nil. Equivalent to Tracer.Flush(context.Background()) Flush() error // Options gets the Options used in New(). Options() Options // Disable prevents the tracer from recording spans or flushing. Disable() }
Tracerv0_14 matches the Tracer interface from v0.14.0 DEPRECATED
func NewTracerv0_14 ¶
func NewTracerv0_14(opts Options) Tracerv0_14
NewTracerv0_14 returns a tracer which conforms to the Tracer interface from v0.14.0, for backwards compatibility. DEPRECATED