Azure Monitor で変換を作成する
Azure Monitor の変換を使用すると、Log Analytics ワークスペースに格納される前に、受信データをフィルター処理または変更できます。 これらは、データ コレクション規則 (DCR) の Kusto 照会言語 (KQL) ステートメントとして実装されます。 この記事では、変換クエリの作成とテストと、DCR へのその追加について説明します。
Note
KQL または Azure Monitor データでのログ クエリの作成に慣れていない場合は、「Azure Monitor の Log Analytics の概要」と「Azure Monitor でのログ クエリ」を最初にお読みください。
クエリの基本的な構造
すべての変換クエリは、入力ストリームを表す仮想テーブルである source で始まります。 その後は、他のテーブルと同様に、サポートされている任意の KQL 演算子を使って、データのフィルター処理、変更、または列の追加を行うことができます。 クエリは、データ ソースによって送信されるエントリごとに個別に適用されます。
クエリの出力は、次のことを考慮して、ターゲット テーブルのスキーマと一致している必要があります。
- 取り込むべきでない列は省略できます。 ターゲット テーブルのレコードでは、その列は空になります。
- 出力テーブルに含まれていない列は必ず除外してください。 データはエラーなしで受け入れられますが、格納されない場合でも、追加データのインジェストには課金されます。
- すべての変換の出力には、
datetime型のTimeGeneratedという名前の列に、有効なタイムスタンプが含まれている必要があります。 データ ソースにこのプロパティが含まれていない場合は、extendまたはprojectを使って変換でそれを追加できます。
いくつかの機能を実行する変換の例を次に示します。
whereステートメントを使用して受信データをフィルター処理します。extend演算子を使用して新しい列を追加します。project演算子を使用して、ターゲット テーブルの列と一致するように出力を書式設定します。
source
| where severity == "Critical"
| extend Properties = parse_json(properties)
| project
TimeGenerated = todatetime(["time"]),
Category = category,
StatusDescription = StatusDescription,
EventName = name,
EventId = tostring(Properties.EventId)
Note
異なるシナリオのさまざまなサンプルについては、Azure Monitor での データ収集ルール (DCR) のサンプルとシナリオに関する記事をご覧ください。
変換クエリを作成する
変換を含む DCR を作成または編集する前に、変換クエリを作成してテストする必要があります。 通常は、既存のデータまたはテスト データに対してテスト クエリを実行してこれを行います。 望む結果が得られたら、後の「変換を DCR に追加する」で説明されているように、テーブル名を source に置き換えて DCR に貼り付けることができます。
重要
変換では、すべての KQL 機能がサポートされているわけではありません。 サポートされている機能と制限については、「Azure Monitor の変換でサポートされている KQL の機能」をご覧ください。
たとえば、Syslog イベントをフィルター処理する変換を作成する場合は、Log Analytics で実行できる次のクエリから始めることができます。
Syslog | where SeverityLevel != 'info'
このクエリを DCR に貼り付けてから、テーブル名を source に変更します。
source | where SeverityLevel != 'info'
クエリのテストに使うデータの場合は、次のいずれかの戦略を使います。
- 変換するデータを既に収集してある場合は、Log Analytics を使い、必要に応じてデータをフィルター処理または変更するクエリを作成できます。 クエリ テキストをコピーして DCR に貼り付けます。
- Log Analytics を使い、
datatable演算子を使ってクエリを記述して、受信データを表すサンプル データ セットを作成します。datatable演算子を除いたクエリ テキストをコピーして、DCR に貼り付けます。 - このプロセスを使って、Azure portal で新しいテーブルを作成し、サンプル データを提供します。 含まれるインターフェイスを使って、変換クエリを作成してテストします。 クエリ テキストをコピーして DCR に貼り付けるか、プロセスを完了してから DCR を編集して変換クエリをコピーします。 その後、新しいテーブルが不要な場合は削除できます。
変換を DCR に追加する
変換クエリができたら、それを DCR に追加できます。 Azure Monitor でのデータ収集ルール (DCR) の作成と編集に関するガイダンスに従って DCR を作成または編集し、このセクションの情報を使って変換クエリを DCR 定義に含めます。
Note
一部のデータ ソースでは、Azure portal を使って変換を DCR に追加する方法が提供されています。 たとえば、仮想マシンからのテキストの収集では、Azure portal で変換クエリを指定できます。 ただし、ほとんどのデータ収集シナリオでは、現在、変換を追加するために DCR 定義を直接操作する必要があります。 このセクションではそのプロセスについて説明します。
変換クエリは、DCR の データ フロー セクションの transformKql プロパティで指定します。 これは、データ ソースと変換先をペアにするセクションです。 変換は、変換先に送信される前のデータ フローの受信ストリームに適用されます。 他のデータ フローで同じストリームまたは変換先が使われている場合でも、そのデータ フローにのみ適用されます。
transformKql プロパティを省略した場合、またはその値が単に source である場合、変換は適用されず、受信データが変更されずに変換先に送信されます。
重要
DCR では、変換クエリは 1 行になっている必要があります。 Azure portal で変換を作成する場合は、読みやすくするために複数の行を使用でき、新しい行ごとに \n がクエリに含まれます。
次の例には transformKql プロパティがないため、受信データは変更されずに変換先に送信されます。
"dataFlows": [
{
"streams": [
"Microsoft-Syslog"
],
"destinations": [
"centralWorkspace"
]
}
]
次の例の transformKql プロパティは source の単純なクエリであるため、受信データは変更されずに変換先に送信されます。 その機能は、前の例と同じです。
"dataFlows": [
{
"streams": [
"Microsoft-Syslog"
],
"transformKql": "source",
"destinations": [
"centralWorkspace"
]
}
]
次の例の transformKql にはデータをフィルター処理するクエリが含まれるため、エラー メッセージのみが変換先に送信されます。
"dataFlows": [
{
"streams": [
"Microsoft-Syslog"
],
"transformKql": "source | where message has 'error'",
"destinations": [
"centralWorkspace"
]
}
]
ワークスペース変換 DCR を作成する
ワークスペース変換データ収集規則 (DCR) は、Log Analytics ワークスペースに直接適用される特殊な DCR です。 各ワークスペースに存在できるワークスペース変換 DCR は 1 つだけですが、その中には任意の数のテーブルの変換を含めることができます。
次のいずれかの方法を使ってワークスペースのワークスペース変換 DCR を作成し、それに 1 つ以上の変換を追加します。
Azure portal でサポートされているテーブルに変換を追加して、ワークスペース変換 DCR を作成できます。
Azure portal の Log Analytics ワークスペースのメニューで、[テーブル] を選びます。 目的のテーブルの右側をクリックして、[変換の作成] を選びます。
このワークスペースに対してワークスペース変換 DCR がまだ作成されていない場合は、作成するオプションを選びます。 既に作成されている場合は、その DCR が既に選ばれています。 各ワークスペースに使用できるワークスペース変換 DCR は 1 つだけです。
[次へ] を選択して、テーブルからサンプル データを表示します。 変換クエリを定義するには、[変換エディター] をクリックします。
その後、変換クエリを編集して実行し、テーブルの実際のデータに対して結果を確認できます。 望む結果が得られるまで、クエリの変更とテストを続けます。
クエリに問題がなければ、[適用]、[次へ]、[作成] の順にクリックして、新しい変換を含む DCR を保存します。
変換を最適化して監視する
変換では、DCR で収集されたすべてのレコードに対して KQL クエリが実行されるため、効率よく実行することが重要です。 変換の実行時間は全体的なデータ インジェスト待機時間に影響し、実行に時間がかかりすぎる変換は、データ収集パイプラインのパフォーマンスに影響を与えて、データ損失の原因になる可能性があります。 最適な変換は、1 秒以下で実行される必要があります。 変換として実装する前のクエリのテストに関するガイダンスと、実行の効率が悪いクエリの最適化に関する推奨事項については、「Azure Monitor でログ クエリを最適化する」をご覧ください。
重要
変換の時間が 20 秒を超えた場合、データが失われる可能性があります。
変換は対話形式では実行されないため、それらを継続的に監視し、適切に実行され、データ処理に時間がかかりすぎないことを確認することが重要です。 変換の正常性とパフォーマンスを監視するログとメトリックの詳細については、「Azure Monitor での DCR データ収集の監視とトラブルシューティング」を参照してください。 これには、KQL で発生したエラーの特定と、その実行時間を追跡するためのメトリックの識別が含まれます。
変換に関しては、以下のメトリックが自動的に収集されており、変換が期待どおりに実行されていることを確認するために、これらを定期的に確認する必要があります。 これらのメトリックのいずれかがしきい値を超えたときに自動的に通知するメトリック アラート ルールを作成します。
- 1 分あたりのログ変換期間
- 1 分あたりの変換エラー数のログ記録
DCR エラー ログを有効にして、変換や他のクエリ内で発生するエラーを追跡します。 このテーブルにエントリが書き込まれたら自動的に通知するログ アラート ルールを作成します。
ガイダンス
変換を作成する方法は、データ収集の方法に応じて複数あります。 次の表に、変換を作成するためのさまざまな方法に関するガイダンスを示します。
| データ コレクション | リファレンス |
|---|---|
| ログ インジェスト API | REST API (Azure portal) を使用して Azure Monitor ログにデータを送信する REST API (Azure Resource Manager テンプレート) を使用して Azure Monitor ログにデータを送信する |
| Azure Monitor エージェントを使用した仮想マシン | Azure Monitor ログに変換を追加する |
| Container Insights を使用した Kubernetes クラスター | Container Insights でのデータ変換 |
| Azure Event Hubs | トリアル: Azure Event Hubs から Azure Monitor ログにイベントを取り込む (パブリック プレビュー) |
次のステップ
- データ収集ルールを作成し、Azure Monitor エージェントを使用する仮想マシンからそのデータ収集ルールとの関連付けを作成します。