このトピックでは、Simple Log Service SDK for Javaを使用してスケジュールされたSQLジョブを作成する方法とサンプルコードについて説明します。
前提条件
RAM (Resource Access Management) ユーザーが作成され、必要な権限がRAMユーザーに付与されます。 詳細については、「RAMユーザーの作成とRAMユーザーへの権限付与」をご参照ください。
ALIBABA_CLOUD_ACCESS_KEY_IDおよびALIBABA_CLOUD_ACCESS_KEY_SECRET環境変数が設定されています。 詳細については、「Linux、macOS、およびWindowsでの環境変数の設定」をご参照ください。
重要Alibaba CloudアカウントのAccessKeyペアには、すべてのAPI操作に対する権限があります。 RAMユーザーのAccessKeyペアを使用して、API操作を呼び出したり、ルーチンのO&Mを実行したりすることを推奨します。
プロジェクトコードにAccessKey IDまたはAccessKey secretを保存しないことを推奨します。 そうしないと、AccessKeyペアが漏洩し、アカウント内のすべてのリソースのセキュリティが侵害される可能性があります。
Java V0.6.69以降のSimple Log Service SDKがインストールされています。 詳細については、「Simple Log Service SDK For Javaのインストール」をご参照ください。
背景情報
Simple Log Serviceは、スケジュールされたSQL機能を提供します。 この機能を使用して、定期的にデータを自動的に分析し、データを集計して保存できます。 この機能を使用して、データをプロジェクトおよびフィルタリングすることもできます。 Scheduled SQLは、SQL-92構文とSimple Log Serviceクエリステートメントの構文をサポートしています。 スケジュールされたSQLジョブは、スケジューリングルールに基づいて定期的に実行され、分析結果を宛先LogstoreまたはMetricstoreに書き込みます。
Simple Log Serviceコンソールには、スケジュールされたSQLジョブを作成するためのGUIがあります。 詳細については、「スケジュールされたSQLジョブの作成」をご参照ください。
Simple Log Serviceは、ScheduledSQL、JobSchedule、およびScheduledSQLConfigurationクラスを提供し、Simple Log Service SDK for Javaを使用してスケジュールされたSQLジョブを効率的に作成するのに役立ちます。
ScheduledSQL: このクラスを使用して、スケジュールされたSQLジョブを作成できます。
JobSchedule: このクラスを使用して、スケジュールされたSQLジョブのスケジュール設定を構成できます。
ScheduledSQLConfiguration: このクラスを使用して、スケジュールされたSQLジョブの基本設定を構成できます。
サンプルコード
この例では、ソースLogstoreからターゲットLogstoreに分析結果を保存するためにApp.javaファイルが作成されます。 例:
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 {
// In this example, the AccessKey ID and AccessKey secret are obtained from environment variables.
static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// Specify a project name and a Logstore name.
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";
// The Simple Log Service endpoint. In this example, the Simple Log Service endpoint for the China (Hangzhou) region is used. Replace the parameter value with the actual endpoint.
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();
}
}
}
詳細については、「Alibaba Cloud Simple Log Service SDK For Java」をご参照ください。
ScheduledSQL
createScheduledSQL操作を呼び出して、スケジュールされたSQLジョブを作成できます。 下表に、各パラメーターを説明します。
パラメーター
例
説明
name
export-123-456
スケジュールされたSQLジョブの名前。 Simple Log Serviceコンソールで、スケジュールされたSQLジョブをクリックして、ジョブの名前を表示できます。
displayName
my-scheduled-sql-job
スケジュールされたSQLジョブの表示名。 Simple Log Serviceコンソールで、
を選択して、スケジュールされたSQLジョブの表示名を表示できます。説明
これはスケジュールされたsqlジョブです。
スケジュールされたSQLジョブの説明。
設定
scheduledSQLConfiguration
スケジュールされたSQLジョブの基本設定。 詳細については、「ScheduledSQLConfiguration」をご参照ください。
スケジュール
jobSchedule
スケジュールされたSQLジョブのスケジューリング設定。 詳細については、「JobSchedule」をご参照ください。
JobSchedule
JobSchedule jobSchedule = new JobSchedule();
を呼び出して、スケジュールされたSQLジョブのスケジューリング設定を構成できます。 下表に、各パラメーターを説明します。パラメーター
例
説明
タイプ
FixedRate
スケジュールされたSQLジョブがスケジュールされる頻度。 インスタンスは、スケジュールされたSQLジョブがスケジュールされるたびに生成されます。 このパラメータは、各インスタンスのスケジュール時間を指定します。 有効な値:
FixedRate: スケジュールされたSQLジョブは、一定の間隔でスケジュールされる。 固定間隔は、intervalパラメーターで指定します。
時間: スケジュールされたSQLジョブは1時間ごとにスケジュールされます。
毎日: スケジュールされたSQLジョブは、毎日固定された時点でスケジュールされます。
Cron: スケジュールされたSQLジョブは、cron式で指定された間隔でスケジュールされます。
interval
50m
スケジュールされたSQLジョブがスケジュールされる固定間隔。 typeをFixedRateに設定した場合、このパラメーターを設定する必要があります。
3 s: 間隔は3秒です。
5 m: 間隔は5分です。
2 h: 間隔は2時間です。
cronExpression
なし
スケジュールされたSQLジョブのスケジュールに基づくcron式。 typeをCronに設定した場合、cron式を指定する必要があります。
cron式を使用する場合、指定された間隔は24時間クロックに基づいて分に正確になります。 たとえば、式
0 0/1 * * *
は、スケジュールされたSQLジョブが00:00から1時間ごとにスケジュールされることを示します。タイムゾーンを指定する場合は、[Cron] を選択します。 共通タイムゾーンの詳細については、「タイムゾーン」をご参照ください。
遅延
10s
インスタンスがスケジュールされた時刻から遅延した秒数。 設定可能な値は、0 から 100 です。 単位は秒です。
データが宛先Logstoreに書き込まれるときにレイテンシが存在する場合、このパラメーターを使用してデータの整合性を確保できます。
ScheduledSQLConfiguration
ScheduledSQLConfiguration scheduledSQLConfiguration = generateConfig();
を呼び出して、スケジュールされたSQLジョブの基本設定を構成できます。 下表に、各パラメーターを説明します。パラメーター
例
説明
スクリプト
* | セレクトカウント (1)
使用するクエリ文。
sqlType
searchQuery
SQL型。 値をsearchQueryに設定します。
resourcePool
高められた
リソースプールのタイプ。 値をenhancedに設定します。 データ分析に使用されるリソースプール。 Simple Log Serviceは、拡張タイプのリソースプールを提供します。
roleArn
acs:ram::11111111:role/aliyunlogetlrole
ソースLogstoreからデータを読み取るために使用されるRAMロールのAlibaba Cloud Resource Name (ARN) 。 ARNの取得方法については、「手順1: RAMロールにソースLogstoreのデータを分析する権限を付与する」をご参照ください。
destRoleArn
acs:ram::11111111:role/aliyunlogetlrole
宛先Logstoreにデータを書き込むために使用されるRAMロールのARN。 ARNの取得方法については、ビジネスシナリオに基づいて次のいずれかのトピックを参照してください。
ソースLogstoreとターゲットLogstoreが同じAlibaba Cloudアカウントに属している場合、「RAMロールにターゲットLogstoreへのデータ書き込み権限を付与」の手順に従ってARNを取得します。
ソースLogstoreとターゲットLogstoreが異なるAlibaba Cloudアカウントに属している場合、「RAMロールBにターゲットLogstoreへのデータ書き込み権限を付与」に記載されている手順に従ってARNを取得します。
sourceLogstore
ソース-logstore
ソースLogstoreの名前。
destEndpoint
http://cn-hangzhou-intranet.log.aliyuncs.com
宛先Logstoreのエンドポイント。
説明Simple Log Serviceは、内部ネットワークを介したAlibaba Cloudサービスとの通信をサポートします。 たとえば、Simple Log Serviceリソースと同じリージョンにあるElastic Compute Service (ECS) インスタンスからSimple Log Serviceリソースにアクセスする場合は、
http://cn-hangzhou-intranet.log.aliyuncs.com
の形式で内部エンドポイントを使用することを推奨します。Simple Log Serviceはインターネット経由のアクセスをサポートしています。 たとえば、インターネット経由でオンプレミスサーバーからAPIまたはSDKを使用してSimple Log Serviceリソースにアクセスする場合は、次の形式のパブリックエンドポイントを使用することを推奨し
http://cn-hangzhou.log.aliyuncs.com
。内部エンドポイントと比較して、パブリックエンドポイントは、もう1つの請求可能なアイテム、つまりインターネット上の読み取りトラフィックを伴います。 詳細については、「課金項目」をご参照ください。
詳細については、「エンドポイント」をご参照ください。
destProject
my-project
データが書き込まれる先のプロジェクトの名前。
destLogstore
my-logstore
データが書き込まれる宛先Logstoreの名前。
dataFormat
log2log
書き込みモードを設定します。 有効な値:
log2log: スケジュールされたSQLジョブは、ソースLogstore内のデータを処理し、処理されたデータを宛先Logstoreに格納します。
log2metric: Scheduled SQLジョブは、ソースLogstore内のデータを処理し、処理したデータを宛先Metricstoreに格納します。
metric2metric: Scheduled SQLジョブは、ソースMetricstoreのデータを処理し、処理したデータを宛先Metricstoreに格納します。
fromTimeExpr
@ m - 12s
SQLタイムウィンドウの開始時刻を指定するために使用される式。 詳細については、「Time expression構文」をご参照ください。
toTimeExpr
@ m
SQLタイムウィンドウの終了時刻を指定するために使用される式。 詳細については、「Time expression構文」をご参照ください。
maxRetries
10
SQL分析操作が失敗した場合の自動再試行のしきい値。 インスタンスの再試行回数が指定したしきい値を超えると、インスタンスは再試行を停止し、FAILED状態になります。
maxRunTimeInSeconds
60
SQL分析操作が失敗した場合の自動再試行のしきい値。 このパラメーターには、再試行に許可される最大時間を指定します。 インスタンスが指定された時間を超えて再試行している場合、インスタンスは再試行を停止し、FAILED状態になります。
fromTime
1653965045
スケジュールされたSQLジョブがスケジュールされる時間範囲の開始時刻。
重要スケジュールされたSQLジョブのインスタンスは、指定された時間範囲内でのみ実行できます。 時間範囲が終了すると、Scheduled SQLジョブはインスタンスを生成しなくなります。
toTime
1653968045
スケジュールされたSQLジョブがスケジュールされる時間範囲の終了時刻。 値0は、スケジュールされたSQLジョブに終了時刻が指定されていないことを示します。
params
なし
SQL設定。 dataFormatをlog2metricまたはmetric2metricに設定した場合、このパラメーターを設定する必要があります。 詳細については、「Log2MetricParameters」および「Metric2MetricParameters」をご参照ください。
ソースLogstore内のデータを処理し、処理されたデータを宛先Metricstoreに格納するスケジュール済みSQLジョブを作成する場合は、次のパラメーターも設定する必要があります。
表1 Log2MetricParameters
パラメーター
例
説明
metricKeys
"[\" a\", \" b\", \" c\"]"
メトリック列。 このパラメーターは、Simple Log ServiceコンソールのSQL Settingsパラメーターの下にあるMetric Columnパラメーターに対応します。
Simple Log Serviceは、入力したクエリステートメントに基づいてデータを集計します。 このパラメーターのクエリ結果で、数値データ型の1つ以上の列を選択できます。 詳細については、「メトリック」をご参照ください。
labelKeys
"[\" d\", \" e\", \" f\"]"
ラベル。 このパラメーターは、Simple Log ServiceコンソールのSQL Settingsパラメーターの下にあるLabelsパラメーターに対応します。
Simple Log Serviceは、入力したクエリステートメントに基づいてデータを集計します。 このパラメーターのクエリおよび分析結果で1つ以上の列を選択できます。 詳細については、「メトリック」をご参照ください。
hashLabels
"[\" d\", \" f\"]"
データをハッシュするかどうかを指定します。 このパラメーターは、Simple Log ServiceコンソールのSQL Settingsパラメーターの下にあるRehashパラメーターに対応します。
Rehashをオンにすると、Hash Columnパラメーターを設定して、列に同じ値を持つデータを同じシャードに書き込むことができます。 これにより、データの局所性とクエリの効率が向上します。
ハッシュ列パラメーターの有効な値は、クエリと分析の結果によって異なります。 クエリおよび分析結果の1つ以上の列をハッシュ列として選択できます。 たとえば、Hash Columnをstatusに設定した場合、statusに同じ値を持つデータは同じシャードに書き込まれます。
addLabels
"[\" m\":\" h\", \" n\":\" i\"]"
このパラメーターは、Simple Log ServiceコンソールのSQL Settingsパラメーターの下にあるAdditional Labelsパラメーターに対応します。
メトリックの属性を識別するために使用される静的ラベル。 各ラベルはキーと値のペアです。
たとえば、label_keyをappに、label_valueをingress-nginxに設定できます。
timeKey
time
時間列。 このパラメーターは、Simple Log ServiceコンソールのSQL Settingsパラメーターの下にあるTime Columnパラメーターに対応します。
このパラメーターのクエリおよび分析結果で、値がUNIX timestampである時間列を選択した場合、システムは時間列の値を使用してメトリックの時間を示します。 例:
atime:1627025331
パラメーターをNullに設定した場合、システムはクエリ文の開始時刻を使用してメトリックの時刻を示します。
ソースMetricstoreでデータを処理し、処理されたデータを宛先Metricstoreに格納するスケジュール済みSQLジョブを作成する場合は、次のパラメーターも設定する必要があります。
表2 Metric2MetricParameters
パラメーター
例
説明
metricName
my-metric
分析用に選択したメトリックの新しい名前。 メトリックの名前を変更する場合は、このパラメーターでメトリックの新しい名前を指定できます。 詳細については、「メトリック」をご参照ください。
重要分析用に単一のメトリックを選択した場合は、このパラメータを設定してメトリックの名前を変更することを推奨します。
分析に複数のメトリックを選択し、このパラメーターを設定すると、すべてのメトリックの名前が指定した名前に変更されます。
hashLabels
"{\" m\":\" h\", \" n\":\" i\"}"
データをハッシュするかどうかを指定します。 このパラメーターは、Simple Log ServiceコンソールのSQL Settingsパラメーターの下にあるRehashパラメーターに対応します。
Rehashをオンにすると、Hash Columnパラメーターを設定して、列に同じ値を持つデータを同じシャードに書き込むことができます。 これにより、データの局所性とクエリの効率が向上します。
ハッシュ列パラメーターの有効な値は、メトリクスの既存のラベル情報によって異なります。 たとえば、メトリックの既存のラベル情報が
{"alert_id":"alert-1608815762-545495" 、"alert_name":"Alert clearance disabled" 、"status":"inactive"}
の場合、Hash Columnパラメーターの有効な値はalert_id、alert_name、statusです。 ハッシュ列をstatusに設定した場合、statusの値が同じメトリックが同じシャードに書き込まれます。addLabels
"{\" m\":\" h\", \" n\":\" i\"}"
このパラメーターは、Simple Log ServiceコンソールのSQL Settingsパラメーターの下にあるAdditional Labelsパラメーターに対応します。
メトリックの属性を識別するために使用される静的ラベル。 各ラベルはキーと値のペアです。
たとえば、label_keyをappに、label_valueをingress-nginxに設定できます。