alibabacloud-sls-query

Alibaba Cloud SLS クエリと分析

シナリオの説明

ユーザーが次のことを希望する場合に、このスキルを使用します。

• 既存のクエリを説明、書き換え、最適化、または実行する
• 自然言語の要件を SLS の インデックスクエリ、SQL、または SPL 文に変換する

---

前提条件

Aliyun CLI のインストール

aliyun version を実行し、バージョンが 3.3.8 以上であることを確認します。未インストールの場合、またはバージョンが古い場合は、references/cli-installation-guide.md のドキュメントに従ってインストールまたは更新します。

プラグインの更新

aliyun plugin update

Alibaba Cloud の認証情報が設定されていることを確認

aliyun configure list を実行して、認証情報が設定されているか確認します。 有効なプロファイルが表示されない場合は、ここで必ず処理を停止し、このセッション外で aliyun configure を実行するようユーザーに依頼します。

セキュリティルール：

• AK/SK の値を読み取ったり、表示したり、出力したりすることは絶対にしないでください
• 会話に AK/SK を貼り付けるようユーザーに求めることは絶対にしないでください
• 認証情報の状態確認には aliyun configure list のみを使用してください

---

RAM 権限の要件

API	CLI	アクション	目的
GetLogsV2	get-logs-v2	log:GetLogStoreLogs	クエリ／SQL／SPL を実行し、結果を読み取る
GetIndex	get-index	log:GetIndex	前提条件を確認するためにインデックス設定を読み取る

最小限および完全な RAM ポリシー JSON については、references/ram-policies.md を参照してください。

権限エラーへの対応： 呼び出しで Unauthorized 権限エラーが返された場合は、処理を停止し、references/ram-policies.md をユーザーに提示してください。ユーザーの明示的な確認なしに、別のアカウントで再試行してはいけません。

---

オブザーバビリティ（すべての aliyun API コマンドで必ず従うこと）

このスキルの読み込み時に、セッション全体で使用するランダムなセッション ID（32 文字の小文字の 16 進文字列）を一度だけ生成します。以下では {session-id} として使用します。

ルール： クラウド API を呼び出す aliyun CLI コマンドには、すべて --user-agent フラグを必ず含めてください。ローカルユーティリティコマンド（例：configure、plugin、version）はこのフラグに対応していないため、対象外です。

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sls-query/{session-id}"

例（session-id が a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 の場合）：

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 --query '*' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sls-query/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

aliyun API コマンドの呼び出しで、--user-agent を省略したり、形式を変更したり、付け忘れたりしないでください。

---

基本的なワークフロー

1. インデックス設定を読み取る（GetIndex）
2. クエリモードを選択する
3. 文を作成する
4. 時間範囲を解決する
5. クエリを実行する
6. レスポンスからデータを抽出する
7. CLI コマンドと結果を提示する

ステップ 1：インデックス設定を読み取る（必須）

必ず最初に get-index を呼び出してください。インデックス設定により、ステップ 2 で使用できるクエリモードが決まります。

aliyun sls get-index \
  --project <project> --logstore <logstore>

レスポンスの 2 つのセクションが、その後のすべての判断に影響します。

セクション	意味
line	全文インデックス — 存在しない場合、全文検索は無効です
keys	フィールドインデックス — フィールドから { type, doc_value, token, caseSensitive, chn, ... } へのマップです。doc_value: true は、そのフィールドで統計が有効であることを意味します

呼び出しで IndexConfigNotExist（HTTP 404）が返された場合、またはレスポンスで line と keys のどちらにも値が設定されていない場合、Logstore にインデックスがありません。直ちに処理を停止し、クエリ／SQL／SPL を実行する前にインデックスを作成する必要があることをユーザーに伝えてください。

• レスポンスが大きい場合があります — 現在のクエリに関連するフィールドのみを抽出してください。logstore ごとにキャッシュし、セッション内で再利用してください。

フィールド型、トークン化、get-index と機能の対応については、references/related-apis.md と references/query-analysis.md を参照してください。

---

ステップ 2：クエリモードを選択する（重要）

クエリ文は、次のいずれかの形式を取ります。

優先度	モード	文の形式	使用する場合	必要条件
1	インデックス検索	<index-search>	生ログをフィルタリングし、時間順に並べてページ分割したログを返す場合	全文（line）または任意のフィールドインデックス（keys.<field>）
2	SQL	<index-search> | <SQL>	集計、GROUP BY、並べ替え、ウィンドウ、トップ N、射影、その他の分析処理	対象フィールドに doc_value: true の keys.<field> があること
3	SQL スキャン	<index-search> | <SQL scan>	ユーザーから指定された場合	なし
4	SPL	<index-search> | <SPL>	ユーザーから指定された場合	なし

選択ルール：

• 最速であるため、常にインデックス検索を優先します。
• 集計、GROUP BY、並べ替え、ウィンドウ分析、トップ N、必要なフィールド／列のみの返却など、ユーザーが生ログ全体の取得ではなく分析処理やフィールドの射影を必要とする場合は、インデックス検索 + SQLを使用します。
• SQL スキャンやSPLを積極的に選択しないでください。ユーザーが明示的に要求した場合のみ使用します。

詳しい選択ガイドについては、references/query-analysis.mdを参照してください。

---

ステップ 3：文を作成する

3.1 まずインデックス検索部分（| の左側）を作成する

インデックス検索構文で表現できるフィルターをすべて集め、最初の | より前に配置します。フィルターが適用されない場合は * を使用します。

* and "payment failed" and status: "500" and not path: "/healthz"

• * はすべてに一致します。"..." は全文検索です（全文インデックスが必要です）。
• key: "value" はフィールドフィルターです（フィールドインデックスが必要です）。
• and／or／not で組み合わせ、かっこでグループ化します。
• key: * はフィールドが存在することを意味します。範囲（>、>=、[a, b]）は long／double でのみ機能します。

集計や行単位の処理なしで要件に完全に回答できる場合は、ここで終了します。これだけで完全なインデックス検索になります。インデックス検索構文の詳細については、references/query-analysis.mdを参照してください。

3.2 SQL を追加する — 集計／分析の場合

status: 500 | SELECT date_trunc('minute', __time__) AS minute,
                    count(*) AS errors
              FROM log
              GROUP BY minute
              ORDER BY minute

• クエリと SQL のルールについては、references/query-analysis.mdを参照してください。
• テーブル名は log です（省略することを推奨します）。
• SQL では get-index のインデックスフィールド型が適用されます。long／double フィールドは直接比較できます（status >= 500）。フィールドが text としてインデックス化されているものの、数値として扱う必要がある場合にのみキャストしてください（エラーを抑制するには try_cast を使用します）。
• 特殊な関数（集計、JSON、正規表現、日時、IP ジオロケーションなど）の選択については、references/functions-guide.mdを参照してください。

3.3 SPL を追加する — 行単位の処理／柔軟なフィルタリングの場合

status: 500 and service: payment
| where try_cast(latency as BIGINT) > 1000
| extend latency_ms = try_cast(latency as BIGINT)
| project service, latency_ms, message

SPL 構文、パイプラインコマンド、フィールドの処理ルールについては、references/spl-guide.mdを参照してください。

3.4 SQL スキャンを追加する — 対象フィールドにインデックス／統計情報がない場合の代替手段

構文は通常の SQL に従います（3.2 を参照）。ただし、すべてのフィールドは varchar であるため、数値の比較や演算の前に必ず cast()／try_cast() を使用してください。スキャンの動作については、references/query-analysis.mdを参照してください。

* | set session mode=scan; SELECT api, count(1) AS pv FROM log GROUP BY api

---

ステップ 4：時間範囲を解決する

CLI コマンドを組み立てる前に、--from / --to を秒単位の Unix タイムスタンプとして生成します。--from は範囲に含まれ、--to は範囲に含まれません。

次の 3 つの入力パターンから選びます。

1. 相対時間 — ユーザーが「最近／過去 N 分・時間・日」と指定する場合。
2. タイムゾーンの指定がない自然言語による絶対時刻 — YYYY-MM-DD HH:MM:SS に正規化してから、マシンのローカルタイムゾーンを使って解析します。
3. タイムゾーンが明示された絶対時刻 — 顧客が指定したタイムゾーンまたは UTC オフセットを使って解析します。

1. 相対時間

# recent 15 minutes
FROM=$(($(date +%s) - 900))
TO=$(date +%s)

2. タイムゾーンの指定がない自然言語による絶対時刻

ユーザーが日付／時刻を指定し、タイムゾーンを指定していない場合は、マシンのローカルタイムゾーンを使います。まず、2026年3月13日12点 のような自然言語を 2026-03-13 12:00:00 に正規化してから、ローカル時刻として解析します。

# Example: 2026年3月13日12点 -> 2026-03-13 12:00:00

# Linux (GNU date): local timezone
FROM=$(date -d "2026-03-13 12:00:00" +%s)

# macOS (BSD date): local timezone
FROM=$(date -j -f "%Y-%m-%d %H:%M:%S" "2026-03-13 12:00:00" +%s)

「2026年3月13日12点から13点」のような時間範囲では、両端の時刻を同じ方法で計算します。特定の時点に関するリクエストの場合は、ユーザーの意図に基づいて実用的な時間範囲を推定します。意図が不明な場合は、実行前に範囲を確認してください。

3. タイムゾーンが明示された絶対時刻

ローカル日時を Unix タイムスタンプに変換するには、date -u で入力を UTC として解析し、タイムゾーンの UTC オフセットを秒単位で差し引きます。

式：unix_ts = date_utc_parse(input) − (UTC_offset_hours × 3600)

# Example: 2025-01-15 10:30:00 Beijing Time (UTC+8)
# Beijing is UTC+8, so subtract 8 × 3600 = 28800

# Linux (GNU date)
FROM=$(( $(date -u -d "2025-01-15 10:30:00" +%s) - 28800 ))

# macOS (BSD date)
FROM=$(( $(date -u -j -f "%Y-%m-%d %H:%M:%S" "2025-01-15 10:30:00" +%s) - 28800 ))

# Example: 2025-01-15 10:30:00 New York Time (UTC-5)
# New York is UTC-5, so subtract -5 × 3600 = subtract -18000 = add 18000

# Linux (GNU date)
FROM=$(( $(date -u -d "2025-01-15 10:30:00" +%s) + 18000 ))

# macOS (BSD date)
FROM=$(( $(date -u -j -f "%Y-%m-%d %H:%M:%S" "2025-01-15 10:30:00" +%s) + 18000 ))

一般的な UTC オフセット（差し引く値）：

タイムゾーン	UTC オフセット（時間）	差し引く秒数
北京（UTC+8）	+8	28800
東京（UTC+9）	+9	32400
ロンドン（UTC）	0	0
ニューヨーク（UTC-5）	-5	-18000

---

ステップ 5：get-logs-v2 で実行する

クエリの実行には aliyun sls get-logs-v2 を使います。aliyun help sls get-logs-v2 を実行して CLI パラメーターの使用方法を確認してください。API パラメーターの詳細な説明は references/related-apis.md を参照してください。

必須の CLI フラグ：

• --project：SLS プロジェクト名
• --logstore：プロジェクト内の Logstore 名
• --from：時間範囲の開始時刻。秒単位の Unix タイムスタンプ（範囲に含む）
• --to：時間範囲の終了時刻。秒単位の Unix タイムスタンプ（範囲に含めない）
• --query：ステップ 3 で組み立てたステートメント

ステートメントに | が含まれるかどうかによって、ページネーションの方法が異なります。

5.1 インデックス検索のみ — --offset / --line でページネーションする

aliyun sls get-logs-v2 \
  --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 \
  --query '* and "payment failed" and status: "500"' \
  --line 100 --offset 0 --reverse true

• ページネーション：--line はページサイズ（1–100、必須）、--offset は開始行（任意、デフォルトは 0）です。
• 並べ替え：--reverse true を指定すると新しい順に返され、デフォルトの false では古い順になります。

5.2 SQL を使用する場合 — ステートメント内の LIMIT でページネーションする

aliyun sls get-logs-v2 \
  --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 \
  --query 'status: "500" | SELECT request_uri, count(*) AS cnt FROM log GROUP BY request_uri ORDER BY cnt DESC LIMIT 20'

• SQL のデフォルトの結果上限は100 行です。結果をさらに取得する、またはページネーションするには：
  • LIMIT count — 上限を引き上げます（例：LIMIT 500 は最大 500 行を返します）
  • LIMIT offset, count — ページネーションします（例：21～40 行には LIMIT 20, 20、41～60 行には LIMIT 40, 20）。offset+count の最大値は 1000000 です。
  • LIMIT count OFFSET offset 構文は使用しないでください。サポートされていません。必ず LIMIT offset, count を使用してください。
• 並べ替え：ORDER BY <field> DESC/ASC を使って並べ替えます。

結果の完全性の確認： すべての応答に meta.progress が含まれます。値が Incomplete の場合は、Complete が返されるまで同じリクエストを再実行してください。

---

Step 6: レスポンスからデータを抽出する

get-logs-v2 は次の内容を返します。

{
  "meta": { "progress": "Complete", "count": 10, ... },
  "data": [ { "field1": "value1", ... }, ... ]
}

フィールド	意味
meta.progress	Complete または Incomplete（Step 5 を参照）
meta.count	返された行数
data	ログエントリまたは集計行の配列。__time__（Unix 秒、文字列）が含まれる場合があります

jq（推奨）または --cli-query（JMESPath）を使って、ユーザーが必要とするフィールドを抽出します。

抽出対象	jq	--cli-query（JMESPath）
データ行	| jq '.data'	--cli-query 'data'
進行状況	| jq '.meta.progress'	--cli-query 'meta.progress'
行数	| jq '.meta.count'	--cli-query 'meta.count'
特定のフィールド	| jq '.data[] | {LogStore, read_mb}'	--cli-query 'data[].{LogStore: LogStore, read_mb: read_mb}'

---

Step 7: CLI コマンドと結果を提示する

CLI コマンド — 常に、コピーしてすぐに実行できる完全な aliyun sls get-logs-v2 ... コマンドを表示します。AK/SK は伏せてください。クエリを実行していない場合（書き込み／説明のシナリオ）は、ユーザーが実行すべきコマンドを提示します。

結果 — クエリを実行した場合は、Step 6 を使って data を抽出し、ユーザーのリクエストに応じた形式（テーブル、リスト、概要など）で整形します。クエリモードを選択した理由を説明する文を1文添えます。

---

全般的なルール

• 最速で生ログを取得するには、常に Index 検索を優先し、分析やフィールドの投影には Index 検索と SQL を使用します。
• ユーザーが特定のフィールドだけを必要とする場合は、完全な生ログを取得するのではなく、SELECT を使ってフィールドを投影します。 これにより、ネットワークのオーバーヘッドが軽減されます。対象フィールドで doc_value: true が必要です（Step 1 で確認）。
• __time__ フィルターをハードコードしないでください。 時間範囲は --from／--to で渡します。
• 非推奨 API：get-logs は呼び出さず、常に get-logs-v2 を使用します。

---

トラブルシューティング

ユーザーから「データがない」「結果が正しくない」、または CLI エラーの報告があった場合は、次のチェックリストを記載された順序どおりに確認します。

1. 時間範囲 — --from／--to が間違っていませんか？ ミリ秒を秒として指定していませんか？ 書き込み直後で、まだインデックス作成中ではありませんか？
2. インデックス設定 — フィールドインデックスがありませんか？ 全文インデックスがオフになっていませんか？ 対象フィールドが keys に含まれていませんか？
3. フィールド型／統計情報 — text フィールドに範囲クエリを実行していませんか？ doc_value のないフィールドに SQL を実行していませんか？
4. 構文 — SQL と SPL が混在していませんか？ あいまい検索の先頭に * がありませんか？ SPL の文字列エスケープに問題はありませんか？
5. モードの選択 — インデックスベースのクエリで済むのにスキャンしていませんか？ SQL ではなく SPL で集計していませんか？
6. 完全性 — meta.progress = Incomplete なのに、呼び出し側で再試行していませんか（Step 5 を参照）。
7. ProjectNotExist — リージョンまたはエンドポイントが間違っています。リージョン横断検索を使ってプロジェクトを自動的に特定するか、ユーザーにリージョンの確認を依頼してください。get-project --cross-region true を呼び出す前に、必ず references/regions.md の Cross-Region Discovery セクションを読んでください — この API は cn-zhangjiakou.log.aliyuncs.com エンドポイント経由でのみ利用できます。
8. ネットワーク障害（タイムアウト、接続拒否）— 内部エンドポイントへの切り替えを試してください。references/regions.md を参照してください。

エラーの種類とエラーコードの全一覧については、references/troubleshooting.md と references/related-apis.md の Common Errors テーブルを参照してください。

---

参考ドキュメント

ドキュメント	説明
references/query-analysis.md	モードの決定、インデックス検索／SQL のルール、スキャンのセマンティクス
references/spl-guide.md	SPL パイプラインの構文、一般的なコマンド、フィールドの扱い
references/functions-guide.md	関数のカテゴリ、SQL／SPL の違い、テンプレート
references/troubleshooting.md	「データなし／結果が誤っている／エラー」の対処ガイド
references/related-apis.md	GetLogsV2 および GetIndex API と CLI のリファレンス
references/ram-policies.md	最小限および完全な RAM ポリシー
references/cli-installation-guide.md	Aliyun CLI のインストール、認証モード、プロファイル
references/regions.md	リージョン／エンドポイントの設定、内部エンドポイント、クロスリージョンの検出（get-project --cross-region true、cn-zhangjiakou のみ）
references/acceptance-criteria.md	CLI 呼び出しの受け入れテスト
references/query_analysis/*.yaml · references/spl/*.yaml · references/functions/*.yaml	このスキルに同梱されている信頼できる情報源となる YAML