ClickStack によるアラート

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

アラートは HyperDX のインターフェースから直接作成でき、Slack や PagerDuty など、よく利用される通知システムと連携します。

アラート機能は ClickStack のデータ全体に対してシームレスに動作し、システムの健全性の把握、パフォーマンス劣化の検出、主要なビジネスイベントの監視に役立ちます。

アラートの種類

ClickStack では、アラートを作成するための 2 つの補完的な方法として、検索アラート と ダッシュボードチャートアラート をサポートしています。アラートを作成すると、そのアラートは対応する検索またはチャートに関連付けられます。

1. 検索アラート

検索アラートを使用すると、保存済み検索の結果に基づいて通知をトリガーできます。これにより、特定のイベントやパターンが予想以上（または予想以下）の頻度で発生していることを検出できます。

定義された時間ウィンドウ内で一致する結果の件数が、指定したしきい値を超えるか下回ったときにアラートがトリガーされます。

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

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

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

アラートを作成する

アラート作成パネルから、次の操作を行えます:

アラートに関連付ける保存済み検索に名前を付けます。
しきい値を設定し、指定した期間内に何回しきい値に達したらアラートを発生させるかを指定します。しきい値は上限または下限としても使用できます。ここで設定する期間は、アラートがどの程度の頻度でトリガーされるかも決定します。
grouped by の値を指定します。これにより、例えば ServiceName のようなキーで検索結果を集約し、同じ検索から複数のアラートをトリガーできるようになります。
通知の送信先となる Webhook を選択します。このビューから新しい Webhook を直接追加することもできます。詳細は Webhook の追加を参照してください。

保存する前に、ClickStack はしきい値条件を可視化し、期待どおりに動作するかを確認できるようにします。

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

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

ダッシュボードアラートを使用すると、アラート機能をチャートに拡張できます。

保存済みダッシュボードから、チャートベースのアラートを直接作成できます。高度な計算には、フルな SQL 集計機能および ClickHouse 関数を利用できます。

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

注記

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

ダッシュボードアラートを追加するには:

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

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

アラートを追加する

Add Alert を選択します。

アラート条件を定義する

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

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

Webhook の追加

アラート作成時には、既存の webhook を使用することも、新しく作成することもできます。いったん作成された webhook は、他のアラートでも再利用できます。

webhook は、Slack や PagerDuty を含むさまざまなサービス種別や、汎用的な送信先向けに作成できます。

例えば、以下のチャートに対するアラートを作成する場合を考えます。webhook を指定する前に、ユーザーは Add New Webhook を選択できます。

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

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

ClickStack Open Source と ClickStack Cloud では、利用可能なサービス種別が異なる点に注意してください。詳しくは Service type integrations を参照してください。

サービス種別ごとの連携

ClickStack のアラートは、標準で次のサービス種別と連携できます:

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

ClickHouse Cloud only integrations

Slack API と PagerDuty の連携は ClickHouse Cloud でのみサポートされています。

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

Slack (Webhook URL)

Webhook URL。たとえば、https://hooks.slack.com/services/<unique_path>。詳細は Slack のドキュメントを参照してください。

Slack (API)

Slack ボットトークン。詳細は Slack のドキュメントを参照してください。

PagerDuty API

PagerDuty インテグレーションキー。詳細は PagerDuty のドキュメントを参照してください。

汎用

Webhook URL
Webhook ヘッダー (任意)
Webhook ボディ (任意)。現在、ボディではテンプレート変数 {{title}}、{{body}}、{{link}} が利用できます。

アラートの管理

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

このビューでは、ClickStack 内で作成され、現在有効になっているすべてのアラートを確認できます。

このビューには、アラートの評価履歴も表示されます。アラートは、アラート作成時に設定した期間/継続時間に基づく一定間隔で評価されます。各評価時に、HyperDX がデータをクエリしてアラート条件が満たされているかを確認します。

赤いバー: この評価の間にしきい値条件が満たされ、アラートが発火した（通知が送信された）ことを示します
緑のバー: アラートは評価されたが、しきい値条件は満たされなかった（通知は送信されなかった）ことを示します

各評価は独立しており、アラートはその時間ウィンドウのデータをチェックし、その時点で条件が真の場合にのみ発火します。

上記の例では、最初のアラートはすべての評価で発火しており、継続的な問題が発生していることを示しています。2つ目のアラートは解消済みの問題を示しており、当初は 2 回発火したものの（赤いバー）、その後の評価ではしきい値条件が満たされなくなっています（緑のバー）。

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

アラートの削除

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

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

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

対応しているチャートタイプ

SQL ベースのアラートは、次の 3 つのチャート表示タイプに対応しています。

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

その他の SQL ベースのチャートタイプ (Table、Pie、Heatmap など) は、アラートをサポートしていません。

SQL アラートを作成する

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

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

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

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

アラートを追加する

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

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

アラートのタイムレンジ

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

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

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

クエリ結果の解釈方法

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

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

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

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

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

折れ線または積み上げ棒チャートのアラートに使用するクエリには、必ずインターバルのパラメータまたはマクロ ({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) -- Fetch 30 intervals back
    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）を検出する検索を設定し、低速な処理が多く発生した場合にアラートが出るように構成できます。

ユーザーイベント: カスタマーサポートなどの顧客対応チーム向けに、新規ユーザーのサインアップや重要なユーザーアクションが実行されたときに通知されるアラートを設定することもできます。

アラートの種類​

1. 検索アラート​

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

アラートを作成する​

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

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

アラートを追加する​

アラート条件を定義する​

Webhook の追加​

サービス種別ごとの連携​

アラートの管理​

アラートの削除​

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

対応しているチャートタイプ​

SQL アラートを作成する​

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

アラートを追加する​

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

クエリ結果の解釈方法​

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

必須および推奨されるパラメータ​

アラート用クエリの例​

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

後方移動平均による異常検知 (時系列データ)​

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

アラートの種類

1. 検索アラート

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

アラートを作成する

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

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

アラートを追加する

アラート条件を定義する

Webhook の追加

サービス種別ごとの連携

アラートの管理

アラートの削除

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

対応しているチャートタイプ

SQL アラートを作成する

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

アラートを追加する

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

クエリ結果の解釈方法

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

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

アラート用クエリの例

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

後方移動平均による異常検知 (時系列データ)

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