配置

配置界面

通过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应用，请点击右侧的"..."按钮添加需要监控的服务名称。

监控自托管应用

如果您部署的是UniAgent 2.5.0以前的版本请在应用启动脚本内增加call "C:\Program Files\tingyun\monitor\agent\dotnet-enable.bat"。

如果您部署的是UniAgent 2.5.0及以上的版本请修改C:\Program Files\tingyun\monitor\conf\interceptor.conf, 中的 netcore.namelist=w3wp,net-demo.exe，通过“任务管理器”或“服务”重启TingyunMonitor服务后，重启启动应用进行监控。

如果您部署的是普通探针，请参考以下说明。

本地启动

如果应用为本地启动，写入临时环境变量到批处理文件的第一行：

SET Cor_Enable_Profiling=1

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

SET Cor_Enable_Profiling=1

start /D "d:\app\" ConsoleWcf.exe

关闭原有运行中的自托管应用，然后使用批处理脚本重启自托管应用。

如果应用有提升权限的图标 app_uac ，上述方法设置的临时环境变量不会生效，需要使用setx设置永久的环境变量，为了防止其他进程也加载探针，最后需要将变量再设回去。

启动脚本应该修改成类似如下形式：

SETX Cor_Enable_Profiling 1

start /D "C:\path1\" ConsoleWcf1.exe
start /D "C:\path2\" ConsoleWcf2.exe
start /D "C:\path3\" ConsoleWcf3.exe

SETX Cor_Enable_Profiling 0

应用名称默认取exe的名称，如果需要自定义应用名称，需要增加环境变量 TINGYUN_APP_NAME, 例如:

SET TINGYUN_APP_NAME=custom_name

远程启动

如果应用为远程启动，例如使用Jenkins等远程部署及启动，写入临时环境变量到批处理文件的第一行：

SET Cor_Enable_Profiling=1
SET COR_PROFILER={8BEB2128-D285-4E1D-91B6-11ACD43EC0EE}
SET TINGYUN_NET_HOME=C:\Program Files (x86)\Networkbench.COM\DotNet Profiler

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

SET Cor_Enable_Profiling=1
SET COR_PROFILER={8BEB2128-D285-4E1D-91B6-11ACD43EC0EE}
SET TINGYUN_NET_HOME=C:\Program Files (x86)\Networkbench.COM\DotNet Profiler
SET TINGYUN_APP_NAME=custom_name
    
start /D "d:\app\" ConsoleWcf.exe

应用命名

应用命名的优先级从高到低依次为:

按照进程环境变量TINGYUN_APP_NAME命名
按照网站名称siteName命名
按照虚拟目录网站名称命名
按照TingYun.ini配置文件重命名

默认情况下，应用名称和站点名称一致。

如果同一网站部署在多个服务器上，报表中一个应用会对应多个实例。如果一个站点中部署多个应用程序，此时默认这几个应用名称均为站点名称。

如果需要变更为虚拟目录应用名，您需要修改探针的本地配置文件TingYun.ini，将local.named_by_virtualpath设置为true。

如果需要设置应用名称前缀，您需要修改探针的本地配置文件TingYun.ini，将local.name_prefix设置为特定字符串，注意前缀中不能包含特殊字符和英文逗号。

如果需要更改应用名称，您需要修改探针的本地配置文件TingYun.ini，增加rename.原应用名=新应用名，例如：rename.test_app=my_app。

事务命名

在报表中用户可以自定义事务的命名方式。

如果是WCF应用，匹配规则仅URL匹配有效，命名规则仅支持按参数和header命名。WCF应用按参数命名时，参数名称为参数对应的索引，例如第1个参数为0，第2个参数为1，且支持获取参数的属性或方法，属性或方法以.进行分隔。

例如下面代码：

[ServiceContract]
public interface IService
{
	[OperationContract]
	public int GetData(Request request);
	
	[OperationContract]
	public int GetList(string name, string index);
}

[DataContract]
public class Request
{
	[DataMember]
	public int Id;

	[DataMember]
	public string Name;
	
	public string GetColor(){
		return "OK";
	}
}

例1：如果我们想按照GetData方法的第1个参数内Request的Name和GetColor()拆分/WCF/IService/GetData产生的事务，我们需要将匹配规则的URL设置为 等于 /WCF/IService/GetData ，将按参数命名设置为0.Name,0.GetColor()。

例2：如果我们想按照GetList方法的第1个参数name和第2个参数index拆分/WCF/IService/GetList产生的事务，我们需要将匹配规则的URL设置为 等于 /WCF/IService/GetList, 将按参数命名设置为0,1。

对特定应用禁用探针

UniAgent部署方式

目前暂不支持通过UniAgent部署界面禁用/启用探针，如需要禁用探针，请配置进程黑名单 C:\Program Files\tingyun\monitor\conf\blacklist.txt 或 C:\Program Files\tingyun\monitor\conf\dotnet.conf。

例如，要禁用IIS内网站名称为discuz的应用，将C:\Program Files\tingyun\monitor\conf\blacklist.txt修改为：

discuz

或修改探针配置文件C:\Program Files\tingyun\monitor\conf\dotnet.conf内local.disabled_apps禁用探针。

local.disabled_apps=discuz

普通部署方式

临时禁用：通过基调听云控制台内的开关来临时禁用和启用探针。
永久禁用：修改探针本地配置文件TingYun.ini永久禁用探针。

当需要禁用的应用比较少，启用的应用比较多时，配置黑名单local.disabled_apps，黑名单内的应用数据不被采集。

当需要禁用的应用比较多，启用的应用比较少时，配置白名单local.allowed_apps，仅采集白名单内的应用数据。

local.disabled_apps=禁用应用名称1,禁用应用名称2
local.allowed_apps=应用名称1,应用名称2

日志管理

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

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

本地配置

首先退出NBUI配置界面，然后打开探针安装路径下的配置文件TingYun.ini，指定本地配置项。

nbs.collector=                  //Collector地址，多个Collector以逗号分隔
nbs.license =                   //授权码
nbs.agent_log_file_name =       //日志存放位置
nbs.agent_log_level =           //日志级别
nbs.audit_mode =                //审计模式(true/false)
nbs.max_log_size =              //日志文件大小(MB)
nbs.max_log_count=              //日志文件数量
local.computername=             //自定义的实例名称
local.process=                  //自托管的WCF服务列表，英文逗号分隔
local.delay=                    //启动延迟加载时长(seconds)
local.named_by_virtualpath=     //按照虚拟目录应用命名应用(true/false)
local.name_prefix=              //应用名称前缀，当设置此项后，当前机器上所有应用名称均会添加此前缀
local.disabled_apps=            //应用黑名单，多个应用使用英文逗号分隔
local.allowed_apps=             //应用白名单，多个应用使用英文逗号分隔，为空代表允许所有应用
local.async=                    //监控异步方法开关，默认不监控异步方法

用户溯源

.NET探针支持从HTTP request header、HTTP response header、URL参数、正文Form表单、Session、Cookie 中获取用户信。.NET 4.5及以上支持从自定义嵌码的参数或返回值获取用户信息。

日志溯源

必要条件

探针 3.3.2.0 及以上版本。
log4net 1.2.10 及以上版本。
平台内开启应用的“日志溯源”开关。
配置被监控应用的log4net配置文件。

配置log4net

log4net 1.2.10 版本配置方式：

在conversionPattern内增加 [%mdc{TINGYUN}]
log4net 1.2.11 及以上版本配置方式：

在conversionPattern内增加 [%aspnet-context{TINGYUN}]

生成的日志包括：

tingyun.app_id：应用与微服务为每一个监控的应用生成的唯一id。
tingyun.trace_id：在整个请求链路中，入口事务生成的整个请求链路的唯一标识，此值将在链路中不断传递到链路中的每一个请求（如果遇到无法实现跨应用追踪的组件的情况除外），以实现全链路追踪。调用链所涉及的各个应用的日志都显示同一个tingyun.trace_id。
tingyun.span_id：整个请求链路中，应用与微服务为所涉及的各个应用的请求单独生成的标识，应用日志中每个请求都显示不同的tingyun.span_id。

配置举例

请根据实际应用变通配置。

例如原配置为：

<log4net>
	<appender name="RollingFile" type="log4net.Appender.RollingFileAppender">
		<file value="g:\tmp\async-mvc.log" />
		<appendToFile value="true" />
		<param name="Encoding" value="UTF-8"/>
		<maximumFileSize value="100KB" />
		<maxSizeRollBackups value="2" />
		<layout type="log4net.Layout.PatternLayout">
			<conversionPattern value="%d [%-5p] [%t] [%c] %m %n" />
		</layout>
	</appender>
	<root>
		<level value="ALL" />
		<appender-ref ref="RollingFile" />
	</root>
</log4net>

log4net 1.2.10 版本，可以将conversionPattern变更为：

<conversionPattern value="%d [%-5p] [%t] [%c] 
[%mdc{TINGYUN_APPID}] [%mdc{TINGYUN}] %m %n" />

log4net 1.2.11 及以上版本，可以将conversionPattern变更为：

<conversionPattern value="%d [%-5p] [%t] [%c] [%aspnet-context{TINGYUN}] %m %n" />

产生的日志效果如下：

2021-12-29 14:27:18,278 [INFO ] [7] [Test] 
[tingyun.app_id:6318,tingyun.trace_id:74a09a3218129fa3,tingyun.span_id:74a09a3218129fa3] this is a message

在某些场景下，日志溯源会失效：

由于log4net 1.2.10不支持从异步线程上下文中获取信息，如果应用使用了异步方法且使用了log4net 1.2.10，会导致在异步方法内获取的日志溯源数据为空，请协调升级log4net至1.2.11及以上版本。例如：

public async Task<ActionResult> Index()
{
    log.Info("begin");
    await new HttpClient().GetAsync("http://www.baidu.com/");
    log.Info("end");
}

日志如下：

2021-12-29 14:22:40,546 [INFO ] [25] [Test] [tingyun.app_id:6318,tingyun.trace_id:74a09a3218129fa3,tingyun.span_id:74a09a3218129fa3] begin
2021-12-29 14:22:40,657 [INFO ] [34] [Test] [(null)] end

log4net 1.2.11及以上版本支持从asp.net异步线程池上下文中获取信息(使用ConfigureAwait(false)放弃线程关联上下文时的场景除外)，但不支持直接从使用Task.Run执行的方法内获取日志溯源信息。例如：
```
public static bool Add()
{
    log.Info("this is a task");
    return true;
}

public static async Task<bool> AddAsync()
{
    return await Task.Run(() => Add());
}
```
日志如下：
```
2021-12-29 14:27:18,278 [INFO ] [7] [Test] [NOT AVAILABLE] this is a task
```

自定义事务

当需要监控exe等应用时，可以通过更改探针目录下的JSON配置文件来监控指定的方法，自定义事务必须是同一个线程执行的代码段。

自定义事务及方法的配置文件说明如下：

探针3.6.0以下版本：配置文件为探针目录下的TingYun.json。
探针3.6.0及以上版本：如果应用使用.NET Framework 4.5+，配置文件为TingYun.net45.json，如果应用使用.NET Framework 2.0-3.5，配置文件为TingYun.net20.json。

更改配置后，在NBUI界面单击启用监控使新配置生效。

TingYun.Hook.API.MethodAsAction：从方法执行开始到方法执行结束作为一个事务。
TingYun.Hook.API.MethodAsName：当将当前方法作为事务名称。
TingYun.Hook.API.StringParamAsError：当执行到此方法时，如果包含String类型的参数，那么将String参数记录为事务的错误。

    "TingYun.Hook.API.MethodAsAction": {
		"程序集名1":[
			["类名1全路径::方法名1"],
			["类名1全路径::方法名2"]
		],
		"程序集名2":[
			["类名3全路径::方法名1"],
			["类名4全路径::方法名2"]
		]
    },
    "TingYun.Hook.API.MethodAsName": {
		"程序集名3":[
			["类名1全路径::方法名1"],
			["类名1全路径::方法名2"]
		],
		"程序集名4":[
			["类名3全路径::方法名1"],
			["类名4全路径::方法名2"]
		]
    },
    "TingYun.Hook.API.StringParamAsError": {
		"程序集名5":[
			["类名1全路径::方法名1"],
			["类名1全路径::方法名2"]
		],
		"程序集名6":[
			["类名3全路径::方法名1"],
			["类名4全路径::方法名2"]
		]
    },

示例

假设有一个exe，已知userCustom.Form1::DoWork整体可能是性能瓶颈，其中调用了userCustom.Form1::ThrowError会记录到错误信息到日志，我们要让这个异常影响事务的可用性，配置如下：

	"TingYun.Hook.API.MethodAsAction": {
		"userCustom":[
			["userCustom.Form1::DoWork"]
		]
    },    
    "TingYun.Hook.API.StringParamAsError": {
		"userCustom":[
			["userCustom.Form1::ThrowError"]
		]
    }

配置界面​

监控自托管应用​

本地启动​

远程启动​

应用命名​

事务命名​

对特定应用禁用探针​

UniAgent部署方式​

普通部署方式​

日志管理​

本地配置​

用户溯源​

日志溯源​

必要条件​

配置log4net​

配置举例​

自定义事务​

示例​