听云 DotNet Agent

• 简介
  • 使用步骤
  • 兼容性要求
• 安装
• 禁用/启用
• 卸载
• 配置
  • 配置界面
  • 应用命名
  • 对特定应用禁用探针
  • 配置排队时间
  • 日志管理
  • 代理设置
• API接口
  • SetActionName
  • API接口范例
• 常见问题
  • 查看日志
  • 排除安装故障
  • 安装成功但无数据
  • 其他问题

使用步骤

1. 确认您的系统满足兼容性要求
2. 如果您还没有听云server帐户，请注册听云server帐户
3. 从听云server探针安装页面复制您的授权码
4. 安装DotNet探针
5. 完成探针设置
6. 启用监控
7. 通过管理页面察看数据，有问题请参考常见问题。

兼容性要求

安装探针之前，请确保您的系统满足如下这些条件：

• Windows 操作系统，满足以下列表条件之一：

  • Windows Server 2012
  • Windows Server 2008
  • Windows 8
  • Windows 7
  • Windows Vista
  • Windows 2003

• DotNet，满足以下列表条件之一：

  • 2.0
  • 3.5
  • 4.0
  • 4.5

• Web服务器，满足以下条件：

  • IIS 6.0 以上

• 数据库，满足以下列表条件之一：

  • SQL Server
  • Oracle
  • MySQL
  • PostgreSQL

• NOSQL，满足以下列表条件之一：

  • MongoDB
  • ServiceStack.Redis
  • StackExchange.Redis
  • Memcache

• MQ，满足以下列表条件之一：

  • MSMQ
  • RabbitMQ

• 框架，满足以下列表条件之一：

  • MVC 2
  • MVC 3
  • MVC 4
  • ASP .NET Web API
  • ASP .NET Web Forms
  • WebServices
  • WCF
  • NServiceBus 4
  • NServiceBus 5

安装

1. 下载安装包 tingyun-agent-dotnet-版本.exe

2. 双击安装包, 选择安装路径, 进行安装

3. 启动“NBUI.exe”,配置license

4. 点击“启用监控”

   

禁用/启用

• 方式1: 通过报表端禁用/启用探针

  • 优点：不需要重启IIS

  • 缺点：通过此方式禁用的探针仍旧驻留在IIS进程内部，只是采集性能的逻辑代码不被执行。

  • 禁用方法：在应用列表内点击“操作”内的“禁用”

  • 启用方法: 在应用列表内查找对应应用并点击“启用”

• 方式2：通过NBUI禁用/启用探针

  • 优点：探针被完全禁用，不被加载

  • 缺点：需要重启IIS。

  • 禁用方法: 在NBUI界面点击“禁用监控”

  • 启用方法: 在NBUI界面点击“启用监控”

卸载

如果监控了自托管宿主的WCF应用（见“配置”一节），必须首先停止批处理下的WCF应用，然后使用普通模式启动WCF，最后才能卸载探针，否则会因为探针被WCF应用占用不能完全卸载。

• 方法1

  打开“控制面板”里面的“添加或删除程序”, 找到“TingYun DotNET Profiler”, 卸载

• 方法2

  打开安装路径，找到“Uninstall.exe”, 双击卸载

  安装路径通常在“C:\Program Files (x86)\Networkbench.COM\DotNET Profiler”下

配置

配置界面

通过NBUI.exe进行参数配置, 对IIS或WCF服务进行控制。

NBUI.exe仅仅是一个配置管理界面, 启动监控后, 可以退出。

• 用户程序集/代码:

  探针默认不监控用户函数的性能。我们可以使用这个配置项指定监控用户程序集及代码
  监控的程序集和代码名称区分大小写，此设置更改后, 必须重新点击“启用监控” 按钮才能生效.

• 监控的WCF服务:

  WCF的典型宿主包括以下四种：
  * “Self-Hosting” in a Managed Application（自托管宿主）
  * Managed Windows Services（Windows Services宿主）
  * Internet Information Services（IIS宿主）
  * Windows Process Activation Service（WAS宿主）

  探针默认仅监控IIS宿主和WAS宿主的应用性能

  如果想监控Windows Services宿主的WCF应用，请点击右侧的“…”按钮添加需要监控的服务名称.

  如果想监控自托管宿主的WCF应用，您需要写一个批处理文件启动WCF或改写现有的批处理启动文件，将以下内容写入到批处理文件的第一行：

  SET Cor_Enable_Profiling=1
  

  例如您的自托管宿主的WCF应用是d:\app\ConsoleWcf.exe，批处理文件应该类似：

  SET Cor_Enable_Profiling=1
  d:\app\ConsoleWcf.exe
  

  当通过NBUI配置界面修改配置选项后，需要手动停止和启动自托管宿主的WCF应用，否则配置选项不会生效。

• 热点代码:

  探针默认不监控用户函数的性能，热点代码采集是从当前活动的线程堆栈中采集需要监控的用户函数,
  为了保证采集效果，请在采集过程中，尽量多的访问应用中常用的页面, 或者在压测的同时进行采集。

  采集过程中会有部分CPU和资源的消耗，建议在测试环境下采集，然后将log文件夹内的learning.dat复制到生产环境的log文件夹内。

  采集完毕后，需要重新“启用监控”才能监控采集结果内的用户函数。

应用命名

默认情况下，应用名称和站点名称一致，如果同一网站部署在多个服务器上，报表中一个应用会对应多个实例，
如果想直接将多个实例区分为多个应用，可以通过配置站点的“nbs.app_name”项更改应用名称

1. 打开“IIS 管理器”

2. 选择网站,双击“应用程序设置”，在更改设置前，此站点的数据会汇总在“discuz”下

   

3. 点击“应用程序设置”中的“添加…” 操作, 添加名称为“nbs.app_name”的数据项，将数值设置为您的“my site”，更改设置后，此站点的数据会汇总在“my site”下

   

如果IIS版本为6.0，您需要修改站点的Web.Config配置文件

<configuration>
	<appSettings>
		<add key="nbs.app_name" value="my Site" />
	</appSettings> 
</configuration>

对特定应用禁用探针

默认情况下，当您想临时禁用所有应用的性能数据采集时，应该通过听云报表内的开关来临时禁用和启用探针。
当需要禁用特定应用的性能数据时，可以通过下述配置来禁用其中某一虚拟主机的性能数据。

如果想禁用某站点的监控，可以配置此站点的“nbs.agent_enabled”项

1. 打开“IIS 管理器”

2. 选择网站,双击“应用程序设置”

   

3. 点击“应用程序设置”中的“添加…” 操作, 添加名称为“nbs.agent_enabled”的数据项，将数值设置为false

   

如果IIS版本为6.0，您需要修改站点的Web.Config配置文件

<configuration>
	<appSettings>
		<add key="nbs.agent_enabled" value="false" />
	</appSettings> 
</configuration>

配置排队时间

如果要配置排队时间，必须保证相关服务器的时钟同步。

• 排队时间定义：

  从负载均衡服务器转发开始到web应用服务器的请求开始被处理所消耗的时间。

• 原理：

  负载均衡设备或容器收到请求后，增加请求的http头: X-QUEUE-START,
  内容为收到请求的毫秒数，负载均衡将请求转发给WEB应用服务器。
  WEB应用服务器在处理请求时，获取当前时间的毫秒数，两个时间差值即为请求排队时间。

  例如，大量请求在web应用服务器队列内排队后请求才被处理时，排队时间会变长

• 配置方法:

  • Apache 配置

    RequestHeader set X-QUEUE-START "%t"
    

  • Nginx 配置(1.2.6版本以上)

    • 使用 proxy_set_header

      proxy_set_header X-QUEUE-START "s=$msec";
      

    • 或使用 fastcgi_param

      fastcgi_param HTTP_X_QUEUE_START "s=$msec";
      

    • 或使用 Passenger

      passenger_set_cgi_param HTTP_X_QUEUE_START "s=${msec}";
      

    • 或使用 uWSGI

      uwsgi_param HTTP_X_QUEUE_START "s=${msec}";
      

  • HaProxy 配置

    http-request set-header X-Queue-Start t=%Ts%ms
    

  • F5 配置

    when HTTP_REQUEST_SEND {
    	set secs [clock seconds]
    	set ms [clock clicks -milliseconds]
    	set base [expr { $secs * 1000 }]
    	set fract [expr { $ms - $base }]
    	if { $fract >= 1000 } {
    		set diff [expr { $fract / 1000 }]
    		incr secs $diff
    		incr fract [expr { -1000 * $diff }]
    	}
    	set micros [format "%d%03d000" $secs $fract]
    	clientside {
    		HTTP::header insert X-QUEUE-START "t=${micros}"
    	}
      }
    

日志管理

• 日志级别
  控制日志数据写入日志文件的级别。
  “DEBUG”是最低级，允许所有日志信息写入日志文件。 “OFF”是最高级，禁止所有日志信息写入日志文件。

• 审计模式

  选项设定是否在日志文件中写入所有向听云平台上传和下载的数据内容。

代理设置

首先退出NBUI配置界面，然后打开探针安装路径下的配置文件TingYun.ini，指定代理服务器

nbs.proxy_host =
nbs.proxy_port =
nbs.proxy_user =
nbs.proxy_password =

API接口

SetActionName

设置应用过程的名称

using System.Web;
using System.Reflection;

namespace TingYun.Tool
{
    public static class TingyunAPI
    {
        public static void SetActionName(string category, string name)
        {
            HttpContext context = HttpContext.Current;
            if (context != null)
            {
                object action = context.Items["tingyun.action"];
                if (action != null)
                {
                    try
                    {
                        PropertyInfo property = action.GetType().GetProperty(
                            "ActionName",
                            BindingFlags.Instance | BindingFlags.Public
                        );
                        if (property != null)
                        {
                            object[] param = {
                                string.Format("{0}/{1}", category, name.Replace("/","%2F"))
                            };
                            property.GetSetMethod(false).Invoke(action, param);
                        }
                    }
                    catch
                    { }
                }
            }
        }
    }
}

API接口范例

1. 修改应用过程名称：

   假设我们使用了自己的mvc框架，需要在自己的路由中将应用过程名称修改为controller名称 + action名称：

   嵌码后：

   TingyunAPI.SetActionName(controller, action)
   

常见问题

查看日志

如果探针工作不正常或者没有数据，通常可以从日志里获取更多的信息来定位问题．

默认日志位置

C:\Program Files (x86)\Networkbench.COM\DotNET Profiler\log\agent.log

正常情况下agent.log 日志中不应该存在Error， Critical等关键字。

默认情况，日志级别为Info, 审计模式是关闭的，这种情况得到的信息量比较小．
通过修改日志级别为debug，开启审计模式，输出更多日志信息来定位问题．

排除安装故障

注意：安装探针时需要在.NET全局应用缓存（GAC）中部署一个程序集，这要求使用管理员权限进行安装。

安装成功后，可以在 C:\Windows\assembly 找到探针的程序集 TingYun.dll

安装时，某些杀毒软件可能会直接禁止了对C:\Windows\assembly的操作，请确认杀软的行为

如果使用受限权限用户安装，或被杀软拦截，可能会导致虽然安装程序提示安装成功，但是启用监控后，使用浏览器访问网站时，由于找不到探针组件导致页面提示失败。

失败页面通常如下所示：

由于安装权限导致的网站运行失败是完全可以在安装之后立即访问网站来进行验证的。
当此情况发生时，请立即卸载探针，并使用管理员权限用户重新安装探针或更改杀软的拦截规则，允许对GAC进行操作后重新安装探针。

安装成功但无数据

1. 初次安装后需要一段时间才能看到数据，通常需要5分钟或更长时间，请多等一段时间

2. 有的用户浏览器缓存有问题，即使有数据如果不强制刷新也可能看不到，请尝试清空缓存或强制刷新或更换浏览器

3. 探针安装成功后，必须启用监控，否则探针不生效

4. 请确认授权码是否正确

5. 请确认web服务器有没有用户访问
   探针数据是基于http请求的性能，如果没有访问，就不会有性能数据。
   如果没有用户访问，请使用浏览器访问相应的应用，再过5分钟后查看报表

其他问题

1. 探针都能采集哪些数据?

   目前，探针可以采集IIS运行时的性能数据和错误信息。

   性能数据包括：
   * HTTP请求的总响应时间
   * 从负载均衡服务器到web服务器的排队时间
   * 数据库耗时
   * NOSQL耗时
   * web service耗时
   * 超过阈值的性能瓶颈函数
   * 慢sql语句及调用堆栈

   错误信息包括：
   * sql语法错误
   * 网站运行时未捕获的异常
   * http状态码为4xx 5xx的错误

2. 在win2003部分机器上，日志内出现下面错误

   ERROR tid:6	POST getRedirectHost?app= 
   	-> System.Net.WebException: The operation has timed out 
   

   或

   ERROR tid:10 POST getRedirectHost?app= 
   	-> System.Net.WebException: 基础连接已经关闭: 未能为 SSL/TLS 安全通道建立信任关系。  
   	---> System.Security.Authentication.AuthenticationException: 根据验证过程，远程证书无效。
   

   答：根据WebTrust 、CA/B成员计划及Microsoft根证书成员计划的要求，2017年1月1日起不再签发SHA1算法的服务器证书.

   听云探针使用安全性更高的SHA256算法证书与服务器进行SSL通讯，但部分win2003机器不支持SHA256的证书算法, 请打操作系统补丁https://support.microsoft.com/zh-cn/kb/938397，如果找不到补丁，请联系听云技术支持，或在探针配置界面内禁用SSL通讯。