CAT.net 客户端为 .net 应用提供接入 CAT 的 API

Z时代
2024-01-10
分类：IT

CAT.net 客户端的 API 设计、客户端配置方式，与 CAT Java 客户端基本一致。

编译工程

CAT.net 客户端要求 **.NET Framework 4.0 或更高版本**。

用 Visual Studio 2010 或更高版本，打开 Cat\Cat.sln。可以看到 Solution 中包括两个工程：

Cat：CAT.net 客户端实现代码

CatClientTest：示例程序和测试用例。

单击 Rebuild Solution 编译这两个工程：

Rebuild Solution

编译的输出是Cat.dll，如下图。在业务应用的工程中，通过引用这个dll，调用其中的API，来接入CAT。

Cat DLL

配置

1、创建以下目录，确保执行CAT客户端的帐户有权限读写它们：

d:\data\appdatas\cat\ (CAT客户端使用的临时数据目录)

d:\data\applogs\cat\ (CAT客户端的日志输出目录)

2、创建 d:\data\appdatas\cat\client.xml。在其中配置 Domain ID 和 CAT 服务器地址。推荐 client.xml 用 **UTF-8** 编码。client.xml 内容如下：

<?xml version="1.0" encoding="utf-8"?>
<config mode="client" enabled="true" queue-size="123">
	<!--logEnabled enabled="true"></logEnabled-->
	<!-- 配置Domain ID-->
	<domain id="1237" enabled="true" max-message-size="1000"/>
	<servers>
		<!-- 配置CAT服务器地址-->
		<server ip="10.2.6.98" port="2280" http-port="8080"></server>
	</servers>
</config>

执行工程自带的测试用例

设置 CatClientTest 工程为默认启动工程：

Set CatClientTest to be Startup Project

单击执行，就会运行CatClientTest中的Program.cs的Main()方法。

Run CatClientTest

程序输出：

CatClientTest output

在 CAT 中可以看到测试程序的CAT埋点，如下图。其中的CAT服务器地址、Domain ID 应该与 client.xml 中的配置一致。

CatClientTest Transactions

在其他应用中引用 `Cat.dll` 调用 CAT API

假设我们有一个console应用。

Create New Console Project

确保工程使用了 .NET Framework 4.0 或更高版本的服务端 Profile，而 **不是 Client Profile**。

Use Server Profile

添加对 Cat.dll 的引用

Add Reference

调用 CAT API 埋点。示例代码：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Org.Unidal.Cat.Message;
using Org.Unidal.Cat;
using System.Threading;
namespace ConsoleApplication1
{
  class Program
  {
    static void Main(string[] args)
    {
      ITransaction transaction = null; ;
      try
      {
        transaction = Cat.NewTransaction("Order", "Cash");
        // Do your business...
        Cat.LogEvent("City", "Shanghai");
        transaction.Status = CatConstants.SUCCESS;
      }
      catch (Exception ex)
      {
      	Cat.LogError(ex);
        transaction.SetStatus(ex);
        // You may need to re-throw exception ex out.
      }
      finally
      {
        transaction.Complete();
        // 程序退出前睡一会儿。使得CAT客户端有时间发出最后一批消息到网络。
        Thread.Sleep(1000);
      }
    }
  }
}

执行以上 Main() 方法。

在CAT中可以看到埋点效果：

Application Output

Application Output Logview

日志输出

在 client.xml 中，启用 <logEnabled enabled="true"></logEnabled> XML元素，以开启日志输出。

日志输出位于 D:\data\applogs\cat 目录中：

Application Log File Path

为心跳报表获取 .NET 性能数据

Heartbeat Report

如上图，CAT.net客户端每分钟会自动抓取一次机器性能数据，展现在Heartbeat报表中，包括CPU利用率、GC次数、Heap各代大小、锁竞争次数、锁请求队列大小等。

这些性能指标中的一部分，是通过读取.NET Performance Counter实现的，（见DefaultPerformanceMetricProvider.cs中的Initialize()，如下图）。

Default Performance Metric Provider

然而，读取.NET Performance Counter，需要执行应用所使用的帐户是**Performance Log Users**用户组的成员（参考这里）。特别地，在IIS中以普通账户（IIS_USRS）执行的Web应用，是没有这个权限的。

所以，您可能需要提供自己的IPerformanceMetricProvider实现，它通过其他有权限读取的数据源（如Zabbix Agent，Salt Agent，或自己实现的一个有更高执行权限的Performance Counter输出程序）来获取这些性能指标。

在您的实现中，对于IPerformanceMetricProvider接口中的Get*()方法，它应当返回过去1分钟内的某个性能指标的累积值（如GC次数），或过去1分钟内的平均值（如CPU利用率）。不推荐它返回从程序启动至今的累积值/平均值。请参考 DefaultPerformanceMetricProvider 是如何遵循这一语义的。

通过修改 StatusUpdateTask.cs，用您的 IPerformanceMetricProvider 实现，来替换掉 DefaultPerformanceMetricProvider 这个默认实现，如下图。

Instantiate IPerformance Metric Provider