.NET 用 Azure Monitor インジェスト クライアント ライブラリ - バージョン 1.1.1
Azure Monitor インジェスト クライアント ライブラリは、カスタム ログを Azure Monitor に送信するために使用されます。
このライブラリを使用すると、事実上すべてのソースから、サポートされている組み込みテーブル、または Log Analytics ワークスペースで作成したカスタム テーブルにデータを送信できます。 カスタム列を使用して組み込みテーブルのスキーマを拡張することもできます。
リソース:
作業の開始
前提条件
- Azure サブスクリプション
- TokenCredential 実装 (たとえば、資格情報の種類 "Azure Identity ライブラリ" など)
- データ収集エンドポイント
- データ収集ルール
- Log Analytics ワークスペース
パッケージをインストールする
NuGet を使用して .NET 用の Azure Monitor インジェスト クライアント ライブラリをインストールします。
dotnet add package Azure.Monitor.Ingestion
クライアントを認証する
データを取り込むには、認証されたクライアントが必要です。 認証するには、 クラスのインスタンスを TokenCredential 作成します。 クラスの LogsIngestionClient コンストラクターに渡します。
認証を行うために、次の例では パッケージから をAzure.Identity使用DefaultAzureCredentialします。
var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var client = new LogsIngestionClient(endpoint, credential);
Azure ソブリン クラウド用にクライアントを構成する
既定では、 LogsIngestionClient は Azure パブリック クラウドに接続するように構成されています。 代わりにソブリン クラウドに接続するには、 プロパティを設定します LogsIngestionClientOptions.Audience 。 次に例を示します。
var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var clientOptions = new LogsIngestionClientOptions
{
Audience = LogsIngestionAudience.AzureChina
};
var client = new LogsIngestionClient(endpoint, credential, clientOptions);
ログをアップロードする
ログ インジェストの例については、「例」セクション を 参照してください。
主要な概念
データ収集エンドポイント
データ収集エンドポイント (DCEs) を使用すると、Azure Monitor のインジェスト設定を一意に構成できます。 この記事 では、その内容、構造、およびそれらを作成して操作する方法など、DCEs の概要について説明します。
データ収集ルール
データ収集ルール (DCR) は、Azure Monitor によって収集されるデータを定義し、そのデータの送信方法と格納場所を指定します。 REST API 呼び出しでは、使用する DCR を指定する必要があります。 1 つの DCE で複数の DCR をサポートできます。そのため、ソース テーブルとターゲット テーブルごとに異なる DCR を指定できます。
DCR は、入力データの構造とターゲット テーブルの構造を理解する必要があります。 この 2 つが一致しない場合は、変換を使用してソース データを変換し、ターゲット テーブルと一致させることができます。 変換を使用して、ソース データをフィルター処理し、その他の計算や変換を実行することもできます。
詳細については、「 Azure Monitor のデータ収集ルール」を参照してください。
Log Analytics ワークスペース テーブル
カスタム ログは、作成した任意のカスタム テーブルと Log Analytics ワークスペース内の特定の組み込みテーブルにデータを送信できます。 ターゲット テーブルは、データを送信する前に存在している必要があります。 現在サポートされている組み込みのテーブルは次のとおりです。
スレッド セーフ
すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 この設計により、クライアント インスタンスの再利用に関する推奨事項は、スレッド間でも常に安全であることが保証されます。
その他の概念
クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間
例
- 依存関係の挿入でクライアントを登録する
- カスタム ログをアップロードする
- IEnumerable としてカスタム ログをアップロードする
- EventHandler を使用して IEnumerable としてカスタム ログをアップロードする
- ログの確認
サンプルを使用して、さまざまな API について理解することができます。
依存関係の挿入でクライアントを登録する
依存関係挿入 (DI) コンテナーに登録 LogsIngestionClient するには、 メソッドを AddLogsIngestionClient 呼び出します。 詳細については、「クライアントの 登録」を参照してください。
カスタム ログをアップロードする
または メソッドを LogsIngestionClient.Upload 使用してログを LogsIngestionClient.UploadAsync アップロードできます。 データ インジェストの 制限に注意してください。 このメソッドには、省略可能なパラメーターである string contentEncoding があります。 これは、渡される RequestContent のエンコードを指します。 既に操作されているコンテンツを渡す場合は、contentEncoding パラメーターを設定します。 たとえば、コンテンツが gzipped の場合は、contentEncoding を "gzip" に設定します。 このパラメーターが設定されていない場合、既定の動作は、すべての入力を gzip に設定します。
var endpoint = new Uri("<data_collection_endpoint>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";
var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);
DateTimeOffset currentTime = DateTimeOffset.UtcNow;
// Use BinaryData to serialize instances of an anonymous type into JSON
BinaryData data = BinaryData.FromObjectAsJson(
new[] {
new
{
Time = currentTime,
Computer = "Computer1",
AdditionalContext = new
{
InstanceName = "user1",
TimeZone = "Pacific Time",
Level = 4,
CounterName = "AppMetric1",
CounterValue = 15.3
}
},
new
{
Time = currentTime,
Computer = "Computer2",
AdditionalContext = new
{
InstanceName = "user2",
TimeZone = "Central Time",
Level = 3,
CounterName = "AppMetric1",
CounterValue = 23.5
}
},
});
// Upload our logs
Response response = await client.UploadAsync(
ruleId,
streamName,
RequestContent.Create(data)).ConfigureAwait(false);
IEnumerable としてカスタム ログをアップロードする
また、 メソッドまたは メソッドを LogsIngestionClient.Upload 使用してログを LogsIngestionClient.UploadAsync アップロードすることもできます。このメソッドでは、ログがジェネリック IEnumerable 型で渡され、オプション LogsUploadOptions のパラメーターが指定されます。 パラメーターには LogsUploadOptions 、シリアライザー、コンカレンシー、および EventHandler が含まれます。
var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";
var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);
DateTimeOffset currentTime = DateTimeOffset.UtcNow;
var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
entries.Add(
new {
Time = currentTime,
Computer = "Computer" + i.ToString(),
AdditionalContext = i
}
);
}
// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries).ConfigureAwait(false);
EventHandler を使用して IEnumerable としてカスタム ログをアップロードする
または メソッドを LogsIngestionClient.Upload 使用してログを LogsIngestionClient.UploadAsync アップロードできます。 これら 2 つのメソッドでは、ログはジェネリック IEnumerable 型で渡されます。 さらに、シリアライザー、 LogsUploadOptionsコンカレンシー、および EventHandler を設定できる型指定されたパラメーターがあります。 既定のシリアライザーは に System.Text.Json設定されていますが、使用するシリアライザーを渡すことができます。 プロパティは MaxConcurrency 、 メソッドで使用されるスレッドの数を UploadAsync 設定します。 既定値は 5 で、このパラメーターは メソッドでは Upload 使用されません。 EventHandler は、エラー処理に使用されます。 バッチが失敗した場合にアップロードを中止し、失敗したログと対応する例外にアクセスするオプションをユーザーに提供します。 EventHandler がないと、アップロードが失敗すると、 AggregateException がスローされます。
var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";
var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);
DateTimeOffset currentTime = DateTimeOffset.UtcNow;
var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
entries.Add(
new {
Time = currentTime,
Computer = "Computer" + i.ToString(),
AdditionalContext = i
}
);
}
// Set concurrency and EventHandler in LogsUploadOptions
LogsUploadOptions options = new LogsUploadOptions();
options.MaxConcurrency = 10;
options.UploadFailed += Options_UploadFailed;
// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries, options).ConfigureAwait(false);
Task Options_UploadFailed(LogsUploadFailedEventArgs e)
{
// Throw exception from EventHandler to stop Upload if there is a failure
IReadOnlyList<object> failedLogs = e.FailedLogs;
// 413 status is RequestTooLarge - don't throw here because other batches can successfully upload
if ((e.Exception is RequestFailedException) && (((RequestFailedException)e.Exception).Status != 413))
throw e.Exception;
else
return Task.CompletedTask;
}
ログの確認
Azure Monitor クエリ ライブラリを使用して、データが正しくアップロードされたことを確認できます。 ログを確認する前に、最初に カスタム ログのアップロード サンプルを実行します。
var workspaceId = "<log_analytics_workspace_id>";
var tableName = "<table_name>";
var credential = new DefaultAzureCredential();
LogsQueryClient logsQueryClient = new(credential);
LogsBatchQuery batch = new();
string query = tableName + " | Count;";
string countQueryId = batch.AddWorkspaceQuery(
workspaceId,
query,
new QueryTimeRange(TimeSpan.FromDays(1)));
Response<LogsBatchQueryResultCollection> queryResponse =
await logsQueryClient.QueryBatchAsync(batch).ConfigureAwait(false);
Console.WriteLine("Table entry count: " +
queryResponse.Value.GetResult<int>(countQueryId).Single());
トラブルシューティング
さまざまな障害シナリオの診断の詳細については、 トラブルシューティング ガイドを参照してください。
次のステップ
Azure Monitor の詳細については、 Azure Monitor サービスのドキュメントを参照してください。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。
pull request を送信すると、CLA を提供して PR を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 たとえば、ラベルやコメントなどです。 ボットによって提供される手順に従ってください。 CLA に署名する必要があるのは、CLA を使用するすべてのリポジトリで 1 回だけです。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳細については、 行動規範に 関する FAQ を参照するか、質問やコメントに問い合わせてください opencode@microsoft.com 。
Azure SDK for .NET