帮助中心

API接口

API接口仅在CLI模式下生效

PHP探针默认仅能监控到基于FastCGI接口的http请求的性能数据，当使用基于CLI模式的框架时，由于没有明显的业务逻辑拆分依据，探针产生的性能数据是整个脚本的总执行时间的数据。

为了监控基于CLI模式(例如swoole框架)的业务逻辑性能，需要使用以下API接口进行手工嵌码。

tingyun_start_webaction

创建一个Web应用过程, 一个Web应用过程代表业务过程，类似一个HTTP请求的执行过程。

bool tingyun_start_webaction( string $action_name[, string $cross_app_header = NULL])

参数：

action_name

应用过程名称，格式为"业务名"或"分类名/业务名"。其中，分类名可选，当action_name中不包含斜杠(/)时，分类名默认为"API"。例如： action_name为"login"时，报表内产生的应用过程名为"API/login"， action_name为"user/login"时，报表内产生的应用过程名称为"user/login"

cross_app_header

可选参数，跨应用标识，用以支持拓扑和跨应用追踪。

返回值： true代表成功，false或NULL代表失败。

当此API在非CLI模式下调用或应用在报表端被禁用时，tingyun_start_webaction返回NULL。探针有系统资源保护功能，当cpu或内存使用占40%以上，会对监控进行采样，此时tingyun_start_webaction返回NULL。

当前进程已有Web应用过程且没有结束的时候，调用此函数会重新创建Web应用过程, 原有应用过程的性能数据会被丢弃。

默认创建web应用过程时，所属应用的名称是ini配置文件内nbs.app_name指定的名称。如果想在CLI代码内区分不同的应用，需在 tingyun_start_webaction 运行之前使用 ini_set("nbs.app_name", "your_app_name") 指定。

tingyun_end_webaction

结束当前Web应用过程

bool tingyun_end_webaction()

返回值：

true代表成功，false或NULL代表失败。

tingyun_notice_error

记录应用过程异常信息

bool tingyun_notice_error( mixed $exception[, bool $action_error = true])

参数：

exception

参数类型可以是异常类（从Exception继承的类）或异常描述（字符串）。推荐传入异常类，此时探针获取的代码错误堆栈为异常类产生的实际堆栈，如果传入字符串，探针获取的代码错误堆栈为tingyun_notice_error所在位置的代码堆栈。

action_error

异常是否影响业务可用性, 可选参数，默认true。 false 表示此异常不影响业务可用性，仅记录异常信息到报表。

返回值：

true代表成功，false或NULL代表失败。

一个Web应用过程中, 如果调用多次tingyun_notice_error, 报表仅记录第一个影响业务可用性的异常信息。

tingyun_start_webservice

记录web service

string tingyun_start_webservice( string $url)

参数：

url webservice的url全路径, 包括协议名称。例如：

    tingyun_start_webservice("http://www.a.com/login.php")
    tingyun_start_webservice("thrift://192.168.1.5/User")
    tingyun_start_webservice("ws://192.168.1.2/List")

返回值：

返回字符串, 标记了当前webservice调用的跟踪信息。
返回NULL, 代表失败。

如果需要实现跨应用的拓扑和追踪功能，需要将返回的字符串信息传递到下一应用的tingyun_start_webaction。如果不需要跨应用的拓扑和追踪功能，此返回值可以忽略。

tingyun_end_webservice

结束web service，并计算webservice调用时间。

bool tingyun_end_webservice()

返回值：

true代表成功，false或NULL代表失败。

API接口范例

案例1：

原脚本：

	<?php
		function customAction($index)
		{
			try
			{
				file_get_contents("http://www.baidu.com/?q=" . $index);
			}
			catch (Exception $e)
			{
			}
		}
		for($i=0; $i<3; $i++)
		{
			// 执行业务逻辑
			customAction($i);
		}
	?>

假设我们需要将customAction 拆分为应用过程，同时记录内部捕获的异常信息，嵌码后的代码：

	<?php
		function customAction($index)
		{
			try
			{
				file_get_contents("http://www.baidu.com/?q=" . $index);
			}
			catch (Exception $e)
			{
				// 产生应用过程异常信息
				if(function_exists("tingyun_notice_error"))
				{
					\tingyun_notice_error($e);
				}
			}
		}
		for($i=0; $i<3; $i++)
		{
			// 创建应用过程
			if(function_exists("tingyun_start_webaction"))
			{
				\tingyun_start_webaction("action" . $i);
			}
			// 执行业务逻辑
			customAction($i);
			// 结束应用过程
			if(function_exists("tingyun_end_webaction"))
			{
				\tingyun_end_webaction();
			}
		}
	?>

案例2：

假设有a b c 3个服务，client端调用了service a, service a调用了service b和service c

嵌码前伪代码：

client：

	call_service(a)

service a:


    xxx
    call_service(b)
    yyy
    call_service(c)
    zzz

service b:

bbb

service c:

ccc

嵌码过程：

在调用组件出口包裹上 _webservice, 即

	call_service;

嵌码后

	tingyun_start_webservice; call_service; tingyun_end_webservice;

在服务端入口包裹上 _webaction, 即

	service;

嵌码后

	tingyun_start_webaction; service; tingyun_end_webaction;

增加监控后的代码：

client：

	tingyun_start_webservice; call_service(a); tingyun_end_webservice;

service a:

    tingyun_start_webaction
    xxx
    tingyun_start_webservice; call_service(b); tingyun_end_webservice;
    yyy
    tingyun_start_webservice; call_service(c); tingyun_end_webservice
    zzz
    tingyun_end_webaction

service b:

    tingyun_start_webaction
    bbb
    tingyun_end_webaction

service c:

    tingyun_start_webaction
    ccc

报表上的显示效果：client端的数据不会展示出来，sevice a b c均会显示出来