自定义嵌码

对于自动嵌码不能满足需求的情况，用户可以通过Go探针API进行自定义嵌码。

为了方便对程序问题进行追踪，我们将应用程序执行过程拆分出事务和组件两个概念。

• 事务是一次服务请求的处理过程，例如：一次Web请求，或者RPC调用的server端处理过程。

• 组件是事务处理过程中各个子功能的处理过程，例如: RPC外部调用、数据库调用、NoSQL调用、消息队列访问的生产者和消费者请求、功能/逻辑算法的计算过程、模块封装的过程。

SDK API

CreateAction

/* 功能 : 创建事务组件
 * 参数 :
 *      name : 对应包/struct名
 *      method : 函数名
 * 返回值 :
 *      (事务对象指针, 错误)
 */
func CreateAction(name string, method string) (*Action, error)

GetAction

/* 功能 : 取当前协程对应的事务对象
 * 参数 : 无
 * 返回值 :
 *      事务组件对象指针
 */
GetAction() *Action

(*Action).CreateExternalComponent

/* 功能 : 创建外部调用组件
 * 参数 : 
 *         url : 外部服务调用url
 *         method : 外部调用过程识别名
 * 返回值 :
 *      外部调用组件指针
 */
func (*Action) CreateExternalComponent(url string, method string) *Component

(*Action).CreateMQComponent

/*
 * 功能 : 创建消息队列组件
 * 参数 :
 *     vender : 消息队列类型(rabbitMQ/Kafka/ActiveMQ)
 *     isConsumer : 是否消费者组件
 *     host : MQ地址
 *     queue : 消息队列名
 * 返回值 :
 *     消息队列组件指针
 */
func (*Action) CreateMQComponent(vender string, isConsumer bool, host, queue string) *Component

(*Action).CreateMongoComponent

/*
 * 功能 :  创建MongoDB访问组件
 * 参数 :
 *       host : 服务器地址
 *       database : 库名
 *       collection : collection 名
 *       op : mongo访问操作
 *       method : 组件过程识别名
 * 返回值 :
 *       MongoDB访问组件指针
 */
func (*Action) CreateMongoComponent(host, database, collection, op, method string) *Component

(*Action).CreateComponent

/*
 * 功能 : 创建自定义应用过程
 * 参数 :
 *        method : 组件过程识别名
 * 返回值 :
 *       自定义组件指针
 */
func (*Action) CreateComponent(method string) *Component

(*Action).AddRequestParam

/*
 * 功能 : 采集事务请求参数
 * 参数 : 
 *        k : 参数名
 *        v : 参数值
 * 返回值 : 无
 */
func (*Action) AddRequestParam(k string, v string)

(*Action).AddResponseParam

/*
 * 功能 : 采集事务响应参数
 * 参数 :
 *        k : 参数名
 *        v : 参数值
 * 返回值 : 无
 */
func (*Action) AddResponseParam(k string, v string)

(*Action).AddCustomParam

/*
 * 功能 : 采集自定义参数
 * 参数 :
 *        k : 参数名
 *        v : 参数值
 * 返回值 : 无
 */
func (*Action) AddCustomParam(k string, v string)

(*Action).GetTxData

/*
 * 功能 : 取事务执行性能数据 (跨应用追踪: 被调用端执行)
 * 参数 : 无
 * 返回值 : 
 *         事务性能数据
 */
func (*Action) GetTxData() string

(*Action).SetTrackID

/*
 * 功能 : 写入跨应用追踪数据 (跨应用追踪: 被调用端执行)
 * 参数 :
 *        id : 由调用端(*Component).CreateTrackID生成的, 调用过程携带到被调用端的字符串.
 * 返回值 : 无
 */
func (*Action) SetTrackID(id string)

(*Action).SetName

/*
 * 功能 : 重新设置事务名
 * 参数 :
 *      name : 定位更准确的包名/类(结构)名
 *      method : 函数名
 * 返回值 : 无
 */
func (*Action) SetName(name string, method string)

(*Action).SetHTTPMethod

/*
 * 功能 : 采集 http 请求方法
 * 参数 :
 *        httpMethod: GET/POST/HEAD/OPTIONS/PUT
 * 返回值 : 无
 */
func (*Action) SetHTTPMethod(httpMethod string)

(*Action).SetURL

/*
 * 功能 : 采集事务 URI
 * 参数 :
 *          name : 请求的URI
 * 返回值 : 无
 */
func (*Action) SetURL(name string)

(*Action).Ignore

/*
 * 功能 : 放弃本次采集的事务性能数据
 * 参数 :  无
 * 返回值 : 无
 */
func (*Action) Ignore()

(*Action).SetError

/*
 * 功能 : 采集错误数据, 抓取调用栈
 * 参数 : 
 *        e : error 对象
 * 返回值 : 无
 */
func (*Action) SetError(e interface{})

(*Action).Finish

/*
 * 功能 : 事务数据采集结束
 * 参数 :  无
 * 返回值 : 无
 */
func (*Action) Finish()

(*Action).SetStatusCode

/*
 * 功能 : 采集事务状态码
 * 参数 : 
 *      code : 事务应答状态码
 * 返回值 : 
 *        整数, 成功为0, 失败为非0
 */
func (*Action) SetStatusCode(code uint16) int

(*Component).GetAction

/*
 * 功能 : 取组件关联的事务对象
 * 参数 : 无
 * 返回值 :
 *        事务对象
 */
func (*Component) GetAction() *Action

(*Component).SetError

/*
 * 功能 : 采集组件错误
 * 参数 :
 *       e : error 对象
 *       errorType : 错误相关类型
 *       skipStack : 跳过采集的调用栈个数, 通常写0
 * 返回值 : 无
 */
func (*Component) SetError(e interface{}, errType string, skipStack int)

(*Component).Finish

/*
 * 功能 : 组件性能数据采集结束
 * 参数 : 无
 * 返回值 : 无
 */
func (*Component) Finish()

(*Component).CreateTrackID

/*
 * 功能 : 创建跨应用追踪ID字符串 (跨应用追踪: 调用端执行)
 * 参数 : 无
 * 返回值 :
 *        跨应用追踪ID信息(通过调用请求发送到被调用端)
 */
func (*Component) CreateTrackID() string

(*Component).SetTxData

/*
* 功能 : 写入被调用端事务执行性能数据 (跨应用追踪: 调用端执行). 将rpc调用返回时携带的事务数据写入 
 * 参数 :  
 *        txData : 由被调用端 (*Action).GetTxData 生成的数据
 * 返回值 : 无
 */
func (*Component) SetTxData(txData string)

(*Component).CreateComponent

/*
 * 功能 : 组件再细分子组件
 * 参数 :
 *       子组件方法名
 * 返回值 :
 *       组件对象
 */
func (*Component) CreateComponent(method string) *Component

示例

UDP服务

在下面的UDP服务示例代码中，服务处理框架和组件都是自定义的，所以事务对象的创建和组件对象的创建全部采取手动嵌码方案。具体的应用代码请参见此处。

代码嵌码前后对比：

编译：

$ go mod tidy
$ go build

运行：

• 步骤1：配置tingyun.conf文件，修改license_key为实际的授权序列号，修改collector.address 为实际的Agent Collector地址。

• 步骤2：设置环境变量并运行。

  $ export TINGYUN_GO_APP_CONFIG=tingyun.conf
  $ ./api_general &
  

访问测试：

使用本例同级文件夹提供的udp_client发送数据测试。

$ cd ../udp_client && go build
$ ./udp_client

查看应用性能数据：

在嵌码无误和配置都正确设置的情况下，应用程序启动后，登录基调听云应用与微服务控制台，就能在应用列表中看到应用 api_general 的数据了。

Web服务

在下面的Web服务示例代码中，服务处理框架是自动嵌码的，部分组件不在框架支持内，组件对象的创建采取手动嵌码方案。具体的应用代码请参见此处。

代码嵌码前后对比：

编译：

$ go mod tidy
$ go build

运行：

• 步骤1：配置tingyun.conf文件，修改license_key为实际的授权序列号，修改collector.address 为实际的Agent Collector地址。

• 步骤2：设置环境变量并运行。

  $ export TINGYUN_GO_APP_CONFIG=tingyun.conf
  $ ./api_webapp
  

访问测试：

通过浏览器访问： http://127.0.0.1:3000/test

或者使用curl命令：

$ curl http://127.0.0.1:3000/test

查看应用性能数据：

在嵌码无误和配置都正确设置的情况下，应用程序启动后，登录基调听云APM控制台，就能在应用列表中看到应用api_webapp的数据了。