首页 帮助中心 听云Server API接口
听云Server



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. 案例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. 案例2:

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

    嵌码前伪代码:
    * client:

    ```php
    call_service(a)
    ```  
    
    • service a:

      xxx
      call_service(b)
      yyy
      call_service(c)
      zzz
      
    • service b:

      bbb
      
    • service c:

      ccc
      

    嵌码过程:

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

      call_service;
      

      嵌码后

      tingyun_start_webservice; call_service; tingyun_end_webservice;
      
    2. 在服务端入口包裹上 _webaction, 即

      service;
      

      嵌码后

      tingyun_start_webaction; service; tingyun_end_webaction;
      

    增加监控后的代码:
    * client:

    ```php
    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 
      tingyun_end_webaction 
      

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