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



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();
			}
		}
	?>
  1. 案例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

嵌码过程:

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

嵌码后

	tingyun_start_webservice; call_service; tingyun_end_webservice;
  1. 在服务端入口包裹上 _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均会显示出来