An article to quickly understand the oal of Apache skywalking

OAL brief introduction

In stream mode (Streaming mode) Next ,SkyWalking Provides Observation analysis language (Observability Analysis Language,OAL) To analyze the inflow data .

OAL Focus on Service , Metrics for service instances and endpoints , therefore OAL Very easy to learn and use .

6.3 After the version ,OAL The engine is embedded in OAP In the server runtime , be called oal-rt(OAL Runtime ). OAL The script is now in /config Folder , The user can simply change and restart the server , Make it effective .

however ,OAL Scripts are still compiled languages ,OAL Dynamically generated at run time Java Code . You can set... On the system environment SW_OAL_ENGINE_DEBUG=Y, See which classes are generated .

OAL grammar

OAL The script file should be in .oal For the suffix .

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

// Disable hard code 
disable(METRICS_NAME);

Domain (Scope)

Domains include overall situation (All)、 service (Service)、 Service instance (Service Instance)、 Endpoint (Endpoint)、 Service relationship (Service Relation)、 Service instance relationships (Service Instance Relation)、 Endpoint relationship (Endpoint Relation).

There are, of course, some fields , They all belong to one of these domains .

filter (Filter)

When using filters , Construct filter conditions for field values by specifying field names or expressions .

Expressions can use and,or and () Are combined . The operator contains ==,!=,>,<,>=,<=,in [...],like %...,like ...%,like %...%, They can do type checking based on field types , If the type is not compatible, it will be compiled / Error reported during code generation .

Aggregate functions (Aggregation Function)

The default aggregate function is created by SkyWalking OAP The core to realize . And more functions can be expanded freely .

Provided function ：

• longAvg： The average of all inputs for a domain entity , The input field must be long type .

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

In the example above , Input is ServiceInstanceJVMMemory Each request for the domain , The average is based on the field max To evaluate .

• doubleAvg： The average of all inputs for a domain entity , The input field must be double type .

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

In the example above , Input is ServiceInstanceJVMCPU Each request for the domain , The average is based on usePercent Field to evaluate .

• percent： For the number of percentages in the input that match the specified criteria .

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

In the example above , The input is the request for each endpoint , On the condition that endpoint.status == true.

• rate： For conditional matching input , The ratio is 100 The score of means .

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

In the example above , All the inputs are requests for traffic from each browser application , The molecular condition is trafficCategory == BrowserAppTrafficCategory.FIRST_ERROR, The condition of denominator is trafficCategory == BrowserAppTrafficCategory.NORMAL. among , The first parameter is the condition of the molecule , The second parameter is the condition of denominator .

• sum： The total number of calls to a domain entity .

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

In the example above , Count the number of calls per service .

• histogram： Heat map , More on Heatmap in WIKI.

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

In the example above , The thermodynamic heat maps of all incoming requests are calculated . The first parameter is the accuracy of the delay calculation , In the example above , stay 101-200ms In the group ,113ms and 193ms To be considered the same . The second parameter is the number of groups , In the example above , Altogether 21 The group data are 0-100ms,101-200ms……1901-2000ms,2000ms above .

• apdex： Application performance index (Application Performance Index), More on Apdex in WIKI.

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

In the example above , The application performance index of all services is calculated . The first parameter is the service name , The name of Apdex The threshold is in the configuration file service-apdex-threshold.yml In the definition of . The second parameter is the request status , state ( Success or failure ) influence Apdex The calculation of .

• P99,P95,P90,P75,P50： Percentile , More on Percentile in WIKI.

Percentile Is from 7.0 The first multivalued measure introduced by version . Because there are multiple values , Can pass getMultipleLinearIntValuesGraphQL Query to query .

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

In the example above , All incoming requests are calculated P99,P95,P90,P75,P50. The parameter is the accuracy of percentile calculation , In the example above 120ms and 124 To be considered the same .

Metric name (Metrics Name)

Storage implementation , Alarm and query module metrics name ,SkyWalking The kernel supports automatic type inference .

Group (Group)

All metrics data will use Scope.ID And the minimum time bucket (min-level time bucket) Grouping .

• In the domain of the endpoint ,Scope.ID For the endpoint ID（ Based on the unique identity of the service and its endpoints ）.

Ban (Disable)

Disable yes OAL Advanced statements in , Use only in specific situations . Some of the aggregations and metrics are defined through core hard code , This Disable Statements are designed to stop them , such as segment, top_n_database_statement. By default , There are no forbidden .

Example

//  Calculate the average response time of each endpoint 
endpoint_avg = from(Endpoint.latency).avg()

//  Calculate each endpoint  p50,p75,p90,p95 and p99  The delay histogram of , every other  50  It's a column 
endpoint_percentile = from(Endpoint.latency).percentile(10)

//  The response status of each service is  true  Percent of 
endpoint_success = from(Endpoint.*).filter(status == true).percent()

//  Calculate the response code of each service as [404, 500, 503] The sum of 
endpoint_abnormal = from(Endpoint.*).filter(responseCode in [404, 500, 503]).sum()

//  Calculate the request type for each service as [PRC, gRPC] The sum of 
endpoint_rpc_calls_sum = from(Endpoint.*).filter(type in [RequestType.PRC, RequestType.gRPC]).sum()

//  Calculate the endpoint name of each endpoint as ["/v1", "/v2"] The sum of 
endpoint_url_sum = from(Endpoint.*).filter(endpointName in ["/v1", "/v2"]).sum()

//  Count the total number of calls per service 
endpoint_calls = from(Endpoint.*).sum()

disable(segment);
disable(endpoint_relation_server_side);
disable(top_n_database_statement);

notes ： This article takes SkyWalking Of 8.2.0 Version as an example , If the version is different, there will be a slight difference .