チュートリアル: Resource Manager テンプレートを使ってワークスペースデータ収集ルールの変換を Azure Monitor に追加する

[アーティクル]
07/17/2023

このチュートリアルでは、Resource Manager テンプレートを使ってワークスペースデータ収集ルール内でサンプル変換を構成する手順について説明します。 Azure Monitor の変換を使うと、宛先への送信前に、受信データをフィルター処理または変更することができます。ワークスペース変換は、まだ Azure Monitor データインジェストパイプラインを使っていないワークフローに対するインジェスト時間の変換をサポートしています。

ワークスペース変換は、そのワークスペース用の 1 つのデータ収集ルール (DCR) (ワークスペース DCR と呼ばれます) にまとめて格納されます。各変換は、特定のテーブルに関連付けられます。変換は、DCR を使わないすべてのワークフローからこのテーブルに送信されるすべてのデータに適用されます。

注意

このチュートリアルでは、Resource Manager テンプレートと REST API を使ってワークスペース変換を構成します。 Azure portal を使った同じチュートリアルについては、Azure portal を使って Azure Monitor にワークスペースデータ収集ルールの変換を追加するチュートリアルに関するページを参照してください。

このチュートリアルで学習する内容は次のとおりです。

Log Analytics ワークスペースのテーブルに対してワークスペース変換を構成する。
インジェスト時間変換のログクエリを作成する。

注意

このチュートリアルでは、Azure Cloud Shell の PowerShell を使用し、Azure Monitor の Tables API と Azure portal を使用して REST API 呼び出しを行い、Resource Manager テンプレートをインストールします。これらの呼び出しは、他の方法を使用して行うことができます。

前提条件

このチュートリアルでは、以下のものが必要です。

少なくとも共同作成者権限がある Log Analytics ワークスペース。
ワークスペースにデータ収集ルールオブジェクトを作成するためのアクセス許可。
テーブルには既にいくつかのデータが含まれている必要があります。
テーブルをワークスペース変換 DCR にリンクすることはできません。

チュートリアルの概要

このチュートリアルでは、特定のレコードをフィルターすることで、LAQueryLogs テーブルのストレージ要件を削減します。また、列データを解析してカスタム列にデータを格納するときに、列の内容を削除します。 Laquerylogs テーブルは、ワークスペースでログクエリの監査を有効にしたときに作成されますが、これはチュートリアルのサンプルとしてのみ使用されます。これと同じ基本的なプロセスを使用して、Log Analytics ワークスペースでサポートされているテーブルの変換を作成できます。

クエリ監査ログを有効にする

作業する LAQueryLogs テーブルを作成するには、ワークスペースでクエリ監査を有効にする必要があります。これは、すべてのインジェスト時間変換には必要ありません。このサンプル変換で使用されるサンプルデータを生成するだけです。

Azure portal の [Log Analytics ワークスペース] メニューから [診断設定] を選択し、[診断設定を追加する] をクリックします。
診断設定の名前を指定し、監査データが同じワークスペースに保存されるようにワークスペースを選択します。 [監査] カテゴリを選択し、[保存] をクリックして診断設定を保存し、診断設定ページを閉じます。
[ログ] を選択し、クエリを実行して LAQueryLogs にデータを入力します。これらのクエリでは実際にデータを返す必要はありません。

テーブルスキーマの更新

変換を作成する前に、テーブルに対して次の 2 つの変更を行う必要があります。

テーブルのワークスペース変換を有効にする必要があります。これは、変換によってテーブルのスキーマが変更されない場合でも、変換を行うすべてのテーブルに必要です。
変換によって入力された追加の列は、テーブルに追加する必要があります。

以下の PowerShell コードを使用してテーブルを構成するには、Tables - Update API を使用します。 API を呼び出すと、カスタム列が定義されているかどうかにかかわらず、テーブルのワークスペース変換が有効になります。このサンプルには、変換クエリを使用して設定される Resources_CF という名前のカスタム列が含まれています。

重要

組み込みテーブルに追加されたカスタム列の末尾は、_CF にする必要があります。カスタムテーブル (名前の末尾が _CL であるテーブル) に追加された列には、このサフィックスは必要ではありません。

Azure portal で [Cloud Shell] ボタンをクリックして、環境が PowerShellに設定されていることを確認します。

次の PowerShell コードをコピーし、Path パラメーターをワークスペースの詳細に置換します。

$tableParams = @'
{
    "properties": {
        "schema": {
            "name": "LAQueryLogs",
            "columns": [
                {
                    "name": "Resources_CF",
                    "description": "The list of resources, this query ran against",
                    "type": "string",
                    "isDefaultDisplay": true,
                    "isHidden": false
                }
            ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/LAQueryLogs?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

そのコードを Cloud Shell のプロンプトに貼り付けて、実行します。
Azure portal の [Log Analytics ワークスペース] メニューに移動すると、列が追加されたことを確認できます。 [ログ] を選択して Log Analytics を開き、LAQueryLogs テーブルを展開してその列を表示します。

変換クエリを定義する

Log Analytics を使用して、変換クエリをデータ収集ルールに追加する前にテストします。

Azure portal の [Log Analytics ワークスペース] メニューでワークスペースを開き、[ログ] を選択して Log Analytics を開きます。
次のクエリを実行して、LAQueryLogs テーブルのコンテンツを表示します。 RequestContext 列のコンテンツを確認します。変換によって、この列からワークスペース名が取得され、残りのデータが削除されます。
```
LAQueryLogs
| take 10
```
次のようにクエリを変更します。
```
LAQueryLogs
| where QueryText !contains 'LAQueryLogs'
| extend Context = parse_json(RequestContext)
| extend Workspace_CF = tostring(Context['workspaces'][0])
| project-away RequestContext, Context
```
これにより、次の変更が行われます。
- これらのログエントリは役に立たないため、スペースを節約するために LAQueryLogs テーブル自体のクエリに関連する行を削除します。
- クエリされたワークスペースの名前の列を追加します。
- RequestContext 列からデータを削除して領域を節約します。
変換で使用するために、クエリに次の変更を加えます。
- このクエリのデータのソースとしてテーブル名 (この場合は LAQueryLogs) を指定するのではなく、source キーワードを使用します。これは、変換クエリで受信データを常に表す仮想テーブルです。
- 変換クエリでサポートされていないすべての演算子を削除します。サポートされている演算子の詳細な一覧については、「サポートされている KQL 機能」を参照してください。
- クエリを単一の行にフラット化して、DCR JSON に収まるようにします。
これらの変更後に変換で使用するクエリを次に示します。
```
source | where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''
```

データ収集ルール (DCR) を作成する

これはワークスペースの最初の変換であるため、ワークスペース変換の DCR を作成する必要があります。同じワークスペース内に他のテーブル用のワークスペース変換を作成すると、それらは常にこの同じ DCR に格納されます。

Azure portal の検索ボックスに、テンプレート と入力して、[カスタムテンプレートのデプロイ] を選択します。
[エディターで独自のテンプレートをビルド] をクリックします。

下の Resource Manager テンプレートをエディターに貼り付けて、[保存] をクリックします。このテンプレートでは、DCR が定義され、変換クエリが含まれます。パラメーターの値を収集するので、このテンプレートを変更する必要はありません。

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "westus2",
            "allowedValues": [
                "westus2",
                "eastus2",
                "eastus2euap"
            ],
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-09-01-preview",
            "kind": "WorkspaceTransforms",
            "properties": {
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "clv2ws1"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Microsoft-Table-LAQueryLogs"
                        ],
                        "destinations": [
                            "clv2ws1"
                        ],
                        "transformKql": "source |where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

[カスタムデプロイ] 画面で、データ収集ルールを格納する [サブスクリプション] と [リソースグループ] を指定し、テンプレートに定義されている値を指定します。これには、データ収集ルールの [名前] と、前の手順で収集した [ワークスペースリソース ID] が含まれます。 [場所] は、ワークスペースと同じ場所にする必要があります。 [リージョン] は既に設定されていて、データ収集ルールの場所に使用されます。
[確認と作成] をクリックし、詳細を確認したら [作成] をクリックします。
デプロイが完了したら、[デプロイの詳細] ボックスを展開し、データ収集ルールをクリックして詳細を表示します。 [JSON 表示] をクリックします。
データ収集ルールの [リソース ID] をコピーします。これは次の手順で使用します。

ワークスペースを DCR にリンクする

変換を有効にする最後の手順は、DCR をワークスペースにリンクすることです。

重要

ワークスペースは 1 つの DCR にしか接続できません。リンクされた DCR には、このワークスペースが変換先として含まれている必要があります。

以下の PowerShell コードを使用してテーブルを構成するには、Workspaces - Update API を使用します。

[Cloud Shell] ボタンをクリックして Cloud Shell を再度開きます。次の PowerShell コードをコピーし、パラメーターをワークスペースおよび DCR の値に置換します。

$defaultDcrParams = @'
{
    "properties": {
        "defaultDataCollectionRuleResourceId": "/subscriptions/{subscription}/resourceGroups/{resourcegroup}/providers/Microsoft.Insights/dataCollectionRules/{DCR}"
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}?api-version=2021-12-01-preview" -Method PATCH -payload $defaultDcrParams

そのコードを Cloud Shell のプロンプトに貼り付けて、実行します。

テスト変換

変換が有効になるまで約 30 分待ってから、テーブルに対してクエリを実行してテストできます。変換が適用された後にテーブルに送信されたデータのみが影響を受けます。

このチュートリアルでは、いくつかのサンプルクエリを実行して、LAQueryLogs テーブルにデータを送信します。変換によってこれらのレコードがフィルター処理されることを確認できるように、LAQueryLogs に対するクエリをいくつか含めます。出力には新しい Workspace_CF 列があり、LAQueryLogs のレコードはないことに注意してください。

トラブルシューティング

このセクションでは、受け取る可能性があるさまざまなエラー状態とその修正方法について説明します。

Log Analytics の IntelliSense でテーブルの新しい列が認識されない

IntelliSense を駆動するキャッシュは、更新に最大 24 時間かかる場合があります。

動的列の変換が機能していません

現在、動的列に影響を与える既知の問題があります。一時的な回避策は、動的列データに対して操作を実行する前に、parse_json() を使用して動的列データを明示的に解析することです。

チュートリアル: Resource Manager テンプレートを使ってワークスペースデータ収集ルールの変換を Azure Monitor に追加する

前提条件

チュートリアルの概要

クエリ監査ログを有効にする

テーブルスキーマの更新

変換クエリを定義する

データ収集ルール (DCR) を作成する

ワークスペースを DCR にリンクする

テスト変換

トラブルシューティング

Log Analytics の IntelliSense でテーブルの新しい列が認識されない

動的列の変換が機能していません

次のステップ

その他のリソース

チュートリアル: Resource Manager テンプレートを使ってワークスペース データ収集ルールの変換を Azure Monitor に追加する

前提条件

チュートリアルの概要

クエリ監査ログを有効にする

テーブル スキーマの更新

変換クエリを定義する

データ収集ルール (DCR) を作成する

ワークスペースを DCR にリンクする

テスト変換

トラブルシューティング

Log Analytics の IntelliSense でテーブルの新しい列が認識されない

動的列の変換が機能していません

次のステップ

その他のリソース

チュートリアル: Resource Manager テンプレートを使ってワークスペースデータ収集ルールの変換を Azure Monitor に追加する

テーブルスキーマの更新