OpenTsdb官方文檔----查詢過濾器

??任何數據庫系統的關鍵功能是使用某種形式的過濾來獲取完整數據集的子集。OpenTsdb從版本1.x開始提供了過濾功能，并從2.2開始具有了擴展功能。過濾器目前在標簽值上運行，這意味著在拉取數據時，任意指標和標簽Key都必須按照與數據庫中完全相同的出現方式來進行指定。

示例數據

??由于每個過濾器都會在下面進行說明，都會用到下述數據集。它由單一指標組成，定義在各個標簽上的多個時間序列。作為例子，在T1處僅給出一個數據點。

分組

??分組，即group by，是使用所需的聚合函數和過濾器將多個時間序列組合成一個的過程。默認情況下，OpenTSDB按指標對所有內容進行分組，以便如果查詢返回10個時間序列且使用sum聚合器，則所有10個序列將隨著時間的推移添加到一個值中。有關時間序列如何聚合合并的詳細信息，請參閱聚合。

??為了避免在沒有任何聚合的情況下對每個底層時間序列進行分組和獲取，請使用版本2.2中包含的聚合器。或者，可以禁用OpenTSDB2.2以及更高版本基于每個過濾器的分組。請參閱API文檔了解如何操作。

OpenTSDB 1.x – 2.1

??在最初的OpenTSDB版本中，最多只有兩種類型的過濾器可用，并且它們被隱式配置用于分組。允許的兩個運算符如下：

• *：星號（或通配符,wildcard）將為檢測到的每個唯一標簽值返回單獨的結果。例如，如果標簽鍵host有web01與web02這組值，將會有兩個組發出。一組為web01，另一組為web02。
• |：管道（或者literal_or）僅為指定的準確的標簽值返回單獨的結果。也就是說，它只會匹配具有給定標簽值的時間序列和聚合每個匹配成組。

??多個過濾器可以提供給一個查詢，過濾器之間使用AND連接，返回同時滿足條件的結果。這些過濾器在2.x以及更高版本中可用。

示例

??下面示例使用v1版本的HTTP URI棧，聚合器組成的參數m，冒號，緊接著指標以及花括弧里面通過等號分隔開的標簽過濾器。
??例1： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=web01}

??在這種情況下，聚合標簽集將為空，因為時間序列4和5具有與整個集合不相同的標簽。
??新版API實際運行情況：(與文檔描述不一致)
??查詢條件：

{
    "start":"23h-ago",
    "end":"10h-ago",
    "queries":[
        {
            "metric":"sys.cpu.system",
            "rate":"false",
            "aggregator":"sum",
            "tags":{
                "host":"web01"
            }
        }
    ]
}

??查詢結果：

[
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521689251":8,
            "1521689113":3,
            "1521689167":1,
            "1521689211":4
        },
        "aggregateTags":[
            "dc"
        ],
        "tags":{
            "owner":"jdoe",
            "host":"web01"
        }
    }
]

??例2： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=web01,dc=dal}

??新版API實際運行情況：(與文檔描述一致)
??查詢條件：

{
    "start":"1h-ago",
    "queries":[
        {
            "metric":"sys.cpu.system",
            "aggregator":"sum",
            "tags":{
                "host":"web01",
                "dc":"dal"
            }
        }
    ]
}

??查詢結果：

[
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521773430":3
        },
        "aggregateTags":[],
        "tags":{
            "host":"web01",
            "dc":"dal"
        }
    }
]

例3： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=*,dc=dal}

??這次我們為host標簽提供了*通配符以及顯示匹配dc標簽。這將對host標簽進行分組，并為每個唯一的host標簽值返回一個時間序列，在本例中為3個序列。

??新版API實際運行情況：(與文檔描述一致)
??查詢條件：

{
    "start":"1h-ago",
    "queries":[
        {
            "metric":"sys.cpu.system",
            "aggregator":"sum",
            "tags":{
                "host":"*",
                "dc":"dal"
            }
        }
    ]
}

??查詢結果：

[
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521773430":3
        },
        "aggregateTags":[],
        "tags":{
            "host":"web01",
            "dc":"dal"
        }
    },
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521773431":2
        },
        "aggregateTags":[],
        "tags":{
            "host":"web02",
            "dc":"dal"
        }
    },
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521773432":10
        },
        "aggregateTags":[],
        "tags":{
            "host":"web03",
            "dc":"dal"
        }
    }
]

??例4： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{dc=dal|lax}

??在這里，| 運算符僅用于匹配dc查詢中提供的標簽值。因此，TSD將會把擁有這些值的任意時間序列分組聚合在一起。host標簽被移動到聚合標簽列表中，設定的每個序列擁有一個host標簽，并且標簽擁有多個值。
??新版API實際運行情況：(與文檔描述一致)
??查詢條件：

{
    "start":"1h-ago",
    "queries":[
        {
            "metric":"sys.cpu.system",
            "aggregator":"sum",
            "tags":{
                "host":"*",
                "dc":"dal"
            }
        }
    ]
}

??查詢結果：

[
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521773430":3
        },
        "aggregateTags":[],
        "tags":{
            "host":"web01",
            "dc":"dal"
        }
    },
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521773431":2
        },
        "aggregateTags":[],
        "tags":{
            "host":"web02",
            "dc":"dal"
        }
    },
    {
        "metric":"sys.cpu.system",
        "dps":{
            "1521773432":10
        },
        "aggregateTags":[],
        "tags":{
            "host":"web03",
            "dc":"dal"
        }
    }
]

警告
??由于這些過濾器有限制，如果用戶像#1, #4和#5一樣編寫時間序列，則可能會由于聚合時間序列而返回異常結果，這些時間序列可能有一個通用的標簽但附加標簽不同。這個問題在2.3和顯式標簽中有所解決。

OpenTSDB 2.2

??在OpenTSDB 2.2版本中增加了一個更靈活的過濾框架，允許禁用分組以及增加了過濾器類型，如正則表達式和通配符。過濾框架是可插拔的，以允許嘗試進入外部系統如資產管理或供應系統。

??在處理過程中，在同一個標簽Key上可以有多個過濾器，比如它們之間用AND連接。如果有兩個過濾器host=literal_or(web01)和host=literal_or(web02)，查詢將會返回空。如果同一個標簽Key包含兩個或者更多過濾器，并且其中一個過濾器啟用了組，另一個未啟用，則對于該標簽Key上的所有過濾器，group by將實際為真。

警告
??某些類型的過濾器可能會導致查詢比其他的慢，特別是regexp,wildcard和大小寫不敏感的過濾器。在從存儲拉取數據之前，將對這些過濾器進行處理以基于UID創建數據庫過濾器，因此使用區分大小寫的literal_or過濾器總是比regexp快，因為可以將字符串解析為UID，并將它們發送到存儲系統進行過濾。相反，如果要求使用pre, post或infix過濾的正則表達式或通配符，則TSD必須使用標簽鍵UID從存儲中檢索所有行，然后對每個唯一行，將UID解析為字符串，然后再在結果上運行過濾器。此外，有大量文字(literals)列表的過濾器將在存儲后處理，以避免為后臺存儲創建大量過濾器。此限制的默認為4096，并且可以通過tsd.query.filter.expansion_limit參數進行配置。

顯示標簽

??從2.3及更高版本開始，如果給定指標所有的標簽值可以通過使用explicitTags功能大大降低查詢延遲。有兩個好處：

1. 對高基數的指標，后端可以切換到更高效的查詢以從存儲中獲取更小的數據子集。
2. 對于具有不同標簽的指標，這可以用于避免聚合不應包含在最終結果中的時間序列。
   ??顯示標簽將創建一個底層存儲查詢，該查詢僅獲取具有給定標簽Key的那些行。這可以讓數據庫跳過不相關的行，并在更短的時間內響應。
   ??例子：
   ??下面示例使用v1版本的HTTP URI棧，聚合器組成的參數m，冒號，緊接著指標以及花括弧里面通過等號分隔開的標簽過濾器。
   ??例1： http://host:4242/q?start=1h-ago&m=sum:explicit_tags:sys.cpu.system{host=web01}

??這解決了不一致的標簽key的問題，使我們只能篩選出時間序列#4。

??例2： http://host:4242/q?start=1h-ago&m=sum:explicit_tags:sys.cpu.system{host=*}{dc=*}

??此查詢使用v2版本URI語法，以避免將dc標簽key置于第二組花括號中進行分組。此時只篩選同時擁有host和dc標簽key的時間序列，然而僅僅根據host的值進行分組。它跳過了時間序列#4和#5。

注意：
??使用HBase(0.98或更高版本)或者Bigtable時，確保tsd.query.enable_fuzzy_filter已經在配置中啟用（默認啟用）。它為后端提供了一個特殊的過濾器，可以跳過我們需要查詢的行，而不是遍歷每一個rowkey進行正則表達式匹配比較。
注意：
??使用2.4版本，TSDB將會向后端發送多個get請求而不是一個scan請求。此時可以通過多種因素減少查詢時間，特別是對于高基數的時間序列。但是，過濾器只能由literal_or組成。

v2.2內置過濾器

??下述列表即OpenTSDB內置的過濾器。附加的過濾器可以插件的方式加載。每一個heading都是URI或JSON查詢中使用的type。在編寫URI查詢時，通過將過濾器名稱放在標簽key的等號右側并將過濾器值放在 括號中來使用過濾器。例如{host=regexp(web[0-9]+.lax.mysite.com)}。對于JSON查詢，只需使用過濾器名稱作為type參數，并使用過濾器值作為filter參數。例如：

??以下示例使用URI語法：

literal_or

??采用一個literal_or或|管道符連接值列表，則會返回區分大小寫敏的結果匹配時間序列。這是一個十分高效的過濾器，因為它可以將字符串解析為UID并將其發送到存儲層進行預過濾。它與SQL的IN謂詞類似。
例子：

• host=literal_or(web01|web02|web03)，類似于SQL：where host in(‘web01’,’web02’,’web03’)
• host=literal_or(web01)，類似于SQL: where host=’webb01’

iliteral_or

??（注意官方文中為ilteral_or，錯誤）

與literal_or類似但它不區分大小寫。請注意：它不像literal_or一樣高效，或者說它必須后處理存儲中的所有行。（即TSDB會取出存儲中的所有行進行過濾）

not_literal_or

與literal_or一樣區分大小寫，將返回與給定值列表不匹配的時間序列。因為它可以通過存儲進行預處理。

not_iliteral_or

??與not_literal_or過濾效果相同，但不區分大小寫

wildcard

??提供區分大小寫的后綴、前綴、中綴(infix)和多個中綴(multi-infix)過濾器。通配符是星號”*”。如果只給出星號，則過濾器有效地返回包含標簽key的任意時間序列（并且是可以預處理的高效過濾器）。在SQL的字段域中，它與LIKE謂詞相似，但具有更多的靈活性。
??例子：

• host=wildcard(*mysite.com)， SQL： where host=’%mysite.com’
• host=wildcard(web*)
• host=wildcard(web*mysite.com)
• host=wildcard(webmysite)
• host=wildcard(*)，與v1版本基礎的group by運算符等效，效率很高。

iwildcard

??與wildcard相同，但不區分大小寫。

regexp

??從存儲中獲取后使用符合POSIX標準正則表達式的過濾器過濾。該過濾器使用Java內置的正則表達式操作。根據查詢的使用方法，請注意轉義特殊字符。
??例子：

• regexp(web.), SQL: where host regexp ‘web.’
• regexp(web[0-9].mysite.com)

加載過濾器

??在OpenTSDB2.2及更高版本中顯示加載的過濾器，請調用HTTP接口/api/config/filters。它將列出加載的插件以及說明和示例用法。

插件

??隨著開發人員添加插件，將會在此處列出。
??如果要開發一個插件，只需擴展net.opentsdb.query.filter.TagVFilter類，然后根據插件文檔創建JAR包并將其放入插件目錄。在TSD啟動時，將會搜索插件并加載它。如果執行過程中出現錯誤，TSD將不會啟動并且記錄異常。