cal

README

As of May 2019, we would like to explore evolution of cal. There's background and on https://github.com/paypal/hera/issues/25

Documentation

Overview

Package cal implements application logger for monitoring.

As of May 2019, we are slowly looking to evolve cal. There's more background on https://github.com/paypal/hera/issues/25

Index

• Constants
• func ReleaseCxtResource(_tgname ...string)
• func TxnStatus(_severity string, _module string, _sysErr string, rc ...interface{}) string
• type Activity
• type CalTimer
  • func (ct *CalTimer) Duration() float32
  • func (ct *CalTimer) Reset()
• type Client
  • func GetCalClientInstance() *Client
  • func (c *Client) GetPoolName() string
  • func (c *Client) GetPoolStack(_tgname ...string) string
  • func (c *Client) GetReleaseBuildNum() string
  • func (c *Client) IsEnabled() bool
  • func (c *Client) IsInitialized() bool
  • func (c *Client) IsPoolstackEnabled() bool
  • func (c *Client) SetParentStack(_clientpoolInfo string, _operationName string, _tgname string) (err error)
  • func (c *Client) WriteData(_msg string) error
• type Event
  • func NewCalEvent(_type string, _name string, _status string, _data string, _tgname ...string) Event
• type Flags
• type HeartBeat
  • func NewCalHeartBeat(_type string, _name string, _status string, _data string, _tgname ...string) HeartBeat
• type LogLevel
• type Transaction
  • func NewCalTransaction(_type string, _name string, _status string, _data string, _tgname string) Transaction

Constants

const (
	TransTypeClient        = "CLIENT"
	TransTypeExec          = "EXEC"
	TransTypeFetch         = "FETCH"
	TransTypeAPI           = "API"
	TransTypeURL           = "URL"
	TransTypeReplay        = "REPLAY"
	TransTypeClientSession = "CLIENT_SESSION"

	// severity code, Don't add extra level of SEVERITY
	TransOK      = "0"
	TransFatal   = "1"
	TransError   = "2"
	TransWarning = "3"

	// Addition data field name
	ErrDEscription = "ERR_DESCRIPTION"
	ErrAction      = "ERR_ACTION"

	// System error codes
	SysErrNone             = ""
	SysErrAccessDenied     = "ACCESS DENIED"
	SysErrConfig           = "CONFIG"
	SysErrConnectionFailed = "CONNECTION_FAILED"
	SysErrData             = "DATA"
	SysErrHandshake        = "HANDSHAKE"
	SysErrInternal         = "INTERNAL"
	SysErrMarkedDown       = "MARKED DOWN"
	SysErrHera             = "HERA"
	SysErrOracle           = "ORACLE"
	SysErrSQL              = "SQL"
	SysErrUnknown          = "UNKNOWN"

	// Event types
	EventTypeFatal     = "FATAL"
	EventTypeError     = "ERROR"
	EventTypeWarning   = "WARNING"
	EventTypeException = "EXCEPTION"
	EventTypeBacktrace = "Backtrace"
	EventTypePayload   = "Payload"
	EventTypeMarkup    = "MarkUp"
	EventTypeMarkdown  = "MarkDown"
	EventTypeTL        = "TL"
	EventTypeEOA       = "EOA"
	EventTypeMessage   = "MSG"

	//The name used by infrastructure to log client related information not to be used in product code.
	EventTypeClientInfo = "CLIENT_INFO"
	EventTypeServerInfo = "SERVER_INFO"

	//All cal messages for business monitoring should be done with this event type. It will be mainly used by product code.
	EventTypeBIZ = "BIZ"
)

*

• Transaction status code standard.
• For normal termination of a Transaction, the status code can simply be set to
• CAL::TRANS_OK
• For error termination, the format of the status code is as follow:
• <severity>.<module name>.<system error code>.<module return code>
• Transaction Types
• Predefined CAL Transactions TYPES, DON't REUSE these unless you are instrumenting
• new server or web application

const (
	FlagDefault = iota
	FlagPending
	FlagFinalizeRootName
	FlagSetRootStatus
)

Flags constants

const (
	//
	// name of the thread group passed in through a context.WithValue
	//
	CALThreadIDName = "ThreadId"
	DefaultTGName   = "CDTGName##%%&&**"
	//
	// @TODO max number of thread groups allowed. if client created too many groups, we
	// need a way to protect ourselves from overflowing. cal document suggests it
	// will cut off at 200 (double check).
	// each thread group still has its calmsg chain/nesting maintained separately by
	// the maps in calclient. but when writing into cal logview, different thread group
	// may end up having to share a same swimminglane.
	// the way this works is thread group name is first hashed into a 4-byte integer
	// after that the integer is modulized by 100 to produce a number between 0 and 99
	//
	CALMaxThreadNum = 100
)

*

• different from c++ calclient, go calclient support multi-threading.
• user of calclient does not need to worry about resource protection.
• the extra consideration here is to decide whether to enable thread grouping
• and, if so, how to group calmessages.
• thread grouping is controled by "cal_enable_threadgroup" in cal_client.txt.
• once enabled, user can set thread group name in each calmessage through Init().
• messages in the same thread group are put in the same swimlane in cal logview.
• if cal_enable_threadgroup!=true, all calmsgs will end up in one swimminglane.
• there is no limit on how many groups to create, but there is a limit on the number
• of swimlanes in cal logview. go client supported a maximum of 100 swimlanes.
• if number of thread groups is more than 100, some of them will share swimlanes. *
• sample usage
• et := cal.NewCalEvent(cal.EVENT_TYPE_MESSAGE, "mux_started", cal.TRANS_OK, "", "tgname")
• et.AddDataStr("key", "loadprotected")
• et.Completed()
• cal.ReleaseCxtResource("tgname") // optional. see comment
• in this case, thread group name is "tgname". *
• for a long running process, a cal user may choose to create a large number of
• thread groups. inside cal, a considerable amount of resources is allocated for
• each thread group. cal user has a better knowledge about the lifecycle
• of a particular thread group. so, it is cal user's responsibility to release
• resources allocated for a thread group at the end of its lifecycle to avoid memory
• leak. by the way, if cal user put all his calmessages under a single thread group,
• it is not required to do this cleanup since one bucket has a fixed size. only the
• growth of buckets is a concern. however, allowing calmessages from all goroutines
• to go under one thread group may lead to a messy caltxn chain and illegible output
• in cal logview *
• caltxns on different goroutine need to be put into different thread group.
• caltxn is not thread safe for managing nested caltxns from different goroutine. there is a
• known race condition in get/setcurrentcaltxn and completeAnyNestedTransactions. there
• could be a way to navigate out a thread safe solution for nested caltxn from different goroutine.
• but caltxn on one goroutine as parent of caltxn on another goroutine does not make much sense.

Functions

func ReleaseCxtResource

func ReleaseCxtResource(_tgname ...string)

ReleaseCxtResource releases the internal context

func TxnStatus

func TxnStatus(_severity string, _module string, _sysErr string, rc ...interface{}) string

TxnStatus creates the txn status string out of severity, module and error

Types

type Activity

type Activity interface {
	SetName(string)
	SetStatus(string)
	SetStatusRc(string, uint32)
	AddDataInt(string, int64)
	AddDataStr(string, string)
	AddData(string)
	GetStatus() string
	Completed()
	GetRootCalTxn() Transaction
	SetRootCalTxn(Transaction)
	GetCurrentCalTxn() Transaction
	SetCurrentCalTxn(Transaction)
	AddPoolStack()
	SetParentStack(string, string, ...string) error
	SendSQLData(string) uint32
	SetLossyRootTxnFlag()
}

Activity defines the interface into CAL sample usage

var et Event = cal.NewCalEvent(cal.EventTypeMESSAGE, "mux_started", cal.TRANS_OK, "", "tgname")
et.AddDataStr("key", "loadprotected")
et.Completed()
cal.GetCalClientInstance().ReleaseCxtResource("tgname")	// optional. see comment in calmessage.go

in this case, thread group is "tgname". see comments in calmessage.go on threadgroup

type CalTimer

type CalTimer struct {
	// contains filtered or unexported fields
}

* More enhancement is needed * Need to add more attributes to this struct, * for now this is implemented to get over of calculating time duration from calActivity.mTimeStamp (string)

func (*CalTimer) Duration

func (ct *CalTimer) Duration() float32

return time elapsed since last Reset call in 10th of micro seconds

func (*CalTimer) Reset

func (ct *CalTimer) Reset()

Reset the time to current time

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client keeps the state of the client

func GetCalClientInstance

func GetCalClientInstance() *Client

GetCalClientInstance returns the singleton instance. The very first time is called it creates and initialize the structure

func (*Client) GetPoolName

func (c *Client) GetPoolName() string

GetPoolName gets the CAL pool name

func (*Client) GetPoolStack

func (c *Client) GetPoolStack(_tgname ...string) string

GetPoolStack returns the pool stack information

func (*Client) GetReleaseBuildNum

func (c *Client) GetReleaseBuildNum() string

GetReleaseBuildNum gets the build number as a string

func (*Client) IsEnabled

func (c *Client) IsEnabled() bool

IsEnabled says if CAL is enabled

func (*Client) IsInitialized

func (c *Client) IsInitialized() bool

IsInitialized says if CAL is initialized

func (*Client) IsPoolstackEnabled

func (c *Client) IsPoolstackEnabled() bool

IsPoolstackEnabled says if pool stack is enabled

func (*Client) SetParentStack

func (c *Client) SetParentStack(_clientpoolInfo string, _operationName string, _tgname string) (err error)

SetParentStack set the CAL parent inthe stack

func (*Client) WriteData

func (c *Client) WriteData(_msg string) error

WriteData is the single place for calmessage classes to send a request to caldaemon

type Event

type Event interface {
	Activity
	SetType(string)
}

Event declares the functions for generating CAL events

func NewCalEvent

func NewCalEvent(_type string, _name string, _status string, _data string, _tgname ...string) Event

NewCalEvent creates a CAL event

type Flags

type Flags int

Flags defines the possible transaction flags

type HeartBeat

type HeartBeat interface {
	Activity
}

HeartBeat declares the functions for generating CAL heartbeat

func NewCalHeartBeat

func NewCalHeartBeat(_type string, _name string, _status string, _data string, _tgname ...string) HeartBeat

NewCalHeartBeat creates a CAL heartbeat

type LogLevel

type LogLevel int

LogLevel defines the CAL log level

type Transaction

type Transaction interface {
	Activity
	SetNameWithFlag(string, Flags)
	SetStatusWithFlag(string, Flags)
	SetRootTransactionStatus(string)
	AddDataToRoot(string, string)
	SetDuration(int)
	CompletedWithStatus(string)
	GetCorrelationID() string
	SetCorrelationID(string)
	SetOperationName(string, bool)
}

Transaction declares the functions for generating CAL transactions

func NewCalTransaction

func NewCalTransaction(_type string, _name string, _status string, _data string, _tgname string) Transaction

NewCalTransaction creates a CAL transaction