一篇文章快速搞懂 Apache SkyWalking 的 OAL

客官°小女子只卖身不卖艺 2023-01-17 11:00 138阅读 0赞

### OAL简介 ###

在流模式(Streaming mode)下，SkyWalking 提供了 观测分析语言(Observability Analysis Language，OAL) 来分析流入的数据。

OAL 聚焦于服务，服务实例以及端点的度量指标，因此 OAL 非常易于学习和使用。

6.3版本以后，OAL引擎嵌入在OAP服务器运行时中，称为`oal-rt`(OAL运行时)。  
OAL脚本现在位于`/config`文件夹，用户可以简单地改变和重新启动服务器，使其有效。

但是，OAL脚本仍然是编译语言，OAL运行时动态生成Java代码。  
您可以在系统环境上设置`SW_OAL_ENGINE_DEBUG=Y`，查看生成了哪些类。

### OAL语法 ###

OAL 脚本文件应该以 `.oal` 为后缀。

// Declare the metrics.
    METRICS_NAME = from(SCOPE.(* | [FIELD][,FIELD ...]))
    [.filter(FIELD OP [INT | STRING])]
    .FUNCTION([PARAM][, PARAM ...])
    
    // Disable hard code 
    disable(METRICS_NAME);

### 域(Scope) ###

域包括**全局**(All)、**服务**(Service)、**服务实例**(Service Instance)、**端点**(Endpoint)、**服务关系**(Service Relation)、**服务实例关系(Service Instance Relation)**、**端点关系**(Endpoint Relation)。

当然还有一些字段，他们都属于以上某个域。

### 过滤器(Filter) ###

使用在使用过滤器的时候，通过指定字段名或表达式来构建字段值的过滤条件。

表达式可以使用 `and`，`or` 和 `()` 进行组合。  
操作符包含`==`，`!=`，`>`，`<`，`>=`，`<=`，`in [...]`，`like %...`，`like ...%`，`like %...%`，他们可以基于字段类型进行类型检测,  
如果类型不兼容会在编译/代码生成期间报错。

### 聚合函数(Aggregation Function) ###

默认的聚合函数由 SkyWalking OAP 核心实现。并可自由扩展更多函数。

提供的函数：

*  `longAvg`：某个域实体所有输入的平均值，输入字段必须是 `long` 类型。

instance_jvm_memory_max = from(ServiceInstanceJVMMemory.max).longAvg();

在上面的例子中，输入是 `ServiceInstanceJVMMemory` 域的每个请求，平均值是基于字段 `max` 进行求值的。

*  `doubleAvg`：某个域实体的所有输入的平均值，输入的字段必须是 `double` 类型。

instance_jvm_cpu = from(ServiceInstanceJVMCPU.usePercent).doubleAvg();

在上面的例子中，输入是 `ServiceInstanceJVMCPU` 域的每个请求，平均值是基于 `usePercent` 字段进行求值的。

*  `percent`：对于输入中匹配指定条件的百分比数.

endpoint_percent = from(Endpoint.*).percent(status == true);

在上面的例子中，输入是每个端点的请求，条件是 `endpoint.status == true`。

*  `rate`：对于条件匹配的输入，比率以100的分数表示。

browser_app_error_rate = from(BrowserAppTraffic.*).rate(trafficCategory == BrowserAppTrafficCategory.FIRST_ERROR, trafficCategory == BrowserAppTrafficCategory.NORMAL);

在上面的例子中，所有的输入都是每个浏览器应用流量的请求，  
分子的条件是`trafficCategory == BrowserAppTrafficCategory.FIRST_ERROR`，  
分母的条件是`trafficCategory == BrowserAppTrafficCategory.NORMAL`。  
其中，第一个参数是分子的条件，第二个参数是分母的条件。

*  `sum`：某个域实体的调用总数。

service_calls_sum = from(Service.*).sum();

在上面的例子中，统计每个服务的调用数。

*  `histogram`：热力图，更多详见[Heatmap in WIKI][]。

all_heatmap = from(All.latency).histogram(100, 20);

在上面的例子中，计算了所有传入请求的热力学热图。  
第一个参数是计算延迟的精度，在上面的例子中，在101-200ms组中，113ms和193ms被认为是相同的.  
第二个参数是分组数量，在上面的例子中，一共有21组数据分别为0-100ms，101-200ms…1901-2000ms，2000ms以上.

*  `apdex`：应用性能指数(Application Performance Index)，更多详见[Apdex in WIKI][]。

service_apdex = from(Service.latency).apdex(name, status);

在上面的例子中，计算了所有服务的应用性能指数。  
第一个参数是服务名称，该名称的Apdex阈值在配置文件`service-apdex-threshold.yml`中定义。  
第二个参数是请求状态，状态(成功或失败)影响Apdex的计算。

*  `P99`，`P95`，`P90`，`P75`，`P50`：百分位，更多详见[Percentile in WIKI][]。

**百分位**是自7.0版本引入的第一个多值度量。由于有多个值，可以通过`getMultipleLinearIntValues`GraphQL查询进行查询。

all_percentile = from(All.latency).percentile(10);

在上面的例子中，计算了所有传入请求的 `P99`，`P95`，`P90`，`P75`，`P50`。参数是百分位计算的精度，在上例中120ms和124被认为是相同的。

### 度量指标名称(Metrics Name) ###

存储实现，告警以及查询模块的度量指标名称，SkyWalking 内核支持自动类型推断。

### 组(Group) ###

所有度量指标数据都会使用 `Scope.ID` 和最小时间桶(min-level time bucket) 进行分组.

*  在端点的域中，Scope.ID 为端点的 ID（基于服务及其端点的唯一标志）。

### 禁用(Disable) ###

`Disable`是OAL中的高级语句，只在特定情况下使用。  
一些聚合和度量是通过核心硬代码定义的，这个`Disable`语句是设计用来让它们停止活动的，  
比如`segment`, `top_n_database_statement`。  
在默认情况下，没有被禁用的。

### 示例 ###

// 计算每个端点的响应平均时长
    endpoint_avg = from(Endpoint.latency).avg()
    
    // 计算每个端点 p50，p75，p90，p95 and p99 的延迟柱状图，每隔 50 毫秒一条柱
    endpoint_percentile = from(Endpoint.latency).percentile(10)
    
    // 统计每个服务响应状态为 true 的百分比
    endpoint_success = from(Endpoint.*).filter(status == true).percent()
    
    // 计算每个服务的响应码为[404, 500, 503]的总和
    endpoint_abnormal = from(Endpoint.*).filter(responseCode in [404, 500, 503]).sum()
    
    // 计算每个服务的请求类型为[PRC, gRPC]的总和
    endpoint_rpc_calls_sum = from(Endpoint.*).filter(type in [RequestType.PRC, RequestType.gRPC]).sum()
    
    // 计算每个端点的端点名称为["/v1", "/v2"]的总和
    endpoint_url_sum = from(Endpoint.*).filter(endpointName in ["/v1", "/v2"]).sum()
    
    // 统计每个服务的调用总量
    endpoint_calls = from(Endpoint.*).sum()
    
    disable(segment);
    disable(endpoint_relation_server_side);
    disable(top_n_database_statement);

> 注：本文以SkyWalking的8.2.0版本为例进行介绍，如果版本不同会略有差异。

> 文章持续更新，微信搜索「**万猫学社**」第一时间阅读。  
> 关注后回复「**电子书**」，免费获取12本Java必读技术书籍。

[Heatmap in WIKI]: https://en.wikipedia.org/wiki/Heat_map
[Apdex in WIKI]: https://en.wikipedia.org/wiki/Apdex
[Percentile in WIKI]: https://en.wikipedia.org/wiki/Percentile