package trace

import "github.com/mediocregopher/radix/trace"

Package trace contains all the types provided for tracing within the radix
package. With tracing a user is able to pull out fine-grained runtime events
as they happen, which is useful for gathering metrics, logging, performance
analysis, etc...

BIG LOUD DISCLAIMER DO NOT IGNORE THIS: while the main radix package is
stable and will always remain backwards compatible, trace is still under
active development and may undergo changes to its types and other features.
The methods in the main radix package which invoke trace types are guaranteed
to remain stable.

type ClusterRedirected struct {
AddrstringKeystringMoved, AskboolRedirectCountint// If true, then the MOVED/ASK error which was received will not be honored,
// and the call to Do will be returning the MOVED/ASK error.Finalbool
}

type ClusterTrace struct {
// StateChange is called when the cluster becomes down or becomes available again.StateChange func(ClusterStateChange)
// TopoChanged is called when the cluster's topology changed.TopoChanged func(ClusterTopoChanged)
// Redirected is called when radix.Do responded 'MOVED' or 'ASKED'.Redirected func(ClusterRedirected)
}

type PoolCommon struct {
// Network and Addr indicate the network/address the Pool was created with
// (useful for differentiating different redis instances in a Cluster).Network, Addrstring// PoolSize and BufferSize indicate the Pool size and buffer size that the
// Pool was initialized with.PoolSize, BufferSizeint
}

PoolCommon contains information which is passed into all Pool-related
callbacks.

type PoolConnClosed struct {
PoolCommon// AvailCount indicates the total number of connections the Pool is holding
// on to which are available for usage at the moment the trace occurs.AvailCountint// The reason the connection was closed.ReasonPoolConnClosedReason
}

PoolConnClosed is passed into the PoolTrace.ConnClosed callback whenever the
Pool closes a connection.

const (
// PoolConnClosedReasonPoolClosed indicates a connection was closed because
// the Close method was called on Pool.PoolConnClosedReasonPoolClosedPoolConnClosedReason = "pool closed"
// PoolConnClosedReasonBufferDrain indicates a connection was closed due to
// a buffer drain event. See radix.PoolOnFullBuffer.PoolConnClosedReasonBufferDrainPoolConnClosedReason = "buffer drained"
// PoolConnClosedReasonPoolFull indicates a connection was closed due to
// the Pool already being full. See The radix.PoolOnFull options.PoolConnClosedReasonPoolFullPoolConnClosedReason = "pool full"
)

type PoolConnCreated struct {
PoolCommon// The reason the connection was created.ReasonPoolConnCreatedReason// How long it took to create the connection.ConnectTimetime.Duration// If connection creation failed, this is the error it failed with.Errerror
}

PoolConnCreated is passed into the PoolTrace.ConnCreated callback whenever
the Pool creates a new connection.

const (
// PoolConnCreatedReasonInitialization indicates a connection was being
// created during initialization of the Pool (i.e. within NewPool).PoolConnCreatedReasonInitializationPoolConnCreatedReason = "initialization"
// PoolConnCreatedReasonRefill indicates a connection was being created
// during a refill event (see radix.PoolRefillInterval).PoolConnCreatedReasonRefillPoolConnCreatedReason = "refill"
// PoolConnCreatedReasonPoolEmpty indicates a connection was being created
// because the Pool was empty and an Action requires one. See the
// radix.PoolOnEmpty options.PoolConnCreatedReasonPoolEmptyPoolConnCreatedReason = "pool empty"
)

type PoolDoCompleted struct {
PoolCommon// AvailCount indicates the total number of connections the Pool is holding
// on to which are available for usage at the moment the trace occurs.AvailCountint// How long it took to send command.ElapsedTimetime.Duration// This is the error returned from redis.Errerror
}

PoolDoCompleted is passed into the PoolTrace.DoCompleted callback whenever Pool finished to run
Do function.

type PoolInitCompleted struct {
PoolCommon// AvailCount indicates the total number of connections the Pool is holding
// on to which are available for usage at the moment the trace occurs.AvailCountint// How long it took to fill all connections.ElapsedTimetime.Duration
}

PoolInitCompleted is passed into the PoolTrace.InitCompleted callback whenever Pool initialized.
This must be called once.

type PoolTrace struct {
// ConnCreated is called when the Pool creates a new connection. The
// provided Err indicates whether the connection successfully completed.ConnCreated func(PoolConnCreated)
// ConnClosed is called before closing the connection.ConnClosed func(PoolConnClosed)
// DoCompleted is called after command execution. Must consider race condition
// for manipulating variables in DoCompleted callback since DoComplete
// function can be called in many go-routines.DoCompleted func(PoolDoCompleted)
// InitCompleted is called after pool fills its connectionsInitCompleted func(PoolInitCompleted)
}

PoolTrace is passed into radix.NewPool via radix.PoolWithTrace, and contains
callbacks which will be triggered for specific events during the Pool's
runtime.