SDK API
由于C/C++应用程序框架/架构的多样性，基调听云3.0 CSDK 提供两套SDK方法，分别用于异步方式调用的框架和同步方式调用的框架。
头文件引入:
#include <tingyun.h>
初始化SDK:
void TingYunAgentInit();
探针初始化函数。
这个函数不是必须要显式调用。
当应用代码中没有调用这个函数时，在首次事务埋点触发时，这个函数会被隐式调用 。
由于探针的初始化过程是异步方式在后台进行的，因此在探针初始化完成前的事务数据不会被采集 。
异步API方法
创建事务
说明：应用性能分解过程中，我们使用Action定义一个完整事务，通常它对应的是一个完整的http请求过程。
代码：
//参数:
// uri : 是Action对应的事务名，为空串则使用所在函数的类名::函数名 。
// 返回值 : 事务Id 。
TActionId CreateAction(const char *uri);
//功能: 定义一个事务过程 。
//调用时机: 客户端请求处理过程开始时 。
创建后台任务
说明：服务端应用中，可能会产生某些服务响应之外的事务处理过程，比如某些定时过程等。我们将其定义为后台任务。
代码：
//参数:
// cmd : 是后台事务对应的事务名，为空串则使用所在函数的类名::函数名 。
// 返回值 : 事务Id 。
TActionId CreateBackGroundAction(const char *cmd);
//功能: 定义一个后台事务过程 。
//调用时机: 后台事务开始时 。
结束事务
说明：事务结束时调用的方法,以次测量分析事务的执行过程 。
代码：
//参数:
// action : 事务id 。
void ActionDestroy(TActionId action);
//功能: 结束事务过程 。
//调用时机: 事务处理过程结束时 。
//说明: ActionDestroy调用之后,即表示事务的数据采集过程完成,此后action和由action创建的所有component将失效 。
创建Component
Component说明
一个事务通常会包含多个组件过程，组件过程还可能继续分解成几个其他组件过程。我们将这样的子过程定义为Component,通过对Component树的耗时分析来定位事务执行过程中的性能瓶颈 。
从Action创建Component
一般组件
//方法1:
//不指定函数名过程名，获取当前方法名作为组件名称 。
//参数
// action: 事务Id 。
// 返回值: 组件Id 。
TComponentId ACreateComponent(TActionId action);
//功能: 开始一个组件的数据采集,这个API获取当前所处的函数名字作为组件名 。
//调用时机: 一个可能耗时的计算类型的子过程开始的时候 。
//方法2:
//自定义组件名称 。
//参数:
// action: 事务Id 。
// ComponentName: 自定义组件名 。
// 返回值: 组件Id 。
TComponentId ActionCreateComponent(TActionId action, const char *ComponentName);
//功能: 同上,这个API使用自定义的名字作为组件名 。
//调用时机: 同上 。
数据库组件
//方法1: 有SQL语句的情况下,使用SQL语句自动解析 。
//参数:
// action: 事务Id 。
// type: 数据库类型: "Mysql"/"Postgresql" 。
// host: 数据库主机地址 。
// dbname: 数据库名 。
// sql: 执行的SQL语句 。
// 返回值: 组件Id 。
TComponentId CreateSQLComponent(TActionId action, const char *type, const char *host, const char *dbname, const char *sql);
//功能: 开始一个数据库调用过程的数据采集,需要传递sql语句.内部将解析出数据库操作类型和表名，作为组件名的一部分 。
//调用时机: 数据库过程开始时 。
//方法2: 无SQL语句的情况下,传递表名和操作名(select/update/insert/delete) 。
//参数:
// action: 事务Id 。
// type: 数据库类型: "Mysql"/"Postgresql" 。
// host: 数据库主机地址 。
// dbname: 数据库名 。
// table: 表名 。
// op: 表上的操作名 。
// 返回值: 组件Id 。
TComponentId CreateDBComponent(TActionId action, const char *type, const char *host, const char *dbname, const char *table, const char *op);
//功能: 同上,差别是明确指定表明和操作方法(select/update/insert/delete) 。
//调用时机: 同上 。
NoSQL组件
//参数:
// action: 事务Id 。
// type: 数据库类型: "Mysql"/"Postgresql" 。
// host: 数据库主机地址 。
// dbname: 数据库名 。
// object_name: 对象名 。
// op: 对象上的操作名 。
// 返回值: 组件Id 。
TComponentId CreateNoSQLComponent(TActionId action, const char *type, const char *host, const char *dbname, const char *object_name, const char *op);
//功能: 开始一个NoSQL数据库调用过程的数据采集 。
//调用时机: 数据库过程开始时 。
外部调用组件(RPC、HTTP等)
//自定义组件名称 。
//参数:
// action: 事务Id 。
// url: 外部调用的url 。
// 返回值: 组件Id 。
TComponentId CreateExternalComponent(TActionId action, const char *url);
//功能: 开始一个外部调用的数据采集,外部调用可以是向其他服务器发起的http请求，或者rpc调用 。
//调用时机: 外部调用开始时
MQ调用组件(生产者,消费者)
//自定义组件名称 。
//参数:
// action: 事务Id 。
// type: MQ类型: RabbitMQ, ActiveMQ, Kafka... 。
// host: MQ地址 。
// queue: 队列名 。
// 返回值: 组件Id 。
TComponentId CreateConsumerComponent(TActionId action, const char *type, const char *host, const char *queue);
//功能: 开始一个消息队列消费者的数据采集 。
//调用时机: MQ消费者开始时 。
//自定义组件名称 。
//参数:
// action: 事务Id 。
// type: MQ类型: RabbitMQ, ActiveMQ, Kafka... 。
// host: MQ地址 。
// queue: 队列名 。
// 返回值: 组件Id 。
TComponentId CreateProducerComponent(TActionId action, const char *type, const char *host, const char *queue);
//功能: 开始一个消息队列生产者的数据采集 。
//调用时机: MQ生产者调用开始时 。
从Component创建Component
//方法1:
//不指定函数名过程名，自动获取当前方法名作为组件名称 。
//参数
// parent: 父级组件Id 。
// 返回值: 组件Id 。
TComponentId CCreateComponent(TComponentId parent);
//功能: 开始一个组件的数据采集 。
//调用时机: 当一个耗时的计算过程被分解为几个子过程时,我们需要采集每个子过程的耗时情况，来详细分析性能瓶颈 。
//此时通过这个API可以构建一个调用树，通过分析每个过程的耗时情况，解决性能问题 。
//方法2:
//自定义组件名称
//参数:
// parent: 父级组件Id 。
// ComponentName: 自定义组件名 。
// 返回值: 组件Id 。
TComponentId ComponentCreateComponent(TComponentId parent, const char *ComponentName);
//功能: 同上, 差别是用此API自定义过程名 。
//调用时机: 同上 。
组件错误采集
//参数:
// component: 组件id 。
// message: 错误消息 。
void ComponentSetError(TComponentId component, const char *message);
//功能: 在组件过程中发生错误时,通过这个api记录代码行和调用栈,协助错误分析 。
//调用时机: 对应组件的过程发生错误时 。
结束Component
//参数:
// component: 组件id 。
void ComponentFinish(TComponentId component);
//功能: 结束一个组件的数据采集 。
//调用时机: 对应该组件的过程执行完毕时。比如数据库过程执行完时，或者一个外部调用执行完成时 。
子过程结束时,需要调用对应的Component.Finish()，才能达到采集数据的目的。
跨应用追踪
- 应用拓扑 当一个帐号下存在多个应用的相互调用关系时, 可以利用API追踪应用之间的调用关系 。 调用者CreateTrackId, 被调用者SetTrackId, 在报表内就会产生“调用者” -> "被调用者" 的拓扑图 。
客户端:
//流程:
//1.创建一个外部调用组件 。
//2.调用ComponentCreateTrackId生成跨应用追踪id(字符串) 。
//3.发送id到server端 。
//3.1如果外部调用为私有rpc协议，请自行传输这个id 。
//3.2如果是http(s)请求，将这个id作为http头的 "X-Tingyun-Id" 字段发送 。
//4.如果http应答头里携带”X-Tingyun-Tx-Data“，调用ComponentSetTxData完成跨应用追踪 。
//需要的API:
int ComponentCreateTrackId(TComponentId component, char *idbuffer, int buffersize);
void ComponentSetTxData(TComponentId component, const char *tx_data);
//调用过程:
//1.
TComponentId external == CreateExternalComponent(action, "http://192.168.1.253/servermethod");
//2.
char cross_id[1024] = {0};
ComponentCreateTrackId(external, cross_id, sizeof(cross_id) - 1);
//添加cross_id到http请求头 (如果是http(s)) 。
...
//3.
//发送数据到服务器 。
...
//应答完成后，
//取应答头里的 ”X-Tingyun-Tx-Data“ 。
...
//4.
ComponentSetTxData(external, tingyun_txdata);
ComponentFinish(external);
服务器端:
void ActionSetTrackId(TActionId action, const char *TrackId);
char track_id[1024] = {0};
//1.解析出客户端传过来的跨应用追踪ID 。
...
//2.创建事务:
TActionId action = CreateAction(appid, "/servermethod");
//3.
ActionSetTrackId(action, track_id);
//Action其他处理过程...
...
ActionDestroy(action);
- 跨应用追踪 当产生拓扑关系的应用过程性能超过阈值时，会产生慢过程跟踪数据，同时在慢过程跟踪数据内会记录调用者和被调用者的详细追踪信息 。 通过点击慢过程跟踪图表内的链接，可以跳转到被调用者的详细追踪数据 。
API函数
异步调用API
TActionId CreateAction(const char *uri);
创建一个事务，uri可以是自定义的事务名。
void ActionAddCustomParam(TActionId action_id, const char k, const char v);
添加事务的自定义参数(uri解析参数),协助应用在报表端分析慢过程追踪和错误追踪栈。
适用情形: 需要通过参数分析慢事务或者错误原因时，请调用此接口采集参数。
void ActionAddRequestParam(TActionId action_id, const char k, const char v);
添加事务的客户端请求参数(http头),协助应用在报表端分析慢过程追踪和错误追踪栈。
适用情形: 需要通过参数分析慢事务或者错误原因时，请调用此接口采集参数。
TComponentId ACreateComponent(TActionId action);
从Action创建一个一般组件,组件名使用当前调用方函数的名字。
TComponentId ActionCreateComponent(TActionId action, const char *ComponentName);
从Action创建一个一般组件,组件名使用自定义名字。
TComponentId CreateSQLComponent(TActionId action, const char type, const char host, const char dbname, const char sql);
从Action创建一个数据库组件,参数为:数据库类型,主机名,库名,sql语句。
TComponentId CreateDBComponent(TActionId action, const char type, const char host, const char dbname, const char table, const char *op);
从Action创建一个数据库组件,参数为:数据库类型,主机名,库名,表名,操作名。
TComponentId CreateNoSQLComponent(TActionId action, const char type, const char host, const char dbname, const char object_name, const char *op);
创建NOSQL性能分解组件 参数:
type : “mongo"/"memcache"/"redis" 。
host : 主机地址，可空 。
dbname : 库名称，可空 。
object_name : 对象名 。
op : 操作类型, ("GET", "SET" ...) 。
TComponentId CreateExternalComponent(TActionId action, const char *url);
从Action创建一个外部调用组件 参数: url:外部服务的url,格式: http(s)://host/uri, 例如 http://www.tingyun.com/。
void ActionIgnore(TActionId action);
忽略这次Action的性能采集,只在ActionDestroy调用之前有效。
适用情形: 通常不需要使用者调用。
void ActionSetName(TActionId action, const char classname, const char methodname);
修改事务名 参数: 类名,方法名。
适用情形: 明确指定事务名。
void ActionSetStatus(TActionId action, int StatusCode)
设置Action对应的http事务应答的http状态码,缺省值200。
适用情形: 能取到返回状态码的情况。
void ActionSetError(TActionId action, const char error_classname, const char message);
设置事务错误类名和消息。
适用情形: 事务处理过程发生错误时调用。
void ActionSetTrackId(TActionId action, const char *trackId)
用于rpc调用或者http外部调用的跨应用追踪,trackId 由使用者从调用端传过来。
适用情形: 参考跨应用追踪。
void ActionSetUrl(TActionId action, const char *Url);
重设对应Action的 uri, 用于追踪慢过程和错误分析。
适用情形: 明确指定事务对应的url,事务的命名优先使用url，没有的情况下使用函数名。
void ActionDestroy(TActionId action)
当前事务数据采集结束。
适用情形: 事务结束。
性能分解组件
TComponentId CCreateComponent(TComponentId parent);
对本组件再进行性能分解，创建下层性能分解组件，使用调用者所处函数作为组件名。
TComponentId ComponentCreateComponent(TComponentId parent, const char *ComponentName);
对本组件再进行性能分解，创建下层性能分解组件，使用ComponentName作为组件名。
int ComponentCreateTrackId(TComponentId component, char *idbuffer, int buffersize);
用于跨应用追踪,本组件内调用了外部应用过程或者发起了rpc调用,由应用此方法返回的结果携带到server端,server端通过ActionSetTrackId使用这个结果。最终在报表端生成跨应用追踪图表。
适用情形: 参考跨应用追踪。
void ComponentSetTxData(TComponentId component, const char *tx_data);
用于跨应用追踪,如果外部调用的server端安装了基调听云的Java、PHP等其他探针,启用跨应用追踪时，响应头里会有”X-Tingyun-Tx-Data“数据，通过本接口采集这个数据，完成跨应用追踪。
适用情形: 参考跨应用追踪。
TActionId ComponentGetAction(TComponentId component);
取本组件所属的事务对象Action。
适用情形: 某些情况下，传参过程同时携带事务ID和组件ID 会令代码变的复杂,这个API提供了方便方法通过组件获取到相应的事务id。
void ComponentFinish(TComponentId component);
停止性能分解组件计时 性能分解组件时长 = Finish时刻 - CreateComponent时刻 当时长超出堆栈阈值时，记录当前组件的代码堆栈。
void ComponentSetError(TComponentId component, const char *message);
设置组件错误消息。
适用情形: 组件处理过程发生错误时调用。
同步调用API
说明：对于同步处理的事务类型(主函数开始即事务开始,主函数退出即事务结束，过程分解亦如此)，我们需要更简洁的函数调用，方便用户使用，减少传递id给用户带来的困扰。我们提供如下函数完成埋点任务 。
TingYunID C_SyncTrackEnter(const char *instance);
同步执行的事务/组件调用的入口,返回事务ID/组件ID。
调用时机: 在需要关注的函数入口开始时调用。
void C_SyncTrackLeave(id_pointer);
一个事务/组件结束时调用,参数是事务/组件的id。
TComponentId C_SyncTrackRPCEnter(const char *url);
用于测量外部调用过程的执行性能，比如http/thrift/proto_buf等。在执行前调用这个方法计时，执行后调用C_SyncTrackLeave结束计时。
TComponentId C_SyncTrackNoSQLEnter(const char dbtype, const char host, const char db, const char table, const char *op);
用于测量一次NoSQL数据访问性能,dbtype可以取mongo, redis, memcache; host:=> 数据库地址; db:=>库名; table:=>对象名; op:=>操作名。
TComponentId C_SyncTrackDBEnter(const char dbtype, const char host, const char db, const char sql);
用于测量关系型数据库访问性能, dbtype取mysql/postgresql/oracle/db2/sqlite等; host:=>数据库地址; db:=>库名; sql:=> 数据库查询语句。
TComponentId C_SyncTrackConsumerEnter(const char mqtype, const char host, const char *queue);
用于测量消息队列消费者的处理过程, mqtype取RabbitMQ/ActiveMQ/Kafka 等; host:=>MQ地址; queue:=>消息队列名。
TComponentId C_SyncTrackProducerEnter(const char mqtype, const char host, const char *queue);
用于测量消息队列生产者的发送过程, mqtype取RabbitMQ/ActiveMQ/Kafka 等; host:=>MQ地址; queue:=>消息队列名。
TComponentId C_SyncTrackError(const char *message);
在组件过程中发生错误时,通过这个api记录代码行和调用栈,协助错误分析。
//调用时机: 对应组件的过程发生错误时。
跨进程事务API
int TingYunIDSerialize(const TActionId action_id, char out);
在多进程协作事务处理框架中,事务的入口框架创建事务id, 应用调用 TingYunIDSerialize 将事务id序列化成字符串,通过进程通信接口发送到协作进程。
TingYunID TingYunIDParse(const char *input);
在多进程协作事务处理框架中,协作进程收到序列化后的字符串，解析出事务id。