cat

README

cat

cat client for golang

背景

公司使用cat做监控与链路追踪，官方golang的client已经多年不维护了，使用的话还是要自己封装

变更点

• 支持了参数选项
• 支持了mod模式
• Transaction 增加 AddChild、 GetChildren方法，可组装消息树
• 增加了MessageId、ParentMessageId、RootMessageId透传
• 增加gin中间件使用示例：https://github.com/cat-go/gin-Middleware

使用

go get github.com/aaab456/cat

Quickstart

package main

import (
	"errors"
	"math/rand"
	"sync"
	"time"

	"github.com/aaab456/cat"
)

const TestType = "foo"

var wg = sync.WaitGroup{}

func init() {
	cat.DebugOn()
	cat.Init(&cat.Options{
    		AppId:      "cat-go",
    		Port:       2280,
    		HttpPort:   8080,
    		ServerAddr: "127.0.0.1",
    	})
}

// send transaction
func case1() {
	t := cat.NewTransaction(TestType, "test")
	defer t.Complete()

	if rand.Int31n(100) == 0 {
		t.SetStatus(cat.FAIL)
	}

	t.AddData("foo", "bar")

	t.NewEvent(TestType, "event-1")
	t.Complete()

	if rand.Int31n(100) == 0 {
		t.LogEvent(TestType, "event-2", cat.FAIL)
	} else {
		t.LogEvent(TestType, "event-2")
	}
	t.LogEvent(TestType, "event-3", cat.SUCCESS, "k=v")

	t.SetDurationStart(time.Now().Add(-5 * time.Second))
	t.SetTime(time.Now().Add(-5 * time.Second))
	t.SetDuration(time.Millisecond * 500)
}

// send completed transaction with duration
func case2() {
	cat.NewCompletedTransactionWithDuration(TestType, "completed", time.Second*24)
	cat.NewCompletedTransactionWithDuration(TestType, "completed-over-60s", time.Second*65)
}

// send event
func case3() {
	// way 1
	e := cat.NewEvent(TestType, "event-4")
	e.Complete()
	// way 2

	if rand.Int31n(100) == 0 {
		cat.LogEvent(TestType, "event-5", cat.FAIL)
	} else {
		cat.LogEvent(TestType, "event-5")
	}
	cat.LogEvent(TestType, "event-6", cat.SUCCESS, "foobar")
}

// send error with backtrace
func case4() {
	if rand.Int31n(100) == 0 {
		err := errors.New("error")
		cat.LogError(err)
	}
}

// send metric
func case5() {
	cat.LogMetricForCount("metric-1")
	cat.LogMetricForCount("metric-2", 3)
	cat.LogMetricForDuration("metric-3", 150*time.Millisecond)
	cat.NewMetricHelper("metric-4").Count(7)
	cat.NewMetricHelper("metric-5").Duration(time.Second)
}

func run(f func()) {
	defer wg.Done()

	for i := 0; i < 100000000; i++ {
		f()
		time.Sleep(time.Microsecond * 100)
	}
}

func start(f func()) {
	wg.Add(1)
	go run(f)
}

func main() {
	start(case1)
	start(case2)
	start(case3)
	start(case4)
	start(case5)

	wg.Wait()

	cat.Shutdown()
}

cat的一些概念

监控模型

CAT主要支持以下四种监控模型：

• Transaction 适合记录跨越系统边界的程序访问行为,比如远程调用，数据库调用，也适合执行时间较长的业务逻辑监控，Transaction用来记录一段代码的执行时间和次数
• Event 用来记录一件事发生的次数，比如记录系统异常，它和transaction相比缺少了时间的统计，开销比transaction要小
• Heartbeat 表示程序内定期产生的统计信息, 如CPU利用率, 内存利用率, 连接池状态, 系统负载等
• Metric 用于记录业务指标、指标可能包含对一个指标记录次数、记录平均值、记录总和，业务指标最低统计粒度为1分钟

主要功能

• Transaction报表 监控一段代码运行情况：运行次数、QPS、错误次数、失败率、响应时间统计（平均影响时间、Tp分位值）等等。
• Event报表 监控一段代码运行次数：例如记录程序中一个事件记录了多少次，错误了多少次。Event报表的整体结构与Transaction报表几乎一样，只缺少响应时间的统计。
• Problem报表 Problem记录整个项目在运行过程中出现的问题，包括一些异常、错误、访问较长的行为。Problem报表是由logview存在的特征整合而成，方便用户定位问题。 来源：

1. 业务代码显示调用Cat.logError(e) API进行埋点，具体埋点说明可查看埋点文档。
2. 与LOG框架集成，会捕获log日志中有异常堆栈的exception日志。
3. long-url，表示Transaction打点URL的慢请求
4. long-sql，表示Transaction打点SQL的慢请求
5. long-service，表示Transaction打点Service或者PigeonService的慢请求
6. long-call，表示Transaction打点Call或者PigeonCall的慢请求
7. long-cache，表示Transaction打点Cache.开头的慢请求

• Heartbeat报表 是CAT客户端，以一分钟为周期，定期向服务端汇报当前运行时候的一些状态。
• Business报表 对应着业务指标，比如订单指标。与Transaction、Event、Problem不同，Business更偏向于宏观上的指标，另外三者偏向于微观代码的执行情况。

声明

代码根据官方v2版本调整

Documentation

Index

• Constants
• func AddMonitorCollector(collector Collector)
• func DebugOn()
• func Init(opts *Options)
• func IsEnabled() bool
• func LogError(err error, args ...string)
• func LogErrorWithCategory(err error, category string)
• func LogEvent(mtype, name string, args ...string)
• func LogMetricForCount(name string, args ...int)
• func LogMetricForDuration(name string, duration time.Duration)
• func MessageId() string
• func NewCompletedTransactionWithDuration(mtype, name string, duration time.Duration)
• func NewEvent(mtype, name string) message.Messager
• func NewTransaction(mtype, name string) message.Transactor
• func SetChildTraceId(tran message.Transactor, sub message.Transactor)
• func Shutdown()
• type Buf
  • func (b *Buf) WriteInt(i int) (err error)
  • func (b *Buf) WriteUInt64(i uint64) (err error)
• type Collector
• type Config
  • func (config *Config) Init(opts *Options) (err error)
• type Logger
  • func (l *Logger) Debug(format string, args ...interface{})
  • func (l *Logger) Error(format string, args ...interface{})
  • func (l *Logger) Info(format string, args ...interface{})
  • func (l *Logger) Warning(format string, args ...interface{})
• type MetricHelper
  • func NewMetricHelper(name string) MetricHelper
• type Options
• type XMLConfig
• type XMLConfigServer
• type XMLConfigServers

Constants

const (
	SUCCESS = "0"
	ERROR   = "-1"
	FAIL    = "fail"
)

const (
	RootId   = "X-ROOT-MESSAGE-ID"
	ParentId = "X-ROOT-PARENT-ID"
	ChildId  = "X-ROOT-CHILD-ID"

	TypeUrl        = "URL"
	TypeUrlMethod  = "URL.method"
	TypeUrlForward = "URL.Forward"
	TypeRemoteCall = "RemoteCall"
	TypeUrlClient  = "URL.client"
	TypeRedis      = "REDIS"
	TypeRedisCmd   = "REDIS.cmd"
	TypeSql        = "SQL"
	TypeSqlOp      = "SQL.op"
	TypeSqlVal     = "SQL.val"
	TypeMQ         = "MQ"
	TypeMQTopic    = "MQ.topic"
)

const (
	GoCatVersion = "2.0.0"
)

Functions

func AddMonitorCollector

func AddMonitorCollector(collector Collector)

func DebugOn

func DebugOn()

func Init

func Init(opts *Options)

func IsEnabled

func IsEnabled() bool

func LogError

func LogError(err error, args ...string)

func LogErrorWithCategory

func LogErrorWithCategory(err error, category string)

func LogEvent

func LogEvent(mtype, name string, args ...string)

func LogMetricForCount

func LogMetricForCount(name string, args ...int)

func LogMetricForDuration

func LogMetricForDuration(name string, duration time.Duration)

func MessageId

func MessageId() string

func NewCompletedTransactionWithDuration

func NewCompletedTransactionWithDuration(mtype, name string, duration time.Duration)

func NewEvent

func NewEvent(mtype, name string) message.Messager

func NewTransaction

func NewTransaction(mtype, name string) message.Transactor

func SetChildTraceId

func SetChildTraceId(tran message.Transactor, sub message.Transactor)

func Shutdown

func Shutdown()

Types

type Buf

type Buf struct {
	bytes.Buffer
}

func (*Buf) WriteInt

func (b *Buf) WriteInt(i int) (err error)

func (*Buf) WriteUInt64

func (b *Buf) WriteUInt64(i uint64) (err error)

type Collector

type Collector interface {
	GetId() string
	GetDesc() string
	GetProperties() map[string]string
}

type Config

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

func (*Config) Init

func (config *Config) Init(opts *Options) (err error)

type Logger

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

func (*Logger) Debug

func (l *Logger) Debug(format string, args ...interface{})

func (*Logger) Error

func (l *Logger) Error(format string, args ...interface{})

func (*Logger) Info

func (l *Logger) Info(format string, args ...interface{})

func (*Logger) Warning

func (l *Logger) Warning(format string, args ...interface{})

type MetricHelper

type MetricHelper interface {
	AddTag(key, val string) MetricHelper
	Count(int)
	Duration(time.Duration)
}

func NewMetricHelper

func NewMetricHelper(name string) MetricHelper

type Options

type Options struct {
	AppId      string `json:"app_id"`
	Port       int    `json:"port"`
	HttpPort   int    `json:"http_port"`
	ServerAddr string `json:"server_addr"`
}

type XMLConfig

type XMLConfig struct {
	Name    xml.Name         `xml:"config"`
	Servers XMLConfigServers `xml:"servers"`
}

type XMLConfigServer

type XMLConfigServer struct {
	Host string `xml:"ip,attr"`
	Port int    `xml:"port,attr"`
}

type XMLConfigServers

type XMLConfigServers struct {
	Servers []XMLConfigServer `xml:"server"`
}