ClickStack のアラート

ClickStack のアラート

ClickStack にはアラート機能が標準で備わっており、チームはログ、メトリクス、トレース全体にわたって問題をリアルタイムで検知し、対応できます。

アラートは HyperDX インターフェイスから直接作成でき、Slack や PagerDuty などの一般的な通知システムと連携できます。

アラート機能は ClickStack 上のデータ全体でシームレスに機能し、システムヘルスの追跡、パフォーマンス低下の検出、重要なビジネスイベントの監視に役立ちます。

​

アラートの種類

ClickStack では、アラートを作成する方法として、互いを補完する 2 つの方式 検索アラート と ダッシュボードチャートアラート をサポートしています。アラートを作成すると、そのアラートは検索またはチャートのいずれかに紐付けられます。

​

1. 検索アラート

検索アラートでは、保存済みの検索結果に基づいて通知をトリガーできます。これにより、特定のイベントやパターンの発生頻度が想定より高い場合や低い場合を検知できます。

定義した時間枠内で一致した結果の件数が、指定したしきい値を上回るか下回ると、アラートがトリガーされます。

検索アラートを作成するには:

検索に対してアラートを作成するには、その検索が保存されている必要があります。既存の保存済み検索に対してアラートを作成することも、アラートの作成中に検索を保存することもできます。以下の例では、検索はまだ保存されていないものとします。

1. ​

   アラート作成ダイアログを開く

   まず検索を実行し、Searchページ右上のAlertsボタンをクリックします。

2. ​

   アラートを作成する

   アラート作成パネルでは、次の操作を行えます。

   • アラートに関連付ける保存済み検索に名前を付ける。
   • しきい値を設定し、指定した期間内に何回到達したらアラートとするかを指定する。しきい値は上限または下限として使用することもできます。ここで設定する期間は、アラートがトリガーされる頻度も決定します。
   • grouped by の値を指定する。これにより、検索を ServiceName などで集計できるようになり、同じ検索から複数のアラートをトリガーできます。
   • 通知先の webhook 宛先を選択する。この画面から直接新しい webhook を追加することもできます。詳しくはwebhook の追加を参照してください。

   保存する前に、ClickStack はしきい値条件を可視化するため、想定どおりに動作するか確認できます。

なお、1 つの検索に複数のアラートを追加できます。上記の手順を繰り返すと、現在のアラートがアラート編集ダイアログ上部にタブとして表示され、各アラートには番号が割り当てられます。

​

2. ダッシュボードチャートアラート

ダッシュボードアラートは、チャートに対しても設定できます。

完全なSQL集計とClickHouse関数による高度な計算を活用し、保存済みのダッシュボードからチャートベースのアラートを直接作成できます。

メトリクスが設定したしきい値を超えると、アラートが自動的にトリガーされるため、KPI、レイテンシ、その他の主要なメトリクスを継続的に監視できます。

ダッシュボード上の可視化に対してアラートを作成するには、ダッシュボードが保存済みである必要があります。

ダッシュボードアラートを追加するには、次の手順に従います。

アラートは、チャートの作成時、ダッシュボードへのチャート追加時、または既存のチャートに追加して作成できます。以下の例では、チャートがすでにダッシュボード上に存在しているものとします。

1. ​

   チャート編集ダイアログを開く

   チャートの設定メニューを開き、アラートボタンを選択します。チャート編集ダイアログが表示されます。

2. ​

   アラートを追加する

   Add Alert を選択します。

3. ​

   アラート条件を定義する

   条件 (>=, >, <=, <, =, !=, <= x >=, > or <) 、しきい値、期間、webhook を定義します。ここで設定する期間は、アラートがトリガーされる頻度も決定します。

   この画面から新しい webhook を直接追加することもできます。詳しくは webhook の追加 を参照してください。

​

webhook の追加

alert の作成時には、既存の webhook を使用することも、新しく作成することもできます。作成した webhook は、ほかの alert でも再利用できます。

webhook は、Slack や PagerDuty などのさまざまなサービス種別に対して作成できるほか、汎用的なターゲット向けにも作成できます。

たとえば、以下の chart に対する alert の作成を考えてみましょう。webhook を指定する前に、ユーザーは Add New Webhook を選択できます。

これにより webhook 作成ダイアログが開き、新しい webhook を作成できます。

webhook 名は必須で、説明は任意です。そのほかに必要な設定項目は、サービス種別によって異なります。

利用できるサービス種別は、ClickStack Open Source と ClickStack Cloud とで異なる点に注意してください。詳細はサービス種別のインテグレーションを参照してください。

​

サービス種別別インテグレーション

ClickStack の alerts は、標準で次のサービス種別と連携できます。

• Slack: webhook または API を使用して、チャンネルに直接通知を送信します。
• PagerDuty: PagerDuty API を介して、オンコールチーム向けにインシデントをルーティングします。
• Webhook: 汎用 webhook を介して、alerts を任意のカスタムシステムやワークフローに接続します。

ClickHouse Cloud only integrations

Slack API および PagerDuty インテグレーションは、ClickHouse Cloud でのみサポートされています。

サービス種別に応じて、指定する内容は異なります。具体的には次のとおりです。

Slack (Webhook URL)

• Webhook URL。例: https://hooks.slack.com/services/<unique_path>。詳細については、Slack documentation を参照してください。

Slack (API)

• Slack bot token。詳細については、Slack documentation を参照してください。

PagerDuty API

• PagerDuty integration key。詳細については、PagerDuty documentation を参照してください。

Generic

• Webhook URL
• Webhook headers (任意)
• Webhook ボディ (任意) 。現在、ボディではテンプレート変数 {{title}}、{{body}}、{{link}} をサポートしています。

​

アラートの管理

アラートは、HyperDX の左側にあるアラートパネルから一元管理できます。

この画面では、作成済みで現在 ClickStack で有効になっているすべてのアラートを確認できます。

この画面には、アラートの評価履歴も表示されます。アラートは一定の時間間隔で繰り返し評価されます (アラート作成時に設定した period/duration で定義) 。各評価のたびに、HyperDX はアラート条件が満たされているかどうかを確認するため、データに対してクエリを実行します。

• 赤いバー: この評価でしきい値条件が満たされ、アラートが発報されました (通知送信あり)
• 緑のバー: アラートは評価されましたが、しきい値条件は満たされませんでした (通知送信なし)

各評価は独立しており、アラートはその時間ウィンドウのデータを確認し、その時点で条件が true の場合にのみ発報します。

上の例では、1 つ目のアラートは毎回の評価で発報しており、問題が継続していることを示しています。2 つ目のアラートは、解消済みの問題を示しています。最初に 2 回発報した後 (赤いバー) 、その後の評価ではしきい値条件が満たされなくなりました (緑のバー) 。

アラートをクリックすると、そのアラートが紐付けられているチャートまたは検索に移動します。

​

アラートの削除

アラートを削除するには、関連する Search またはチャートの編集ダイアログを開き、Remove Alert を選択します。 以下の例では、Remove Alert ボタンをクリックすると、チャートからアラートが削除されます。

​

SQLベースのチャートアラート

SQLベースのチャートアラートでは、任意の ClickHouse SQL を記述してアラート条件を定義できます。これにより、フィルタリング、集計、計算を含め、あらゆる処理を完全に制御できます。つまり、SQL で表現できるものはすべてアラートにできます。

​

サポートされているチャートタイプ

SQL ベースのアラートは、次の 3 つのチャート表示タイプでサポートされています。

チャートタイプ	動作
Line	時系列アラート。クエリは時間バケットごとの行を返す必要があります。各バケットはしきい値に対して個別に評価されます。
Stacked Bar	時系列アラート。動作は Line と同じです。
数値	単一値アラート。クエリは単一の数値結果を返し、評価のたびに 1 回しきい値と比較されます。

その他の SQL ベースのチャートタイプ (テーブル、円グラフ、ヒートマップなど) はアラートをサポートしていません。

​

SQLアラートを作成する

SQLベースのチャートにアラートを作成するには、次の手順を行います。

1. ​

   ダッシュボードでSQLベースのチャートを作成または開く

   保存済みのダッシュボードで、SQL チャートモードの新しいチャートを作成するか、既存のSQLベースのチャートを開いて編集します。

   表示タイプとして Line、Stacked Bar、または Number を選択します。

2. ​

   アラートを追加する

   チャートエディタのアラートセクションで Add Alert を選択します。次の項目を設定します。

   • しきい値タイプ: >= (以上) 、> (より大きい) 、<= (以下) 、< (より小さい) 、= (等しい) 、!= (等しくない) 、<= x >= (範囲内) 、または > or < (範囲外)
   • しきい値: 比較対象となる数値
   • インターバル: アラートを評価する頻度 (1m、5m、15m、30m、1h、6h、12h、または 1d) 。これは各評価の time window も定義します。
   • Webhook: アラート発報時に使用する通知チャネルです。Webhook の追加を参照してください。

   Alert Time Range

   通常、アラートクエリはインターバルごとに1回実行されます。ただし、エラーやクエリの遅延によって1つ以上のインターバルがスキップされた場合、次回の実行では、その未処理のインターバルを含む time window が使用されます。この場合、クエリの interval parameter は引き続きアラートに設定された period の値になりますが、time range parameter にはより長い time window が反映されます。

3. ​

   ダッシュボードを保存する

   アラートを有効にするには、ダッシュボードを保存します。アラートは設定したインターバルで評価を開始します。

​

クエリ結果の解釈方法

アラートシステムは、しきい値と比較する対象を判断するために、SQLクエリが返すカラムを確認します。

• 値カラム: SELECT 句の最後の数値カラムがアラートの値として使用されます。クエリが複数の数値カラム (例: count, avg_latency, p99_latency) を返す場合、しきい値と比較されるのは最後のカラム (p99_latency) のみです。
• タイムスタンプカラム: 時系列チャート (Line と Stacked Bar) では、システムは結果内の Date/DateTime カラムを時間バケット (つまり時系列チャートの x 軸) として識別します。各時間バケットの値カラムは、それぞれ独立してしきい値に対して評価され、いずれかの時間バケットの値が設定されたしきい値を超えた場合、アラートがトリガーされます。
• グループカラム: 数値カラムでもタイムスタンプカラムでもないカラム (例: ServiceName, Environment) は、グループ化の次元として扱われます。グループが存在する場合、グループ値の一意な組み合わせごとに個別に追跡され、それぞれに対してアラートが生成されます。ClickStack は、設定されたしきい値を超えた値を持つ各グループごとにアラートを送信します。グループは時系列チャートでのみ利用できます。

​

クエリパラメータとマクロ

SQL アラートクエリでは、評価時に自動的に置き換えられるテンプレートパラメータとマクロをサポートしています。これらは、SQL ベースのチャートを作成する際に使用できるパラメータやマクロと同じものです。

​

必須および推奨パラメータ

Line グラフまたは Stacked Bar グラフのアラートに使用するクエリには、必ずインターバルパラメータまたはマクロ ({intervalSeconds:Int64}、{intervalMilliseconds:Int64}、$__timeInterval(col)、または $__timeInterval_ms(col)) を含める必要があります。アラートの実行時には、これらはアラートに設定された期間に置き換えられます。

アラートに使用するクエリには、時間範囲フィルター ({startDateMilliseconds:Int64} と {endDateMilliseconds:Int64}、または $__timeFilter(col) など) を含めることを推奨します。クエリ内に時間範囲フィルターが含まれているかどうかにかかわらず、アラートクエリはアラートに設定された期間で実行されます。時間範囲フィルターがない場合、クエリは実行のたびにソーステーブルで利用可能な全期間を読み取ります。

アラートの時間範囲

通常、アラートクエリはインターバルごとに 1 回実行されます。ただし、エラーやクエリの遅延により 1 つ以上のインターバルがスキップされた場合、次回の実行では、スキップされたインターバルを含む時間範囲が使用されます。この場合でも、クエリのインターバルパラメータにはアラートに設定された期間が引き続き設定されますが、時間範囲パラメータにはより長い時間範囲が反映されます。

​

アラートクエリの例

​

サービスごとのエラー率 (時系列)

いずれかのサービスのエラー率が 5% を超えた場合にアラートを発報します。また、トラフィックの少ないサービスでノイズの多いアラートが発生するのを避けるため、アラート期間内のリクエスト数が少なくとも 10 件あることを条件とします。

WITH error_rates AS (
  SELECT
    $__timeInterval(Timestamp) as ts,
    ServiceName,
    countIf (SpanKind = 'Server') as request_count,
    countIf (
      SpanKind = 'Server'
      and StatusCode = 'Error'
    ) as error_count,
    error_count / request_count * 100 AS error_percent
  FROM $__sourceTable
  WHERE $__timeFilter(Timestamp)
  GROUP BY ts, ServiceName
)
SELECT ts, ServiceName, error_percent
FROM error_rates
WHERE request_count > 10

表示タイプ: Line または Stacked Bar しきい値: >= 5 (エラー率が 5% に達すると発報)

このクエリでは、ServiceName は数値カラムでもタイムスタンプのカラムでもないため、各サービスは個別のアラートグループとして扱われます。アラートはサービスごとに個別に発報されます。

​

ラグ付き平均による異常検知 (時系列)

エラー数が移動平均を2標準偏差超えて上回った場合にアラートを発します。これにより、固定のしきい値ではなく、直近のベースライン動作に対するスパイクを検出できます。

WITH buckets AS (
  SELECT
    $__timeInterval(Timestamp) AS ts,
    count() AS bucket_count
  FROM $__sourceTable
  WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
        - toIntervalSecond($__interval_s * 30) -- 30インターバル分さかのぼって取得
    AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
    AND SeverityText = 'error'
  GROUP BY ts
  ORDER BY ts
  WITH FILL
    FROM toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
    TO toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))
    STEP toIntervalSecond($__interval_s)
),

anomaly_detection AS (
  SELECT
    ts,
    bucket_count,
    avg(bucket_count) OVER (
      ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
    ) AS previous_30_avg,
    stddevPop(bucket_count) OVER (
      ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
    ) AS previous_30_stddev,
    greatest(
      bucket_count - (previous_30_avg + 2 * previous_30_stddev), 0
    ) AS excess_error_count
  FROM buckets
)

SELECT ts, excess_error_count
FROM anomaly_detection
WHERE ts >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
  AND ts < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})

表示タイプ: Line しきい値: > 0 (ローリングベースラインを上回る過剰なエラーが検出されると発報します)

このクエリは、ローリングウィンドウ計算を初期化するために、日付範囲の開始前の30インターバルを取得し、その後、最終出力を評価ウィンドウのみに絞り込みます。

​

一般的なアラートのシナリオ

HyperDX で活用できる、一般的なアラートのシナリオをいくつか紹介します。

エラー: デフォルトの All Error Events と HTTP Status >= 400 の保存済み検索に対してアラートを設定し、 エラーが過剰に発生したときに通知を受け取ることを推奨します。

低速な操作: 低速な操作を対象とする検索 (例: duration:>5000) を設定し、そのような操作の発生件数が多すぎる場合に アラートを出すことができます。

ユーザーイベント: 新規ユーザーの登録時や重要なユーザー操作が実行された際に、 顧客対応チームへ通知されるようアラートを設定することもできます。