1.6 如何使用

科技2025-07-15 17

Pt1 注解支持

@SentinelResource

Pt2 动态规则扩展

Pt2.1 DataSource 扩展

Pt3 实时监控

Pt3.1 簇点监控

获取簇点列表

查询某个簇点的详细信息

簇点调用者统计信息

Pt3.2 链路监控

Pt3.3 历史资源数据

资源的秒级日志

被拦截的秒级日志

实时查询

Pt1 注解支持

Sentinel 提供了 @SentinelResource 注解用于定义资源，并提供了 AspectJ 的扩展用于自动定义资源、处理 BlockException 等。使用 Sentinel Annotation AspectJ Extension 的时候需要引入以下依赖：

<dependency> <groupId>com.alibaba.csp</groupId> <artifactId>sentinel-annotation-aspectj</artifactId> <version>x.y.z</version> </dependency>

@SentinelResource

注意：注解方式埋点不支持 private 方法。

@SentinelResource 用于定义资源，并提供可选的异常处理和 fallback 配置项。 @SentinelResource 注解包含以下属性：

value：资源名称，必需项（不能为空）

entryType：entry 类型，可选项（默认为 EntryType.OUT）

blockHandler / blockHandlerClass: blockHandler 对应处理 BlockException 的函数名称，可选项。blockHandler 函数访问范围需要是 public，返回类型需要与原方法相匹配，参数类型需要和原方法相匹配并且最后加一个额外的参数，类型为 BlockException。blockHandler 函数默认需要和原方法在同一个类中。若希望使用其他类的函数，则可以指定 blockHandlerClass 为对应的类的 Class 对象，注意对应的函数必需为 static 函数，否则无法解析。

fallback / fallbackClass：fallback 函数名称，可选项，用于在抛出异常的时候提供 fallback 处理逻辑。fallback 函数可以针对所有类型的异常（除了 exceptionsToIgnore 里面排除掉的异常类型）进行处理。fallback 函数签名和位置要求：

返回值类型必须与原函数返回值类型一致；

方法参数列表需要和原函数一致，或者可以额外多一个 Throwable 类型的参数用于接收对应的异常。

fallback 函数默认需要和原方法在同一个类中。若希望使用其他类的函数，则可以指定 fallbackClass 为对应的类的 Class 对象，注意对应的函数必需为 static 函数，否则无法解析。

defaultFallback（since 1.6.0）：默认的 fallback 函数名称，可选项，通常用于通用的 fallback 逻辑（即可以用于很多服务或方法）。默认 fallback 函数可以针对所有类型的异常（除了exceptionsToIgnore里面排除掉的异常类型）进行处理。若同时配置了 fallback 和 defaultFallback，则只有 fallback 会生效。defaultFallback 函数签名要求：

返回值类型必须与原函数返回值类型一致；

方法参数列表需要为空，或者可以额外多一个 Throwable 类型的参数用于接收对应的异常。

defaultFallback 函数默认需要和原方法在同一个类中。若希望使用其他类的函数，则可以指定 fallbackClass 为对应的类的 Class 对象，注意对应的函数必需为 static 函数，否则无法解析。

exceptionsToIgnore（since 1.6.0）：用于指定哪些异常被排除掉，不会计入异常统计中，也不会进入 fallback 逻辑中，而是会原样抛出。

注：1.6.0 之前的版本 fallback 函数只针对降级异常（DegradeException）进行处理，不能针对业务异常进行处理。

特别地，若 blockHandler 和 fallback 都进行了配置，则被限流降级而抛出 BlockException 时只会进入 blockHandler 处理逻辑。若未配置 blockHandler、fallback 和 defaultFallback，则被限流降级时会将 BlockException 直接抛出（若方法本身未定义 throws BlockException 则会被 JVM 包装一层 UndeclaredThrowableException）。

示例：

public class TestService { // 对应的 `handleException` 函数需要位于 `ExceptionUtil` 类中，并且必须为 static 函数. @SentinelResource(value = "test", blockHandler = "handleException", blockHandlerClass = {ExceptionUtil.class}) public void test() { System.out.println("Test"); } // 原函数 @SentinelResource(value = "hello", blockHandler = "exceptionHandler", fallback = "helloFallback") public String hello(long s) { return String.format("Hello at %d", s); } // Fallback 函数，函数签名与原函数一致或加一个 Throwable 类型的参数. public String helloFallback(long s) { return String.format("Halooooo %d", s); } // Block 异常处理函数，参数最后多一个 BlockException，其余与原函数一致. public String exceptionHandler(long s, BlockException ex) { // Do some log here. ex.printStackTrace(); return "Oops, error occurred at " + s; } }

从 1.4.0 版本开始，注解方式定义资源支持自动统计业务异常，无需手动调用 Tracer.trace(ex) 来记录业务异常。Sentinel 1.4.0 以前的版本需要自行调用 Tracer.trace(ex) 来记录业务异常。

Pt2 动态规则扩展

Sentinel 的理念是开发者只需要关注资源的定义，当资源定义成功后可以动态增加各种流控降级规则。Sentinel 提供两种方式修改规则：

通过 API 直接修改 (loadRules)

通过 DataSource 适配不同数据源修改

手动通过 API 修改比较直观，可以通过以下几个 API 修改不同的规则：

FlowRuleManager.loadRules(List<FlowRule> rules); // 修改流控规则 DegradeRuleManager.loadRules(List<DegradeRule> rules); // 修改降级规则

手动修改规则（硬编码方式）一般仅用于测试和演示，生产上一般通过动态规则源的方式来动态管理规则。

Pt2.1 DataSource 扩展

上述 loadRules() 方法只接受内存态的规则对象，但更多时候规则存储在文件、数据库或者配置中心当中。DataSource 接口给我们提供了对接任意配置源的能力。相比直接通过 API 修改规则，实现 DataSource 接口是更加可靠的做法。

我们推荐通过控制台设置规则后将规则推送到统一的规则中心，客户端实现 ReadableDataSource 接口端监听规则中心实时获取变更，流程如下：

DataSource 扩展常见的实现方式有:

拉模式：客户端主动向某个规则管理中心定期轮询拉取规则，这个规则中心可以是 RDBMS、文件，甚至是 VCS 等。这样做的方式是简单，缺点是无法及时获取变更；

推模式：规则中心统一推送，客户端通过注册监听器的方式时刻监听变化，比如使用 Nacos、Zookeeper 等配置中心。这种方式有更好的实时性和一致性保证。

Sentinel 目前支持以下数据源扩展：

Pull-based: 动态文件数据源、Consul, Eureka

Push-based: ZooKeeper, Redis, Nacos, Apollo, etcd

Pt3 实时监控

Sentinel 提供对所有资源的实时监控。如果需要实时监控，客户端需引入以下依赖（以 Maven 为例）：

<dependency> <groupId>com.alibaba.csp</groupId> <artifactId>sentinel-transport-simple-http</artifactId> <version>x.y.z</version> </dependency>

引入上述依赖后，客户端便会主动连接 Sentinel 控制台。通过 Sentinel 控制台即可查看客户端的实时监控。

通常您并不需要关心以下 API，但是如果您对开发控制台感兴趣，以下为监控 API 的文档。

Pt3.1 簇点监控

获取簇点列表

查询某个簇点的详细信息

可以用下面命令模糊查询该簇点的具体信息，其中 id 对应 resource name，支持模糊查询：

curl http://localhost:8719/cnode?id=xxxx

结果示例：

idx id thread pass blocked success total aRt 1m-pass 1m-block 1m-all exeption 6 /app/aliswitch2/machines.json 0 0 0 0 0 0 0 0 0 0 7 /app/sentinel-admin/machines.json 0 1 0 1 1 6 0 0 0 0 8 /identity/machine.json 0 0 0 0 0 0 0 0 0 0 9 /registry/machine 0 2 0 2 2 1 192 0 192 0 10 /app/views/machine.html 0 1 0 1 1 2 0 0 0 0

簇点调用者统计信息

可以用下列命令查询该簇点的调用者统计信息：

curl http://localhost:8719/origin?id=xxxx

结果示例：

id: nodeA idx origin threadNum passedQps blockedQps totalQps aRt 1m-passed 1m-blocked 1m-total 1 caller1 0 0 0 0 0 0 0 0 2 caller2 0 0 0 0 0 0 0 0

其中的 origin 由 ContextUtil.enter(resourceName，origin) 方法中的 origin 指定。

Pt3.2 链路监控

我们可以通过命令 curl http://localhost:8719/tree 来查询链路入口的链路树形结构：

EntranceNode: machine-root(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0) -EntranceNode1: Entrance1(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0) --nodeA(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0) -EntranceNode2: Entrance1(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0) --nodeA(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0) t:threadNum pq:passQps bq:blockedQps tq:totalQps rt:averageRt prq: passRequestQps 1mp:1m-passed 1mb:1m-blocked 1mt:1m-total

Pt3.3 历史资源数据

资源的秒级日志

所有资源的秒级监控日志（metric 日志）在 ${home}/logs/csp/${appName}-metrics.log.${date}.xx。例如，该日志的名字可能为 my-service-metrics.log.2018-06-22.1。日志示例：

1529573107000|2018-06-21 17:25:07|sayHello(java.lang.String,long)|10|3601|10|0|2|0|0|1

格式说明：

index例子说明11529573107000时间戳22018-06-21 17:25:07日期3sayHello(java.lang.String,long)资源名称410每秒通过的资源请求个数 (pass QPS)53601每秒资源被拦截的个数 (block QPS)610每秒完成调用的资源个数 (complete QPS)，包括正常结束和异常结束的情况70每秒资源的异常个数 (error QPS)82资源平均响应时间（ms）90该秒占用未来请求的数目（since 1.5.0）100预留用111资源分类（since 1.7.0）

被拦截的秒级日志

同样的，每秒的拦截日志（block 日志）也会出现在 <用户目录>/logs/csp/sentinel-block.log 文件下。如果没有发生拦截，则该日志不会出现。

2014-06-20 16:35:10|1|sayHello(java.lang.String,long),FlowException,default,origin|61,0 2014-06-20 16:35:11|1|sayHello(java.lang.String,long),FlowException,default,origin|1,0 index例子说明12014-06-20 16:35:10时间戳21该秒发生的第一个资源3sayHello(java.lang.String,long)资源名称4XXXException拦截的原因, 通常 FlowException 代表是被限流规则拦截，DegradeException 则表示被降级，SystemBlockException 则表示被系统保护拦截5default生效规则的调用来源（参数限流中代表生效的参数）6origin被拦截资源的调用者，可以为空761,061 被拦截的数量，0 无意义可忽略