次の方法で共有


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

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

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

リソース:

作業の開始

前提条件

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

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 を見つけるには:

  1. Azure portal内のリソースのページに移動します。
  2. [ 概要 ] ブレードで、[ JSON ビュー ] リンクを選択します。
  3. 結果の 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 やメモリ消費量などのログ クエリ実行統計を取得するには、次のようにします。

  1. LogsQueryOptions.IncludeStatistics プロパティを trueに設定します。
  2. オブジェクトで 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 演算子を使用してログ クエリの視覚化データを取得するには:

  1. LogsQueryOptions.IncludeVisualization プロパティを trueに設定します。
  2. オブジェクトで 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 を見つけるには、次のようにします。

  1. Azure portalでリソースのページに移動します。
  2. [ 概要 ] ブレードで、[ JSON ビュー ] リンクを選択します。
  3. 結果の 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オブジェクトには、型指定されたオブジェクト、、 TimeSpanIntervalCostResourceRegionNamespaceMetricResult一覧などのプロパティが含まれています。 オブジェクトの一覧には 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

インプレッション数