CreateScheduledSQL API を呼び出して、スケジュール SQL タスクを作成します。
前提条件
Simple Log Service がアクティブ化されていること。 詳細については、「Activate Simple Log Service」をご参照ください。
Simple Log Service SDK for Java が初期化されていること。 詳細については、「Initialize Simple Log Service SDK for Java」をご参照ください。
背景情報
Simple Log Service は、スケジュール SQL 機能を提供します。 この機能を使用すると、定期的にデータを自動的に分析し、保存のためにデータを集計できます。 また、データの投影とフィルタリングにも使用できます。 スケジュール SQL は、SQL-92 構文と Simple Log Service クエリ文の構文をサポートしています。 スケジュール SQL ジョブは、スケジューリングルールに基づいて定期的に実行され、結果を宛先のログストアまたはメトリックストアに書き込みます。
Simple Log Service コンソールは、スケジュール SQL ジョブを作成するための GUI を提供します。 詳細については、「スケジュール SQL ジョブの作成」をご参照ください。
Simple Log Service は、Simple Log Service SDK for Java を使用してスケジュール SQL ジョブを効率的に作成するのに役立つ ScheduledSQL、JobSchedule、および ScheduledSQLConfiguration クラスを提供します。
ScheduledSQL: このクラスを使用して、スケジュール SQL ジョブを作成できます。
JobSchedule: このクラスを使用して、スケジュール SQL ジョブのスケジューリング設定を構成できます。
ScheduledSQLConfiguration: このクラスを使用して、スケジュール SQL ジョブの基本設定を構成できます。
パラメーター
リクエストパラメーター
名前 | 型 | 必須 | 説明 | 例 |
project | String | はい | プロジェクトの名前。 | ali-test-project |
scheduledSql | Object | はい | スケジュール SQL ジョブの構成。 | - |
ScheduledSQL
次の表にパラメーターを示します。
パラメーター | 型 | 必須 | 説明 | 例 |
name | String | はい | スケジュール SQL ジョブの名前。 命名規則は次のとおりです。
| export-123-456 |
displayName | String | はい | スケジュール SQL ジョブの表示名。 Simple Log Service コンソールで、 を選択して、スケジュール SQL ジョブの表示名の一覧を表示します。 | my-scheduled-sql-job |
description | String | いいえ | スケジュール SQL ジョブの説明。 | this is a scheduled sql job. |
configuration | Object | はい | スケジュール SQL ジョブの構成情報。 | - |
schedule | Object | はい | スケジューリングプロパティを構成します。 | - |
JobSchedule
JobSchedule jobSchedule = new JobSchedule();
を呼び出して、スケジュール SQL ジョブのスケジューリングタスクを作成します。 次の表にパラメーターを示します。
パラメーター | 型 | 必須 | 説明 | 例 |
type | String | はい | スケジュール SQL ジョブがスケジュールされる頻度。 スケジュール SQL ジョブがスケジュールされるたびにインスタンスが生成されます。 このパラメーターは、各インスタンスのスケジュールされた時間を決定します。 有効値:
| FixedRate |
interval | String | いいえ | type が FixedRate に設定されている場合は、一定の間隔を構成します。
| 50m |
cronExpression | String | いいえ | type が Cron に設定されている場合は、Cron 式を構成します。 Cron 式の最小精度は、24 時間形式の分です。 たとえば、 タイムゾーンを構成する必要がある場合は、[Cron] モードを選択します。 一般的なタイムゾーンの一覧については、「タイムゾーンリスト」をご参照ください。 | なし |
delay | int | いいえ | インスタンスがスケジュールされた時間から遅延される秒数。 有効値: 0 ~ 120。 単位: 秒。 データが宛先ログストアに書き込まれるときにレイテンシが存在する場合は、このパラメーターを使用してデータの整合性を確保できます。 | 10s |
ScheduledSQLConfiguration
ScheduledSQLConfiguration scheduledSQLConfiguration = generateConfig();
を呼び出して、スケジュール SQL ジョブの構成情報タスクを作成します。 次の表にパラメーターを示します。
パラメーター | 型 | 必須 | 説明 | 例 |
script | String | はい | 使用するクエリ文。 | *|select count(1) |
sqlType | String | はい | SQL の型。 値を searchQuery に設定します。 | searchQuery |
resourcePool | String | はい | リソースプールの種類。 値を enhanced に設定します。 Simple Log Service は、データ分析用に拡張型のリソースプールを提供します。 | enhanced |
roleArn | String | はい | ソースログストアからデータを読み取るために使用される RAM ロールの Alibaba Cloud リソースネーム (ARN)。 ARN の取得方法については、「カスタム RAM ロールにソースログストアを分析する権限を付与する」をご参照ください。 |
|
destRoleArn | String | はい | 宛先ログストアにデータを書き込むために使用される RAM ロールの ARN。 ARN の取得方法については、ビジネスシナリオに基づいて次のいずれかのトピックを参照してください。
|
|
sourceLogstore | String | はい | ソースログストアの名前。 | source-logstore |
destEndpoint | String | はい | 宛先ログストアのエンドポイント。 説明
詳細については、「エンドポイント」をご参照ください。 |
|
destProject | String | はい | データの書き込み先のプロジェクトの名前。 | my-project |
destLogstore | String | はい | データの書き込み先の宛先ログストアの名前。 | my-logstore |
dataFormat | String | はい | 書き込みモード。
| log2log |
fromTimeExpr | String | はい | SQL タイムウィンドウの開始時刻を指定するために使用される式。 詳細については、「時間式の構文」をご参照ください。 | @m - 12s |
toTimeExpr | String | はい | SQL タイムウィンドウの終了時刻を指定するために使用される式。 詳細については、「時間式の構文」をご参照ください。 | @m |
maxRetries | Long | はい | SQL 分析操作が失敗した場合の自動再試行のしきい値。 インスタンスの再試行回数が指定したしきい値を超えると、インスタンスは再試行を停止し、FAILED 状態になります。 | 10 |
maxRunTimeInSeconds | Long | はい | SQL 分析操作が失敗した場合の自動再試行のしきい値。 このパラメーターは、再試行に許可される最大時間を指定します。 インスタンスが指定された時間を超えて再試行している場合、インスタンスは再試行を停止し、FAILED 状態になります。 | 60 |
fromTime | Long | はい | スケジュール SQL ジョブがスケジュールされる時間範囲の開始時刻。 重要 時間範囲を指定した場合、スケジュール SQL ジョブのインスタンスは、指定された時間範囲内でのみ実行できます。 終了時刻の後、スケジュール SQL ジョブはインスタンスを生成しなくなります。 | 1653965045 |
toTime | Long | はい | スケジュール SQL ジョブがスケジュールされる時間範囲の終了時刻。 値 0 は、スケジュール SQL ジョブに終了時刻が指定されていないことを示します。 | 1653968045 |
parameters | Object | はい | dataFormat が log2metric または metric2metric に設定されている場合は、SQL 構成パラメーターを構成します。 特定の構成項目については、 Log2MetricParameters および Metric2MetricParameters を参照してください。 |
|
parameters
ログストアからメトリックストアへのスケジュール SQL ジョブを構成する場合、次の追加パラメーターを構成する必要があります。
表 1. Log2MetricParameters
パラメーター
例
説明
metricKeys
"[\"a\", \"b\", \"c\"]"
メトリック列。 このパラメーターは、Simple Log Service コンソールの [SQL 設定] パラメーターの下にある [メトリック列] パラメーターに対応しています。
Simple Log Service は、入力したクエリ文に基づいてデータを集計します。 このパラメーターには、クエリおよび分析結果の数値データ型の 1 つ以上の列を選択できます。 詳細については、「時系列データ (メトリック)」をご参照ください。
labelKeys
"[\"d\", \"e\", \"f\"]"
ラベル。 このパラメーターは、Simple Log Service コンソールの [SQL 設定] パラメーターの下にある [ラベル] パラメーターに対応しています。
Simple Log Service は、入力したクエリ文に基づいてデータを集計します。 このパラメーターには、クエリおよび分析結果の 1 つ以上の列を選択できます。 詳細については、「時系列データ (メトリック)」をご参照ください。
hashLabels
"[\"d\", \"f\"]"
データをハッシュするかどうかを指定します。 このパラメーターは、Simple Log Service コンソールの [SQL 設定] パラメーターの下にある [再ハッシュ] パラメーターに対応しています。
[再ハッシュ] スイッチをオンにすると、[ハッシュ列] を構成して、同じ列値を持つデータを同じシャードに書き込むことができます。 これにより、データの局所性が向上し、クエリの効率が向上します。
[ハッシュ列] の値は、クエリと分析の結果によって異なります。 クエリおよび分析結果の 1 つ以上の列をハッシュ列として選択できます。 たとえば、[ハッシュ列] を status に設定すると、同じ status フィールド値を持つデータが同じシャードに書き込まれます。
addLabels
"[\"m\":\"h\", \"n\":\"i\"]"
このパラメーターは、Simple Log Service コンソールの [SQL 設定] パラメーターの下にある [追加ラベル] パラメーターに対応しています。
メトリックの属性を識別するために使用される静的タグ。 各タグはキーと値のペアです。
たとえば、label_key を app に設定し、label_value を ingress-nginx に設定します。
timeKey
time
時間列。 このパラメーターは、Simple Log Service コンソールの [SQL 設定] パラメーターの下にある [時間列] パラメーターに対応しています。
クエリおよび分析結果から時間列を選択した場合 (列値は Unix タイムスタンプ、例:
atime:1627025331
)、システムはこの時間列を時系列データの時間として使用します。[空] を選択すると、システムはクエリおよび分析の時間範囲の開始時刻を時系列データの時間として使用します。
メトリックストアからメトリックストアへのスケジュール SQL ジョブを構成する場合、次の追加パラメーターを構成する必要があります。
表 2. Metric2MetricParameters
パラメーター
例
説明
metricName
my-metric
分析用に選択したメトリックの新しい名前。 メトリックの名前を変更する場合は、このパラメーターでメトリックの新しい名前を指定できます。 詳細については、「時系列データ (メトリック)」をご参照ください。
重要メトリックが 1 つだけ存在する場合は、このパラメーターを指定することをお勧めします。
複数のメトリックが存在し、このパラメーターを指定した場合、すべてのメトリック名が指定されたメトリック名に変更されます。
hashLabels
"{\"m\":\"h\", \"n\":\"i\"}"
データをハッシュするかどうかを指定します。 このパラメーターは、Simple Log Service コンソールの [SQL 設定] パラメーターの下にある [再ハッシュ] パラメーターに対応しています。
[再ハッシュ] スイッチをオンにすると、[ハッシュ列] を構成して、同じラベル値を持つデータを同じシャードに書き込むことができます。 これにより、データの局所性が向上し、クエリの効率が向上します。
[ハッシュ列] の値は、時系列データの既存のラベル情報によって異なります。 たとえば、時系列データの既存のラベル情報が
{"alert_id":"alert-1608815762-545495","alert_name":"alert recovery shutdown","status":"inactive"}
の場合、[ハッシュ列] のオプション値は alert_id、alert_name、および status です。 [ハッシュ列] を status に設定すると、同じ status フィールド値を持つデータが同じシャードに書き込まれます。addLabels
"{\"m\":\"h\", \"n\":\"i\"}"
このパラメーターは、Simple Log Service コンソールの [SQL 設定] パラメーターの下にある [追加ラベル] パラメーターに対応しています。
メトリックの属性を識別するために使用される静的タグ。 各タグはキーと値のペアです。
たとえば、label_key を app に設定し、label_value を ingress-nginx に設定します。
サンプルコード
この例では、ソースログストアから宛先ログストアへの分析結果を保存するために、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 {
// 環境変数から AccessKey ID と AccessKey シークレットを取得します。
static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// プロジェクト名とログストア名を指定します。
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";
// Simple Log Service エンドポイント。 この例では、中国 (杭州) リージョンの Simple 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();
}
}
}
関連情報
スケジュール SQL ジョブの管理に使用される API については、次のトピックを参照してください。
サンプルコードの詳細については、GitHub の Alibaba Cloud Simple Log Service SDK for Java を参照してください。