Metric SQL 使用者手冊

本手冊面向使用者，系統地介紹了 Metrics SQL 語言的語法與使用方式。

# 目錄

# 約定

為了方便起見，在本文件中我們使用 msql 來表示 Ops 語言。

有問題的示例程式碼會在每行開頭標記問號 ?。例如：

? select *;

# 描述

Metrics SQL 語言受 SQL 語言啟發，但從未打算與 SQL 標準或某些 SQL 方言 100% 相容。儘管如此，Metrics SQL 程式碼可能看起來與 SQL 程式碼非常相似。

Metrics SQL 語言作為 OpenResty Edge 平臺的一部分提供。它是為 OpenResty Edge 快速建立新動態指標的一種方式。

返回目錄

# 程式佈局

Metrics SQL 程式由多個用分號分隔的語句組成。目前只允許單個 select 查詢語句，但這在將來可能會改變。下面是一個例子：

select uri, host, count(*)
from reqs group by uri, host limit 10;

最後一個語句的尾隨分號可以省略。

返回目錄

# 詞法結構

# 整數

整數可以表示為十進位制或十六進位制字面量，如：

-3
519
0xdeadbeef

返回目錄

# 浮點數

浮點數可以表示如下：

3.1415926
2e8
4.2E2

返回目錄

# 字串字面量

字串字面量用單引號括起來，就像標準 SQL 語言一樣，如：

'hello, world!'

此外，我們支援以下特殊轉義序列來指定特殊字元：

\a          響鈴，ascii 碼 0x07
\b          退格，ascii 碼 0x08
\f          換頁，ascii 碼 0x0c
\n          換行
\r          回車
\t          製表符
\v          垂直製表符
\\          反斜槓 (\)
\'          單引號字元 (')
\"          雙引號字元 (")
\<newline>  換行字元，就像 \n

下面是使用轉義序列的例子：

'hello\nworld\t!'

返回目錄

# 正規表示式字面量

正規表示式字面量是表示用於模式匹配的正規表示式的一種方式（與 like 二元運算子一起使用）。正規表示式字面量，比如 /[0-9]+/，可以用不同的分隔符括起來，如：

/[0-9]+/

rx/[0-9]+/

rx{[0-9]+}

rx([0-9]+)

rx[[0-9]+]

rx'[0-9]+'

rx"[0-9]+"

rx![0-9]+!

您可以選擇最佳分隔符來最小化正規表示式模式本身內部必要的轉義。

目前只允許 Perl 相容正規表示式和 POSIX 正規表示式語法的通用子集，但不包括反向引用語法（如 \1、\2 等）。我們可能在將來取消這個限制。

支援使用括號的子匹配捕獲。

返回目錄

# 布林字面量

Metrics SQL 中的布林字面量就是 true 和 false，就像在 SQL 中一樣。

返回目錄

# 空值

特殊的 null 關鍵字表示空值（類似於 SQL 中的 null 值）。

Metrics SQL 通常不涉及空值，因此這個字面量很少使用。包含它只是為了完整性。

返回目錄

# 表

表名必須始終以其完全限定形式指定，除非使用者給出別名（如在 from 子句中使用 as ALIAS 語法）。

Metrics SQL 目前支援一個內建表 reqs。詳見"內建表"部分。

返回目錄

# 列

當沒有歧義時，列名可以用其裸名稱表示，如 uri 和 host，或者用帶表名的完全限定形式，如：

select uri, count(*)
from reqs group by uri

其中 uri 列使用完全限定形式 reqs.uri 指定。

列也可以透過使用者別名間接引用（如在 select 列表中使用 as ALIAS 語法）。

返回目錄

# 運算子和表示式

Metrics SQL 支援許多類似 SQL 的運算子和表示式型別，並有一些自己的補充。

所有運算子的優先順序表如下：

3    一元 !
4    - (一元減號), + (一元加號)
5    || (字串連線)
7    *, /, %
8    二元 -, +
12    = (比較), >=, >, <=, <, <>, !=, is, like, in, prefix, suffix, contains
13    between
14    not
15    and
17    or
19    left join, inner join
20    , (交叉連線)

通常可以使用括號 (...) 來組合優先順序較低的運算子。

not ... 變體如 not between 和 is not 未在運算子優先順序表中列出。

返回目錄

# 算術表示式

Metrics SQL 支援以下二元算術運算子：加法（+）、減法（-）、乘法（*）、除法（/）和取模（%）。

它還支援一元算術運算子 - 和 +。

返回目錄

# 字串連線

支援 SQL 風格的字串連線運算子 ||。

返回目錄

# 關係表示式

Metrics SQL 支援大多數常見的 SQL 風格關係運算子：

• =（等於）
• != 或 <>（不等於）
• <=
• <
• >
• >=
• between ... and（開發中）
• in (value...)（開發中）
• like 和 not like
• is 或 is not（開發中）

like 運算子支援兩種形式的模式：

1. （開發中） 帶有元字元的 SQL 風格模式，如 %（匹配零個或多個任意字元）和 _（匹配一個任意字元）。元字元可以用反斜槓（/）轉義以表示 % 和 _ 字元本身。
2. 正規表示式字面量，如 /.../ 和 rx{...}。

此外，Metrics SQL 支援以下字串匹配運算子，分別測試右側字串是否是左側字串的字首、子字串或字尾：

• prefix
• contains
• suffix

返回目錄

# 邏輯表示式

支援以下 SQL 風格邏輯運算子：

• 二元 and
• 二元 or
• 一元 not

返回目錄

# 子查詢

Metrics SQL 目前不支援子查詢，儘管 Metrics SQL 編譯器可以很好地解析它們。

返回目錄

# Select 查詢語句

此語句包含一個帶有以下一個或多個子句的單個 select 查詢。注意 select 子句始終是必需的。

返回目錄

# Select 子句

支援 SQL 風格的 select 子句。下面是一些例子：

select host, count(*) from reqs group by host;

聚合函式和轉換函式可以出現在 select 列表中。關係表示式、算術表示式和字串連線表示式也可以。目前不允許邏輯表示式。我們可能在將來取消這個限制。

每個選定的值可以在值表示式後面帶一個可選的別名，就像在標準 SQL 中一樣，如：

select avg(active_conns) as active from http;

聚合函式如 sum()、avg()、min()、max() 和 count() 也可以在選定的值表示式中使用，如：

select count(*), sum(latency_s)
from reqs;

轉換函式如 hist_log() 也可以在選定的值表示式中使用，如：

select count(*), hist_log(latency_ms) as latency
from reqs group by latency;

返回目錄

# From 子句

from 子句也類似於標準 SQL 語言。可以指定單個表，如：

select uri, count(*)
from reqs group by uri;

返回目錄

# Where 子句

where 子句與標準 SQL 語言相同。可以在這裡指定邏輯表示式作為搜尋條件。下面是一個例子：

select count(*)
from reqs
where uri prefix '/css/';

返回目錄

# Group By 子句

group by 子句類似於標準 SQL 語言，如：

select count(*) as cnt, host
from reqs
group by host
order by cnt desc
limit 10;

返回目錄

# Order By 子句

order by 子句類似於標準 SQL 語言。Metrics SQL 目前有一些限制：

1. order by 子句中只允許一列。
2. order by 列只能是列名或 count() 聚合函式。

下面是一個例子：

select count(*), host
from reqs
group by host
order by count(*) desc;

也可以在 order by 子句中引用選定值表示式的別名（如果有的話），如：

select count(*) cnt, host
from reqs
group by host
order by cnt desc;

返回目錄

# Limit 子句

limit 子句類似於標準 SQL 語言。下面是一個例子：

select *
from reqs
limit 10;

返回目錄

# Offset 子句（開發中）

offset 子句語法類似於 PostgreSQL 提供的 PL/SQL 語言。下面是一個例子：

select *
from reqs
offset 1
limit 10;

這將跳過第一行，只輸出第 2 到第 10 行。

返回目錄

# 內建表

下面是 Metrics SQL 編譯器當前支援的內建表的詳細列表。我們正在快速新增新表和新列。

返回目錄

# reqs

此表用於檢查 nginx（主）請求。這裡排除了 Nginx 子請求。

它有以下列：

• args

  HTTP 請求的 URI 查詢字串。

• host

  HTTP 請求的主機名。

• latency_ms

  表示請求延遲（毫秒）的整數，如 120。

• latency_s

  表示請求延遲（秒）的浮點數，如 0.32。

• keepalive

  布林值，表示當前請求是否為當前 TCP 連線啟用 HTTP keep-alive。

• method

  HTTP 請求的方法字串。

• scheme

  當前 HTTP 請求的協議字串，如 http 和 https。

• uri

  HTTP 請求 URI（不包括任何查詢字串）。

• raw_uri

  HTTP 原始請求 URI（包括查詢字串）。

• client_ip

  字串。IP 地址（IPv4 或 IPv6 或 unix socket 檔案路徑）。

• req_size

  整數。整個請求大小（包括頭部和正文）的位元組數。

• req_body_size

  整數。請求正文大小的位元組數。

• resp_size

  整數。整個響應大小（包括頭部和正文）的位元組數（如果涉及壓縮，則為壓縮後的大小）。

• resp_body_size

  整數。響應正文大小的位元組數。

• total_size

  整數。下游請求的總大小，包括 req_size 和 resp_size。

• server_city

  字串。基於伺服器 IP 地址查詢地理資訊資料獲得的城市名稱

• server_province

  字串。基於伺服器 IP 地址查詢地理資訊資料獲得的省份名稱

• server_country

  字串。基於伺服器 IP 地址查詢地理資訊資料獲得的國家名稱

• server_continent

  字串。基於伺服器 IP 地址查詢地理資訊資料獲得的大洲名稱

• server_isp

  字串。基於伺服器 IP 地址查詢地理資訊資料獲得的 ISP 名稱

• server_latitude

  字串。基於伺服器 IP 地址查詢地理資訊資料獲得的緯度

• server_longtitude

  字串。基於伺服器 IP 地址查詢地理資訊資料獲得的經度

• server_port

  整數。當前請求訪問的伺服器埠。

• status

  整數。HTTP 響應狀態碼（如 502 和 200）或內部 nginx 錯誤碼（如果沒有有意義的 HTTP 狀態碼可用）。

• status_class

  字串。分類後的 HTTP 響應狀態碼，如 2xx/3xx/4xx/5xx。

• is_ssl

  布林值。當前請求是否使用 SSL 或 TLS。

• tls_ver

  數字。TLS 協議版本號，如 1.2 和 1.3。

• ssl_ver

  數字。SSL 協議版本號，如 2 和 3。

• resp_is_chunked

  布林值。響應正文是否使用分塊編碼。

• req_is_chunked

  布林值。請求正文是否使用分塊編碼。

• http_ver

  數字。HTTP 協議版本（0.9、1.0、1.1、2.0）。

• is_websocket

  布林值。當前請求是否已升級到 WebSocket 協議。

• resp_is_compressed

  布林值。當前請求的響應正文是否被壓縮（透過 gzip 或其他編碼）。

• mime_type

  字串。應該是像 application/javascript 這樣的值。應排除任何尾隨引數，如 ; charset=utf-8。

• uses_lua

  布林值。當前請求是否在任何請求處理階段使用任何 Lua 程式碼處理程式（如 log_by_lua、rewrite_by_lua 等）。

• for_static_file

  布林值。當前請求是否使用靜態檔案模組來提供當前機器檔案系統上的靜態檔案。

• has_upstream

  布林值。當前請求是否使用代理（即使用 nginx upstream 模組）。

• uses_error_page

  布林值。當前請求是否提供錯誤頁面。

• uri_changes

  整數。在請求處理階段完成的 URI 更改次數（對應 r->uri_changes）。

• uri_changed

  布林值。當前請求的 URI 是否曾被請求處理階段更改（對應 r->uri_changed）。

• is_pipelined

  布林值。當前請求是否是管道請求（即 C 層面的 r->pipeline）。

• resp_header_only

  布林值。當前響應是否只有頭部（r->header_only）。

• location

  字串。最後服務當前請求的 nginx location 名稱。

• user_agent

  字串。User-Agent 字串。

• conn_is_reused

  布林值。當前請求是否重用了由較早請求建立的連線。

• upstream_addr

  字串。用於連線到上游伺服器的最後一個上游地址。

• upstream_cache_status

  字串。上游快取狀態。 如果沒有上游則為空字串，否則為以下之一：MISS BYPASS EXPIRED STALE UPDATING REVALIDATED HIT

• is_upstream_cache_status_hit

  字串。當前請求的快取狀態為 HIT，表示請求的內容在快取中找到且有效，響應直接從快取提供。此變數於 25.6.20-1 版本首次引入。

• is_upstream_cache_status_miss

  字串。當前請求的快取狀態為 MISS，表示請求的內容在快取中未找到，需要從上游伺服器獲取。此變數於 25.6.20-1 版本首次引入。

• is_upstream_cache_status_bypass

  字串。當前請求的快取狀態為 BYPASS，表示快取被繞過，請求直接轉發到上游伺服器而不使用快取。此變數於 25.6.20-1 版本首次引入。

• is_upstream_cache_status_expired

  字串。當前請求的快取狀態為 EXPIRED，表示快取內容已過期，需要從上游伺服器重新獲取。此變數於 25.6.20-1 版本首次引入。

• is_upstream_cache_status_stale

  字串。當前請求的快取狀態為 STALE，表示快取內容已過期但仍可用，通常在上游伺服器不可用時返回。此變數於 25.6.20-1 版本首次引入。

• is_upstream_cache_status_updating

  字串。當前請求的快取狀態為 UPDATING，表示快取正在更新，當前請求使用舊的快取內容提供服務。此變數於 25.6.20-1 版本首次引入。

• is_upstream_cache_status_revalidated

  字串。當前請求的快取狀態為 REVALIDATED，表示快取內容已與上游伺服器重新驗證並確認仍然有效。此變數於 25.6.20-1 版本首次引入。

• upstream_byte_sent

  整數。傳送到上游伺服器的位元組數。多個上游伺服器的值將相加。

• upstream_byte_received

  整數。從上游伺服器接收的位元組數。多個上游伺服器的值將相加。

• upstream_byte_total

  整數。傳送到上游伺服器和從上游伺服器接收的位元組數。多個上游伺服器的值將相加。

• upstream_body_length

  整數。從上游伺服器獲得的響應長度。多個上游伺服器的值將相加。

• upstream_header_timer_ms

  整數。從上游伺服器接收響應頭部所花費的時間；時間以毫秒解析度儲存。多個響應的時間相加。

• upstream_connect_timer_ms

  整數。與上游伺服器建立連線所花費的時間；時間以毫秒解析度儲存。在 SSL 情況下，包括握手所花費的時間。多個連線的時間相加。

• upstream_resp_timer_ms

  整數。從上游伺服器接收響應所花費的時間；時間以毫秒解析度儲存。多個響應的時間相加。

• client_city

  字串。基於客戶端 IP 地址查詢地理資訊資料獲得的城市名稱

• client_province

  字串。基於客戶端 IP 地址查詢地理資訊資料獲得的省份名稱

• client_country

  字串。基於客戶端 IP 地址查詢地理資訊資料獲得的國家名稱

• client_continent

  字串。基於客戶端 IP 地址查詢地理資訊資料獲得的大洲名稱

• client_isp

  字串。基於客戶端 IP 地址查詢地理資訊資料獲得的 ISP 名稱

• client_latitude

  字串。基於客戶端 IP 地址查詢地理資訊資料獲得的緯度

• client_longtitude

  字串。基於客戶端 IP 地址查詢地理資訊資料獲得的經度

• is_status_2xx

  布林值。當前請求的響應狀態是否在 200 到 299 之間。

• is_status_3xx

  布林值。當前請求的響應狀態是否在 300 到 399 之間。

• is_status_4xx

  布林值。當前請求的響應狀態是否在 400 到 499 之間。

• is_status_5xx

  布林值。當前請求的響應狀態是否在 500 到 599 之間。

• is_status_other

  布林值。當前請求的響應狀態是否小於 200 或大於 599。

• is_upstream_status_2xx

  布林值。當前請求的響應狀態是否在 200 到 299 之間。

• is_upstream_status_3xx

  布林值。上游的響應狀態是否在 300 到 399 之間。

• is_upstream_status_4xx

  布林值。上游的響應狀態是否在 400 到 499 之間。

• is_upstream_status_5xx

  布林值。上游的響應狀態是否在 500 到 599 之間。

• is_upstream_status_other

  布林值。上游的響應狀態是否小於 200 或大於 599。

• is_status_400

  布林值。響應狀態是否為 400。

• is_status_403

  布林值。響應狀態是否為 403。

• is_status_404

  布林值。響應狀態是否為 404。

• is_status_412

  布林值。響應狀態是否為 412。

• is_status_429

  布林值。響應狀態是否為 429。

• is_status_500

  布林值。響應狀態是否為 500。

• is_status_502

  布林值。響應狀態是否為 502。

• is_status_503

  布林值。響應狀態是否為 503。

• is_status_504

  布林值。響應狀態是否為 504。

• is_upstream_status_400

  布林值。上游的響應狀態是否為 400。

• is_upstream_status_403

  布林值。上游的響應狀態是否為 403。

• is_upstream_status_404

  布林值。上游的響應狀態是否為 404。

• is_upstream_status_412

  布林值。上游的響應狀態是否為 412。

• is_upstream_status_429

  布林值。上游的響應狀態是否為 429。

• is_upstream_status_500

  布林值。上游的響應狀態是否為 500。

• is_upstream_status_502

  布林值。上游的響應狀態是否為 502。

• is_upstream_status_503

  布林值。上游的響應狀態是否為 503。

• is_upstream_status_504

  布林值。上游的響應狀態是否為 504。

# HTTP

此表主要用於統計連線數。

它有以下列：

• active_conns

  當前活躍客戶端連線數，包括等待連線。

• waiting_conns

  當前等待請求的空閒客戶端連線數。

• writing_conns

  當前 openresty edge 正在向客戶端寫回響應的連線數。

• reading_conns

  當前 openresty edge 正在讀取請求頭部的連線數。

返回目錄

# 示例

# 示例一：統計統計命中率 TOP 10 的域名

select host, sum(is_upstream_cache_status_hit) / count(*) * 100 as cache_hit_ratio_percent
from reqs
where upstream_cache_status != ''
group by host
order by cache_hit_ratio_percent desc
limit 10

返回目錄

# 作者

章亦春 yichun@openresty.com，OpenResty Inc.

返回目錄

# 版權和許可

版權所有 (C) 2020-2021 OpenResty Inc. 保留所有權利。

本文件為專有文件，包含機密資訊。未經版權持有者書面許可，禁止在任何時候重新分發本文件。

返回目錄