本文介紹通過Java SDK建立定時SQL任務的程式碼範例。
前提條件
已建立RAM使用者並完成授權。具體操作,請參見建立RAM使用者並完成授權。
已配置環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。具體操作,請參見在Linux、macOS和Windows系統配置環境變數。
重要阿里雲帳號的AccessKey擁有所有API的存取權限,建議您使用RAM使用者的AccessKey進行API訪問或日常營運。
強烈建議不要把AccessKey ID和AccessKey Secret儲存到工程代碼裡,否則可能導致AccessKey泄露,威脅您帳號下所有資源的安全。
已安裝0.6.69及以上版本的Java SDK。更多資訊,請參見安裝Java SDK。
背景資訊
Log Service提供定時SQL功能,用於定時分析資料、儲存彙總資料、投影與過濾資料。定時SQL支援標準SQL92文法、Log Service查詢和分析文法,按照調度規則周期性執行,並將運行結果寫入到目標庫(Logstore或Metricstore)中。
Log Service控制台提供可視化的建立定時SQL任務。具體操作,請參見建立定時SQL任務。
除此之外,Log Service提供ScheduledSQL、JobSchedule和ScheduledSQLConfiguration類,協助您更簡單的通過Java SDK建立定時SQL任務。
ScheduledSQL:建立一個定時SQL任務。
JobSchedule:建立定時SQL的調度任務。
ScheduledSQLConfiguration:建立定時SQL任務的基本配置。
範例程式碼
本樣本中,建立一個App.java檔案,將源Logstore的定時分析結果儲存到目標Logstore。樣本如下:
import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.*;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.request.CreateScheduledSQLRequest;
public class App {
// 本樣本從環境變數中擷取AccessKey ID和AccessKey Secret。
static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// 設定Project名稱和Logstore名稱。
static String sourceProject="aliyun-test-sourceProject";
static String destProject="aliyun-test-destProject";
static String sourceLogstore = "logstore-name";
static String destLogstore = "project-name";
static String roleArn = "acs:ram::11111111:role/aliyunlogetlrole";
// 設定Log Service的服務存取點。此處以杭州為例,其它地區請根據實際情況填寫。
static String endpoint = "http://cn-hangzhou.log.aliyuncs.com";
static String destEndpoint = "http://cn-hangzhou-intranet.log.aliyuncs.com";
static long fromTime = 1648105200; //2022-03-23 15:00:00
private static String script = "* | select a,b,c from log";
private static ScheduledSQLBaseParameters generateParams(String dataFormat) {
if (dataFormat.equalsIgnoreCase("log2log")) {
return null;
} else if (dataFormat.equalsIgnoreCase("log2metric")) {
Log2MetricParameters params = new Log2MetricParameters();
params.setMetricKeys("[\"a\", \"b\", \"c\"]");
params.setLabelKeys("[\"d\", \"e\", \"f\"]");
params.setHashLabels("[\"d\", \"f\"]");
params.setAddLabels("{\"m\":\"h\", \"n\":\"i\"}");
params.setTimeKey("time");
return params;
} else if (dataFormat.equalsIgnoreCase("metric2metric")) {
Metric2MetricParameters params = new Metric2MetricParameters();
params.setMetricName("name");
params.setHashLabels("[\"d\", \"f\"]");
params.setAddLabels("{\"m\":\"h\", \"n\":\"i\"}");
return params;
}
return null;
}
private static ScheduledSQLConfiguration generateConfig() {
ScheduledSQLConfiguration scheduledSQLConfiguration = new ScheduledSQLConfiguration();
scheduledSQLConfiguration.setScript(script);
scheduledSQLConfiguration.setSqlType("searchQuery");
scheduledSQLConfiguration.setResourcePool("enhanced");
scheduledSQLConfiguration.setRoleArn(roleArn);
scheduledSQLConfiguration.setDestRoleArn(roleArn);
scheduledSQLConfiguration.setSourceLogstore(sourceLogstore);
scheduledSQLConfiguration.setDestEndpoint(destEndpoint);
scheduledSQLConfiguration.setDestProject(destProject);
scheduledSQLConfiguration.setDestLogstore(destLogstore);
scheduledSQLConfiguration.setDataFormat("log2log");
scheduledSQLConfiguration.setFromTimeExpr("@m-1m");
scheduledSQLConfiguration.setToTimeExpr("@m");
scheduledSQLConfiguration.setMaxRetries(20);
scheduledSQLConfiguration.setMaxRunTimeInSeconds(600);
scheduledSQLConfiguration.setFromTime(fromTime);
scheduledSQLConfiguration.setToTime(0L);
ScheduledSQLBaseParameters params = generateParams(scheduledSQLConfiguration.getDataFormat());
scheduledSQLConfiguration.setParameters(params);
return scheduledSQLConfiguration;
}
private static ScheduledSQL generateScheduledSQL() {
ScheduledSQL scheduledSQLStructure = new ScheduledSQL();
scheduledSQLStructure.setName("job-name");
scheduledSQLStructure.setDisplayName("display-name");
scheduledSQLStructure.setDescription("desc-name");
ScheduledSQLConfiguration scheduledSQLConfiguration = generateConfig();
scheduledSQLStructure.setConfiguration(scheduledSQLConfiguration);
JobSchedule jobSchedule = new JobSchedule();
jobSchedule.setType(JobScheduleType.FIXED_RATE);
jobSchedule.setInterval("1m");
jobSchedule.setDelay(10);
jobSchedule.setRunImmediately(false);
scheduledSQLStructure.setSchedule(jobSchedule);
return scheduledSQLStructure;
}
public static void main(String[] args) {
Client client = new Client(endpoint, accessId, accessKey);
ScheduledSQL scheduledSQL = generateScheduledSQL();
CreateScheduledSQLRequest request = new CreateScheduledSQLRequest(sourceProject, scheduledSQL);
try {
client.createScheduledSQL(request);
} catch (LogException e) {
e.printStackTrace();
}
}
}
更多資訊,請參見Aliyun Log Java SDK。
ScheduledSQL
調用createScheduledSQL介面建立定時SQL任務。各個參數說明如下表所示。
參數名稱
樣本
說明
name
export-123-456
任務名稱。在Log Service控制台,單擊某定時SQL任務,即可查看該任務名。
displayName
my-scheduled-sql-job
定時SQL任務的顯示名稱。在Log Service控制台,選擇
,可以查看定時SQL顯示名稱列表。description
this is a scheduled sql job.
定時SQL任務描述。
configuration
scheduledSQLConfiguration
ScheduledSQL任務的配置任務資訊。具體配置,請參見ScheduledSQLConfiguration。
schedule
jobSchedule
ScheduledSQL任務的調度任務。具體配置,請參見JobSchedule。
JobSchedule
調用
JobSchedule jobSchedule = new JobSchedule();
建立定時SQL任務的調度任務。各個參數說明如下表所示。參數名稱
樣本
說明
type
FixedRate
調度定時SQL任務的頻率,每調度一次定時SQL任務產生一個執行執行個體。調度間隔決定每個執行執行個體的調度時間。
FixedRate:按照固定間隔調度定時SQL任務。固定間隔由interval參數指定。
Hourly:每小時調度一次定時SQL任務。
Daily:在每天的某個固定時間點調度一次定時SQL任務。
Cron:通過Cron運算式指定時間間隔,按照指定的時間間隔調度定時SQL任務。
interval
50m
當type取值為FixedRate時,配置固定間隔。
3s:間隔3秒。
5m:間隔5分鐘。
2h:間隔2小時。
cronExpression
無
當type取值為Cron時,配置Cron運算式。
Cron運算式的最小精度為分鐘,24小時制,例如
0 0/1 * * *
表示從00:00開始,每隔1小時運行一次。當您需要配置時區時,需選擇Cron模式。常見的時區列表請參見時區列表。
delay
10s
調度時間點往後順延強制的時間。取整範圍:0~120,單位:秒。
當資料寫入Logstore存在延遲等情況時,可通過順延強制來保證資料的完整性。
ScheduledSQLConfiguration
調用
ScheduledSQLConfiguration scheduledSQLConfiguration = generateConfig();
建立定時SQL任務的配置任務資訊。各個參數說明如下表所示。參數名稱
樣本
說明
script
*|select count(1)
輸入的查詢和分析語句。
sqlType
searchQuery
SQL類型,固定取值為searchQuery。
resourcePool
enhanced
資源集區類型,固定取值為enhanced。Log Service提供增強型資源集區用於資料分析。
roleArn
acs:ram::11111111:role/aliyunlogetlrole
讀取源Logstore資料的RAM角色標識。如何擷取ARN,請參見步驟一:授予RAM角色分析源Logstore的許可權。
destRoleArn
acs:ram::11111111:role/aliyunlogetlrole
寫入目標Logstore資料的RAM角色標識。如何擷取ARN,請參見如下說明:
如果源Logstore和目標Logstore屬於同一阿里雲帳號,請參見步驟二:授予RAM角色寫目標Logstore的許可權。
如果源Logstore和目標Logstore屬於不同的阿里雲帳號,請參見步驟二:授予帳號B下的RAM角色b寫目標Logstore的許可權。
sourceLogstore
source-logstore
源Logstore名稱。
destEndpoint
http://cn-hangzhou-intranet.log.aliyuncs.com
待寫入Logstore對應的服務入口。
說明阿里雲產品內部相互連信。例如同地區ECS訪問Log Service,建議優先使用私網網域名稱。其私網網域名稱為
http://cn-hangzhou-intranet.log.aliyuncs.com
。通過公網(互連網)訪問Log Service。例如通過本地公網的API、SDK訪問Log Service,建議優先使用公網網域名稱。其公網網域名稱為
http://cn-hangzhou.log.aliyuncs.com
。相比私網網域名稱的計費,公網網域名稱收費增加了外網讀流量。更多資訊,請參見Log Service計費項目。
更多資訊,請參見服務入口。
destProject
my-project
待寫入資料的目標Project名稱。
destLogstore
my-logstore
待寫入資料的目標Logstore名稱。
dataFormat
log2log
寫入模式。
log2log:日誌庫匯入日誌庫,即表示源Logstore中的資料通過定時SQL處理後將儲存到目標Logstore中。
log2metric:日誌庫匯入時序庫,即表示源Logstore中的資料通過定時SQL處理後將儲存到目標MetricStore中。
metric2metric:時序庫匯入時序庫,即表示源MetricStore中的資料通過定時SQL處理後將儲存到目標MetricStore中。
fromTimeExpr
@m - 12s
SQL時間視窗開始運算式。更多資訊,請參見時間運算式文法。
toTimeExpr
@m
SQL時間視窗結束運算式。更多資訊,請參見時間運算式文法。
maxRetries
10
執行SQL分析操作失敗時自動重試的閾值。當重試次數超過最大次數時,該執行執行個體結束,狀態為失敗。
maxRunTimeInSeconds
60
執行SQL分析操作失敗時自動重試的閾值。當重試時間超過指定的最大時間時,該執行執行個體結束,狀態為失敗。
fromTime
1653965045
調度開始時間。
重要執行個體的調度時間必須在該範圍內,超出該範圍時,定時SQL任務不再產生新執行個體。
toTime
1653968045
調度結束時間,0表示不結束。
params
無
當dataFormat取值為log2metric或metric2metric時,配置SQL配置參數。具體配置項請參見Log2MetricParameters和Metric2MetricParameters。
建立從Logstore到MetricStore的定時SQL任務時,還需要配置以下額外的參數:
表 1. Log2MetricParameters
參數名稱
樣本
說明
metricKeys
"[\"a\", \"b\", \"c\"]"
指標列,對應控制台介面SQL配置的指標列。
Log Service會根據您輸入的查詢和分析語句彙總資料,您可以選取查詢和分析結果中列值為數實值型別的一列或多列作為指標列。更多資訊,請參見時序資料(Metric)。
labelKeys
"[\"d\", \"e\", \"f\"]"
標籤列,對應控制台介面SQL配置的Labels。
Log Service會根據您輸入的查詢和分析語句彙總資料,您可以選取查詢和分析結果中的一列或多列作為Label資料。更多資訊,請參見時序資料(Metric)。
hashLabels
"[\"d\", \"f\"]"
對應控制台介面SQL配置的Rehash。
開啟Rehash開關後,您可以配置雜湊列,用於將同一列值的資料寫入到一個Shard中,增強資料局部性,提升查詢效率。
雜湊列的取值取決於查詢和分析結果。您可以選取查詢和分析結果中的一列或多列作為雜湊列。例如您配置雜湊列為status,則status欄位值相同的資料將被寫入到同一個Shard中。
addLabels
"[\"m\":\"h\", \"n\":\"i\"]"
對應控制台介面SQL配置的附加Labels。
添加靜態標籤,索引值對形式,可用於標識指標的相關屬性。
例如配置label_key為app,配置label_value為ingress-nginx。
timeKey
time
對應控制台介面SQL配置的時間列。
如果您選取查詢和分析結果中的時間列(列值為Unixtime時間戳記,例如
atime:1627025331
),則系統將以該時間列作為時序資料的時間。如果您選擇空,則系統將以查詢和分析時間範圍中的開始時間作為時序資料的時間。
建立從MetricStore到MetricStore的定時SQL任務時,還需要配置以下額外的參數:
表 2. Metric2MetricParameters
參數名稱
樣本
說明
metricName
my-metric
如果您要修改您所分析的指標名,您可以輸入修改後的指標名。更多資訊,請參見時序資料(Metric)。
重要建議分析的對象為單個指標時,修改指標名,實現重新命名。
如果分析對象為多個指標,則修改指標名後,會將所有的指標名修改為同一個相同的指標名。
hashLabels
"{\"m\":\"h\", \"n\":\"i\"}"
對應控制台介面SQL配置的Rehash。
開啟Rehash開關後,您可以配置雜湊列,用於將同一Label值的資料寫入到一個Shard中,增強資料局部性,提升查詢效率。
雜湊列的取值取決於時序資料已有的Label資訊。例如時序資料已有的Label資訊為
{"alert_id":"alert-1608815762-545495","alert_name":"警示恢複關閉","status":"inactive"}
,則雜湊列的可選值為alert_id、alert_name、status。如果您配置雜湊列為status,則status欄位值相同的資料將被寫入到同一個Shard中。addLabels
"{\"m\":\"h\", \"n\":\"i\"}"
對應控制台介面SQL配置的附加Labels。
添加靜態標籤,索引值對形式,可用於標識指標的相關屬性。
例如配置label_key為app,配置label_value為ingress-nginx。