.NET 用 Azure Monitor クエリクライアントライブラリ - バージョン 1.2.0

[アーティクル]
05/24/2023

Azure Monitor クエリクライアントライブラリは、 Azure Monitor の 2 つのデータプラットフォームに対して読み取り専用クエリを実行するために使用されます。

ログ - 監視対象のリソースからログとパフォーマンスデータを収集して整理します。 Azure サービスからのプラットフォームログ、仮想マシンエージェントからのログとパフォーマンスデータ、アプリの使用状況とパフォーマンスデータなど、さまざまなソースからのデータを 1 つの Azure Log Analytics ワークスペースに統合できます。さまざまなデータ型は、Kusto 照会言語を使用して一緒に分析できます。
メトリック - 監視対象のリソースから時系列データベースに数値データを収集します。メトリックは、一定の間隔で収集される数値であり、特定の時刻におけるシステムの何らかの特性を表しています。メトリックは軽量で、ほぼリアルタイムのシナリオをサポートできるため、アラートや問題の迅速な検出に役立ちます。

リソース:

作業の開始

前提条件

Azure サブスクリプション
TokenCredential 実装 (たとえば、資格情報の種類 "Azure Identity ライブラリ" など)
ログに対してクエリを実行するには、次のいずれかが必要です。
- Azure Log Analytics ワークスペース
- 任意の種類の Azure リソース (ストレージアカウント、Key Vault、Cosmos DB など)
メトリックに対してクエリを実行するには、あらゆる種類の Azure リソース (ストレージアカウント、Key Vault、Cosmos DB など) が必要です。

パッケージをインストールする

NuGet を使用して .NET 用 Azure Monitor クエリクライアントライブラリをインストールします。

dotnet add package Azure.Monitor.Query

クライアントを認証する

ログまたはメトリックに対してクエリを実行するには、認証されたクライアントが必要です。認証するには、クラスのインスタンスを TokenCredential 作成します。またはクラスのコンストラクターにLogsQueryClientMetricsQueryClient渡します。

認証を行うために、次の例ではパッケージからをAzure.Identity使用DefaultAzureCredentialします。

var client = new LogsQueryClient(new DefaultAzureCredential());

var client = new MetricsQueryClient(new DefaultAzureCredential());

クエリを実行します

ログとメトリックのクエリの例については、「例」セクションを参照してください。

主要な概念

クエリレートの制限と調整をログに記録する

要求レートが高すぎると、Log Analytics サービスによって調整が適用されます。返される行の最大数などの制限は、Kusto クエリにも適用されます。詳細については、「クエリ API」を参照してください。

メトリックデータ構造

メトリック値の各セットは、次の特性を持つ時系列です。

値が収集された時刻
値に関連付けられているリソース
メトリックのカテゴリのように機能する名前空間
メトリック名
値そのもの
多次元メトリックで説明されているように、一部のメトリックには複数のディメンションが含まれる場合があります。カスタムメトリックは最大 10 個のディメンションを持つことができます。

スレッドセーフ

すべてのクライアントインスタンスメソッドはスレッドセーフであり、相互に独立しています (ガイドライン)。この設計により、クライアントインスタンスの再利用に関する推奨事項は、スレッド間でも常に安全であることが保証されます。

その他の概念

Logs クエリ

ワークスペース ID またはリソース ID でログに対してクエリを実行できます。結果は、行のコレクションを含むテーブルとして返されます。

ワークスペース中心のログクエリ

ワークスペース ID でクエリを実行するには、 LogsQueryClient.QueryWorkspaceAsync メソッドを使用します。

string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());

Response<LogsQueryResult> result = await client.QueryWorkspaceAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(1)));

LogsTable table = result.Value.Table;

foreach (var row in table.Rows)
{
    Console.WriteLine($"{row["OperationName"]} {row["ResourceGroup"]}");
}

リソース中心のログクエリ

リソース ID でクエリを実行するには、 LogsQueryClient.QueryResourceAsync メソッドを使用します。

リソース ID を見つけるには:

Azure portal内のリソースのページに移動します。
[ 概要 ] ブレードで、[ JSON ビュー ] リンクを選択します。
結果の JSON で、プロパティの値を id コピーします。

var client = new LogsQueryClient(new DefaultAzureCredential());

string resourceId = "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/<resource_provider>/<resource>";
string tableName = "<table_name>";
Response<LogsQueryResult> results = await client.QueryResourceAsync(
    new ResourceIdentifier(resourceId),
    $"{tableName} | distinct * | project TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(7)));

LogsTable resultTable = results.Value.Table;
foreach (LogsTableRow row in resultTable.Rows)
{
    Console.WriteLine($"{row["OperationName"]} {row["ResourceGroup"]}");
}

foreach (LogsTableColumn columns in resultTable.Columns)
{
    Console.WriteLine("Name: " + columns.Name + " Type: " + columns.Type);
}

ログのクエリ応答を処理する

メソッドは QueryWorkspace を返し、 LogsQueryResultメソッドは QueryBatch を返します LogsBatchQueryResult。応答の階層を次に示します。

LogsQueryResult
|---Error
|---Status
|---Table
    |---Name
    |---Columns (list of `LogsTableColumn` objects)
        |---Name
        |---Type
    |---Rows (list of `LogsTableRows` objects)
        |---Count
|---AllTables (list of `LogsTable` objects)

ログのクエリ結果をモデルにマップする

メソッドを使用して、ログのクエリ結果をモデルに LogsQueryClient.QueryWorkspaceAsync<T> マップできます。

public class MyLogEntryModel
{
    public string ResourceGroup { get; set; }
    public int Count { get; set; }
}

var client = new LogsQueryClient(new DefaultAzureCredential());
string workspaceId = "<workspace_id>";

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<MyLogEntryModel>> response = await client.QueryWorkspaceAsync<MyLogEntryModel>(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
    new QueryTimeRange(TimeSpan.FromDays(1)));

foreach (var logEntryModel in response.Value)
{
    Console.WriteLine($"{logEntryModel.ResourceGroup} had {logEntryModel.Count} events");
}

ログのクエリ結果をプリミティブにマップする

クエリがプリミティブ型の 1 つの列 (または単一の値) を返す場合は、オーバーロードを LogsQueryClient.QueryWorkspaceAsync<T> 使用して逆シリアル化します。

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<string>> response = await client.QueryWorkspaceAsync<string>(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count | project ResourceGroup",
    new QueryTimeRange(TimeSpan.FromDays(1)));

foreach (var resourceGroup in response.Value)
{
    Console.WriteLine(resourceGroup);
}

ログのクエリ結果をテーブルとして出力する

列の一覧を動的に検査することもできます。次の例では、クエリ結果をテーブルとして出力します。

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());
Response<LogsQueryResult> response = await client.QueryWorkspaceAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(1)));

LogsTable table = response.Value.Table;

foreach (var column in table.Columns)
{
    Console.Write(column.Name + ";");
}

Console.WriteLine();

var columnCount = table.Columns.Count;
foreach (var row in table.Rows)
{
    for (int i = 0; i < columnCount; i++)
    {
        Console.Write(row[i] + ";");
    }

    Console.WriteLine();
}

バッチログクエリ

メソッドを使用して、1 つの要求で複数のログクエリを LogsQueryClient.QueryBatchAsync 実行できます。

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
// And total event count
var batch = new LogsBatchQuery();

string countQueryId = batch.AddWorkspaceQuery(
    workspaceId,
    "AzureActivity | count",
    new QueryTimeRange(TimeSpan.FromDays(1)));
string topQueryId = batch.AddWorkspaceQuery(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
    new QueryTimeRange(TimeSpan.FromDays(1)));

Response<LogsBatchQueryResultCollection> response = await client.QueryBatchAsync(batch);

var count = response.Value.GetResult<int>(countQueryId).Single();
var topEntries = response.Value.GetResult<MyLogEntryModel>(topQueryId);

Console.WriteLine($"AzureActivity has total {count} events");
foreach (var logEntryModel in topEntries)
{
    Console.WriteLine($"{logEntryModel.ResourceGroup} had {logEntryModel.Count} events");
}

高度なログクエリシナリオ

ログクエリのタイムアウトを設定する

一部のログクエリの実行には 3 分以上かかります。既定のサーバータイムアウトは 3 分です。サーバーのタイムアウトを最大 10 分に増やすことができます。次の例では、オブジェクトの ServerTimeout プロパティをLogsQueryOptions使用して、サーバーのタイムアウトを 10 分に設定します。

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<string>> response = await client.QueryWorkspaceAsync<string>(
    workspaceId,
    @"AzureActivity
        | summarize Count = count() by ResourceGroup
        | top 10 by Count
        | project ResourceGroup",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    new LogsQueryOptions
    {
        ServerTimeout = TimeSpan.FromMinutes(10)
    });

foreach (var resourceGroup in response.Value)
{
    Console.WriteLine(resourceGroup);
}

複数のワークスペースに対してクエリを実行する

複数のワークスペースに対して同じログクエリを実行するには、プロパティを LogsQueryOptions.AdditionalWorkspaces 使用します。

string workspaceId = "<workspace_id>";
string additionalWorkspaceId = "<additional_workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<string>> response = await client.QueryWorkspaceAsync<string>(
    workspaceId,
    @"AzureActivity
        | summarize Count = count() by ResourceGroup
        | top 10 by Count
        | project ResourceGroup",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    new LogsQueryOptions
    {
        AdditionalWorkspaces = { additionalWorkspaceId }
    });

foreach (var resourceGroup in response.Value)
{
    Console.WriteLine(resourceGroup);
}

統計情報を含める

CPU やメモリ消費量などのログクエリ実行統計を取得するには、次のようにします。

LogsQueryOptions.IncludeStatistics プロパティを trueに設定します。
オブジェクトで GetStatistics メソッドを LogsQueryResult 呼び出します。

次の例では、クエリの実行時間を出力します。

string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());

Response<LogsQueryResult> response = await client.QueryWorkspaceAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    new LogsQueryOptions
    {
        IncludeStatistics = true,
    });

BinaryData stats = response.Value.GetStatistics();
using var statsDoc = JsonDocument.Parse(stats);
var queryStats = statsDoc.RootElement.GetProperty("query");
Console.WriteLine(queryStats.GetProperty("executionTime").GetDouble());

統計ペイロードの構造はクエリによって異なるため、戻り値の BinaryData 型が使用されます。生の JSON 応答が含まれています。統計は、JSON の query プロパティ内にあります。次に例を示します。

{
  "query": {
    "executionTime": 0.0156478,
    "resourceUsage": {...},
    "inputDatasetStatistics": {...},
    "datasetStatistics": [{...}]
  }
}

視覚化を含める

render 演算子を使用してログクエリの視覚化データを取得するには:

LogsQueryOptions.IncludeVisualization プロパティを trueに設定します。
オブジェクトで GetVisualization メソッドを LogsQueryResult 呼び出します。

次に例を示します。

string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());

Response<LogsQueryResult> response = await client.QueryWorkspaceAsync(
    workspaceId,
    @"StormEvents
        | summarize event_count = count() by State
        | where event_count > 10
        | project State, event_count
        | render columnchart",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    new LogsQueryOptions
    {
        IncludeVisualization = true,
    });

BinaryData viz = response.Value.GetVisualization();
using var vizDoc = JsonDocument.Parse(viz);
var queryViz = vizDoc.RootElement.GetProperty("visualization");
Console.WriteLine(queryViz.GetString());

視覚化ペイロードの構造はクエリによって異なるため、戻り値の BinaryData 型が使用されます。生の JSON 応答が含まれています。次に例を示します。

{
  "visualization": "columnchart",
  "title": null,
  "accumulate": false,
  "isQuerySorted": false,
  "kind": null,
  "legend": null,
  "series": null,
  "yMin": "",
  "yMax": "",
  "xAxis": null,
  "xColumn": null,
  "xTitle": null,
  "yAxis": null,
  "yColumns": null,
  "ySplit": null,
  "yTitle": null,
  "anomalyColumns": null
}

メトリッククエリ

メソッドを使用して、Azure リソースのメトリックに対してクエリを MetricsQueryClient.QueryResourceAsync 実行できます。要求されたメトリックごとに、コレクション内 TimeSeries で一連の集計値が返されます。

メトリックのクエリを実行するには、リソース ID が必要です。リソース ID を見つけるには、次のようにします。

Azure portalでリソースのページに移動します。
[ 概要 ] ブレードで、[ JSON ビュー ] リンクを選択します。
結果の JSON で、プロパティの値を id コピーします。

string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/<resource_provider>/<resource>";
var client = new MetricsQueryClient(new DefaultAzureCredential());

Response<MetricsQueryResult> results = await client.QueryResourceAsync(
    resourceId,
    new[] { "Query Success Rate", "Query Count" }
);

foreach (MetricResult metric in results.Value.Metrics)
{
    Console.WriteLine(metric.Name);
    foreach (MetricTimeSeriesElement element in metric.TimeSeries)
    {
        Console.WriteLine("Dimensions: " + string.Join(",", element.Metadata));

        foreach (MetricValue value in element.Values)
        {
            Console.WriteLine(value);
        }
    }
}

メトリッククエリの応答を処理する

メトリッククエリ API はオブジェクトを MetricsQueryResult 返します。 MetricsQueryResultオブジェクトには、型指定されたオブジェクト、、 TimeSpanIntervalCostResourceRegionNamespaceのMetricResult一覧などのプロパティが含まれています。オブジェクトの一覧には MetricResult 、パラメーターを metrics 使用してアクセスできます。この一覧の各 MetricResult オブジェクトには、オブジェクトの MetricTimeSeriesElement 一覧が含まれています。各MetricTimeSeriesElementオブジェクトには、プロパティとプロパティがMetadataValues含まれています。

応答の階層を次に示します。

MetricsQueryResult
|---Cost
|---Granularity
|---Namespace
|---ResourceRegion
|---TimeSpan
|---Metrics (list of `MetricResult` objects)
    |---Id
    |---ResourceType
    |---Name
    |---Description
    |---Error
    |---Unit
    |---TimeSeries (list of `MetricTimeSeriesElement` objects)
        |---Metadata
        |---Values

オプションを使用してメトリックにクエリを実行する

オブジェクトは MetricsQueryOptions 、より詳細なメトリッククエリをサポートするために使用できます。 TestVault という名前の Azure Key Vault リソースに対してクエリを実行する次の例を考えてみましょう。リソースの "コンテナー要求の可用性" メトリックは、メトリック ID "可用性" で示されているように要求されます。また、"Avg" 集計の種類も含まれています。

string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.KeyVault/vaults/TestVault";
string[] metricNames = new[] { "Availability" };
var client = new MetricsQueryClient(new DefaultAzureCredential());

Response<MetricsQueryResult> result = await client.QueryResourceAsync(
    resourceId,
    metricNames,
    new MetricsQueryOptions
    {
        Aggregations =
        {
            MetricAggregationType.Average,
        }
    });

MetricResult metric = result.Value.Metrics[0];

foreach (MetricTimeSeriesElement element in metric.TimeSeries)
{
    foreach (MetricValue value in element.Values)
    {
        // Prints a line that looks like the following:
        // 6/21/2022 12:29:00 AM +00:00 : 100
        Console.WriteLine($"{value.TimeStamp} : {value.Average}");
    }
}

ディメンションでメトリックを分割する

MetricsQueryOptions.Filter プロパティは、フィルター値がアスタリスクに設定されている場合に、ディメンションによってメトリックを分割するために使用できます。 TestWebApp という名前のApp Service リソースの次の例を考えてみましょう。このコードでは、リソースのメトリックに Http2xx 対してクエリを実行し、ディメンションで Instance 分割します。

string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Web/sites/TestWebApp";
string[] metricNames = new[] { "Http2xx" };
// Use of asterisk in filter value enables splitting on Instance dimension.
string filter = "Instance eq '*'";
var client = new MetricsQueryClient(new DefaultAzureCredential());
var options = new MetricsQueryOptions
{
    Aggregations =
    {
        MetricAggregationType.Average,
    },
    Filter = filter,
    TimeRange = TimeSpan.FromDays(2),
};
Response<MetricsQueryResult> result = await client.QueryResourceAsync(
    resourceId,
    metricNames,
    options);

foreach (MetricResult metric in result.Value.Metrics)
{
    foreach (MetricTimeSeriesElement element in metric.TimeSeries)
    {
        foreach (MetricValue value in element.Values)
        {
            // Prints a line that looks like the following:
            // Thursday, May 4, 2023 9:42:00 PM, webwk000002, Http2xx, 1
            Console.WriteLine(
                $"{value.TimeStamp:F}, {element.Metadata["Instance"]}, {metric.Name}, {value.Average}");
        }
    }
}

Azure リソースの種類ごとに使用できるメトリックとディメンションのインベントリについては、「 Azure Monitor でサポートされているメトリック」を参照してください。

依存関係の挿入でクライアントを登録する

依存関係挿入 (DI) コンテナーに登録 LogsQueryClient するには、メソッドを AddLogsQueryClient 呼び出します。依存関係挿入 (DI) コンテナーに登録 MetricsQueryClient するには、メソッドを AddMetricsQueryClient 呼び出します。詳細については、「クライアントの登録」を参照してください。

トラブルシューティング

さまざまな障害シナリオを診断するには、トラブルシューティングガイドを参照してください。

次のステップ

Azure Monitor の詳細については、 Azure Monitor サービスのドキュメントを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、「 cla.microsoft.com」を参照してください。

pull request を送信すると、CLA ボットは CLA を提供する必要があるかどうかを自動的に判断し、ラベルとコメントを使用して PR を適切に装飾します。ボットによって提供される手順に従ってください。 CLA に署名する必要があるのは、すべての Microsoft リポジトリで 1 回だけです。

このプロジェクトは、「Microsoft のオープンソースの倫理規定」を採用しています。詳細については、行動規範に関する FAQ を参照するか、質問やコメントに問い合わせてください opencode@microsoft.com 。

インプレッション数

次の方法で共有

.NET 用 Azure Monitor クエリクライアントライブラリ - バージョン 1.2.0

作業の開始

前提条件

パッケージをインストールする

クライアントを認証する

クエリを実行します

主要な概念

クエリレートの制限と調整をログに記録する

メトリックデータ構造

スレッドセーフ

その他の概念

例

Logs クエリ

ログのクエリ応答を処理する

ログのクエリ結果をモデルにマップする

ログのクエリ結果をプリミティブにマップする

ログのクエリ結果をテーブルとして出力する

バッチログクエリ

高度なログクエリシナリオ

ログクエリのタイムアウトを設定する

複数のワークスペースに対してクエリを実行する

統計情報を含める

視覚化を含める

メトリッククエリ

メトリッククエリの応答を処理する

オプションを使用してメトリックにクエリを実行する

ディメンションでメトリックを分割する

依存関係の挿入でクライアントを登録する

トラブルシューティング

次のステップ

共同作成

その他のリソース

次の方法で共有

.NET 用 Azure Monitor クエリ クライアント ライブラリ - バージョン 1.2.0

作業の開始

前提条件

パッケージをインストールする

クライアントを認証する

クエリを実行します

主要な概念

クエリレートの制限と調整をログに記録する

メトリック データ構造

スレッド セーフ

その他の概念

例

Logs クエリ

ログのクエリ応答を処理する

ログのクエリ結果をモデルにマップする

ログのクエリ結果をプリミティブにマップする

ログのクエリ結果をテーブルとして出力する

バッチ ログ クエリ

高度なログクエリシナリオ

ログクエリのタイムアウトを設定する

複数のワークスペースに対してクエリを実行する

統計情報を含める

視覚化を含める

メトリック クエリ

メトリック クエリの応答を処理する

オプションを使用してメトリックにクエリを実行する

ディメンションでメトリックを分割する

依存関係の挿入でクライアントを登録する

トラブルシューティング

次のステップ

共同作成

その他のリソース

.NET 用 Azure Monitor クエリクライアントライブラリ - バージョン 1.2.0

メトリックデータ構造

スレッドセーフ

バッチログクエリ

メトリッククエリ

メトリッククエリの応答を処理する