An Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.)
Install the package
Install the Azure Monitor Query Logs client library for .NET with NuGet:
dotnet add package Azure.Monitor.Query.Logs
Authenticate the client
An authenticated LogsQueryClient is required to query logs. To authenticate, you'll pass an instance of a TokenCredential to the constructor when creating your client. For example, the following illustration uses DefaultAzureCredential for authentication.
Client for Logs queries
var client = new LogsQueryClient(new DefaultAzureCredential());
Configure the client for an Azure sovereign cloud
By default, the client is configured to use the Azure Public Cloud. To use a sovereign cloud instead, set the Audience property on the appropriate Options-suffixed class. For example:
// LogsQueryClient - by default, Azure Public Cloud is used
var logsQueryClient = new LogsQueryClient(
new DefaultAzureCredential());
// LogsQueryClient With Audience Set
var logsQueryClientOptions = new LogsQueryClientOptions
{
Audience = LogsQueryAudience.AzureChina
};
var logsQueryClientChina = new LogsQueryClient(
new DefaultAzureCredential(),
logsQueryClientOptions);
Execute the query
For examples of Logs and Metrics queries, see the Examples section.
Key concepts
Logs query rate limits and throttling
The Log Analytics service applies throttling when the request rate is too high. Limits, such as the maximum number of rows returned, are also applied on the Kusto queries. For more information, see Query API.
Thread safety
All client instance methods are thread-safe and independent of each other (guideline). This design ensures that the recommendation of reusing client instances is always safe, even across threads.
Navigate to your resource's page in the Azure portal.
From the Overview blade, select the JSON View link.
In the resulting JSON, copy the value of the id property.
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 LogsQueryTimeRange(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);
}
Handle logs query response
The QueryWorkspace method returns the LogsQueryResult, while the QueryBatch method returns the LogsBatchQueryResult. Here's a hierarchy of the response:
LogsQueryResult
|---Error
|---Status
|---Table
|---Name
|---Columns (list of `LogsTableColumn` objects)
|---Name
|---Type
|---Rows (list of `LogsTableRows` objects)
|---Count
|---AllTables (list of `LogsTable` objects)
Map logs query results to a model
You can map logs query results to a model using the LogsQueryClient.QueryWorkspaceAsync<T> method:
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 LogsQueryTimeRange(TimeSpan.FromDays(1)));
foreach (var logEntryModel in response.Value)
{
Console.WriteLine($"{logEntryModel.ResourceGroup} had {logEntryModel.Count} events");
}
Map logs query results to a primitive
If your query returns a single column (or a single value) of a primitive type, use the LogsQueryClient.QueryWorkspaceAsync<T> overload to deserialize it:
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 LogsQueryTimeRange(TimeSpan.FromDays(1)));
foreach (var resourceGroup in response.Value)
{
Console.WriteLine(resourceGroup);
}
Print logs query results as a table
You can also dynamically inspect the list of columns. The following example prints the query result as a table:
string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());
Response<LogsQueryResult> response = await client.QueryWorkspaceAsync(
workspaceId,
"AzureActivity | top 10 by TimeGenerated",
new LogsQueryTimeRange(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();
}
Batch logs query
You can execute multiple logs queries in a single request using the LogsQueryClient.QueryBatchAsync method:
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 LogsQueryTimeRange(TimeSpan.FromDays(1)));
string topQueryId = batch.AddWorkspaceQuery(
workspaceId,
"AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
new LogsQueryTimeRange(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");
}
Advanced logs query scenarios
Set logs query timeout
Some logs queries take longer than 3 minutes to execute. The default server timeout is 3 minutes. You can increase the server timeout to a maximum of 10 minutes. In the following example, the LogsQueryOptions object's ServerTimeout property is used to set the server timeout to 10 minutes:
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 LogsQueryTimeRange(TimeSpan.FromDays(1)),
new LogsQueryOptions
{
ServerTimeout = TimeSpan.FromMinutes(10)
});
foreach (var resourceGroup in response.Value)
{
Console.WriteLine(resourceGroup);
}
Query multiple workspaces
To run the same logs query against multiple workspaces, use the LogsQueryOptions.AdditionalWorkspaces property:
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 LogsQueryTimeRange(TimeSpan.FromDays(1)),
new LogsQueryOptions
{
AdditionalWorkspaces = { additionalWorkspaceId }
});
foreach (var resourceGroup in response.Value)
{
Console.WriteLine(resourceGroup);
}
Include statistics
To get logs query execution statistics, such as CPU and memory consumption:
Set the LogsQueryOptions.IncludeStatistics property to true.
Invoke the GetStatistics method on the LogsQueryResult object.
The following example prints the query execution time:
string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());
Response<LogsQueryResult> response = await client.QueryWorkspaceAsync(
workspaceId,
"AzureActivity | top 10 by TimeGenerated",
new LogsQueryTimeRange(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());
Because the structure of the statistics payload varies by query, a BinaryData return type is used. It contains the raw JSON response. The statistics are found within the query property of the JSON. For example:
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately with labels and comments. Follow the instructions provided by the bot. You'll only need to sign the CLA once across all Microsoft repos.