protocol

Documentation

Index

• Constants
• func AddHeader(msg []byte, threadId uint32) []byte
• func CleanNamespace(s string) string
• func CleanStatus(s string) string
• type CalMessage
  • func NewMsg(class byte, typ, name string) *CalMessage
  • func ParseMsg(b []byte) (*CalMessage, error)
  • func (m *CalMessage) Encode() []byte
  • func (m *CalMessage) PrettyPrintCalMessage()
  • func (m *CalMessage) String() string
• type ClientInfo
  • func (c *ClientInfo) Encode() []byte
• type Data
• type MsgHeader
  • func ParseMsgHeader(b []byte) *MsgHeader
  • func (h MsgHeader) Encode(b []byte)
• type ServiceCallInfo
  • func (p *ServiceCallInfo) Chain(parentChain string) string
  • func (p *ServiceCallInfo) Encode() string
• type Txn
  • func NewTxn(typ string, name string) *Txn
  • func (t *Txn) Done()

Constants

const (
	TxnStart  = 't'
	TxnEnd    = 'T'
	AtomicTxn = 'A'
	Event     = 'E'
	Heartbeat = 'H'
)

CAL message Class field options

const (
	CalTypeFile   string = "FILE"
	CalTypeSocket string = "SOCKET"
)

CAL logging type

const MaxMsgBufferSize = 10000

const MaxMsgLen = 4096

maxMsgLen is the longest wire-formatted message length of CAL messages. Note that wire formatting adds bytes. This is exported only to document that messages will be truncated somewhere around a size of 4k.

const MaxNamespaceLen = 127

MaxNamespaceLen is the longest allowed string for CAL namespace (Msg's Name or Type) fields. If a Name or Type is longer than MaxNamespaceLen, it will be truncated at (MaxNamespaceLen-1) bytes and have a "+" appended to it.

const MsgHeaderLen = 12

Length of encoded MsgHeaders.

Functions

func AddHeader

func AddHeader(msg []byte, threadId uint32) []byte

AddHeader returns data ready for sending to the CAL daemon by returning msg prepended by a CAL message header.

func CleanNamespace

func CleanNamespace(s string) string

CleanNamespace makes s an appropriate CAL namespace (Type or Name) field by dropping disallowed characters, truncating it as necessary, and substituting namespaceUnset for "".

func CleanStatus

func CleanStatus(s string) string

CleanStatus makes s an appropriate CAL status.

Types

type CalMessage

type CalMessage struct {
	Class     byte // ASCII character
	CreatedAt time.Time
	Type      string
	Name      string
	Status    string // TODO make this Status type
	Duration  time.Duration
	Data      []byte
}

Msg is a single log message. TODO: Document (if only by reference) the intended use of the fields, and which the user should set and which the client sets.

func NewMsg

func NewMsg(class byte, typ, name string) *CalMessage

NewMsg creates a new Msg with required fields populated. NewMsg automatically sets CreatedAt and records the active goroutine. If class is not one of the CAL class constants defined in this package, NewMsg will return nil.

func ParseMsg

func ParseMsg(b []byte) (*CalMessage, error)

ParseMsg parses an encoded CAL message. Note that encoded messages do not include the CreatedAt date, only the time. ParseMsg selects the most recent non-future date available for the provided timestamp.

func (*CalMessage) Encode

func (m *CalMessage) Encode() []byte

Encode prepares a CAL message for sending over the wire. Encode sanitizes Type, Name, and Status, and sets CreatedAt and ThreadId if they are not already set.

func (*CalMessage) PrettyPrintCalMessage

func (m *CalMessage) PrettyPrintCalMessage()

func (*CalMessage) String

func (m *CalMessage) String() string

type ClientInfo

type ClientInfo struct {
	Service     string    // name of service
	Hostname    string    // name of the local host
	Environment string    // defaults to "PayPal"
	Label       string    // defaults to "go;***;default"
	Start       time.Time // time of first connection from client; defaults to time.Now
}

ClientInfo is info sent once by the client on initial connection to the server.

func (*ClientInfo) Encode

func (c *ClientInfo) Encode() []byte

Encode encodes c for sending over the wire. If Environment, Label, or Start are not set, Encode initializes them to their default values.

type Data

type Data map[string]interface{}

Data is the data that gets sent with CAL messages. TODO: Better docs.

type MsgHeader

type MsgHeader struct {
	ThreadId  uint32 // active thread (or goroutine) of logging code
	Timestamp uint32 // time when the message was sent
	MsgLen    uint32 // length of entire encoded message to follow
}

MsgHeader is a header sent before all individual CAL messages, including the ClientInfo sent on initial connection.

func ParseMsgHeader

func ParseMsgHeader(b []byte) *MsgHeader

ParseMsgHeader parses b; b is assumed to have come off the wire. ParseMsgHeader panics if len(b) != 12.

func (MsgHeader) Encode

func (h MsgHeader) Encode(b []byte)

Encode encodes h into the first MsgHeaderLen bytes of b. Encode panics if len(b) < MsgHeaderLen.

type ServiceCallInfo

type ServiceCallInfo struct {
	ServiceName      string
	OperationName    string
	ThreadId         uint32
	RootTxnStartTime *time.Time // nil or the time the root txn started
	Hostname         string     // name of the local host
}

ServiceCallInfo represents a single node within a chain of service calls. In other CAL clients, this is called PoolInfo.

func (*ServiceCallInfo) Chain

func (p *ServiceCallInfo) Chain(parentChain string) string

Chain appends this ServiceCallInfo to the parentChain of call chain info. Use "" for parentChain to start a new chain. In other CAL clients, the resulting string would be called a PoolStack.

func (*ServiceCallInfo) Encode

func (p *ServiceCallInfo) Encode() string

type Txn

type Txn struct {
	Start *CalMessage
	End   *CalMessage
}

Txn contains a pair of events that MUST ALWAYS be sent in pairs. See Logger.NewTxn() for expected usage.

func NewTxn

func NewTxn(typ string, name string) *Txn

NewTxn creates a new transaction and populates Txn.Start and Txn.End by calling NewMsg with the specified typ and name.

func (*Txn) Done

func (t *Txn) Done()

Done completes a transaction by setting t.End. t.End is created with NewMsg, using the type and name from t.Start, and calculating t.End's duration appropriately.