Skip to content

Commit 9a1a68e

Browse files
nisha-bhatianisha-bhatia
authored
Add ApplicationInsights Migration Guide to Azure.Monitor.Query (Azure#27235)
1 parent 62757cc commit 9a1a68e

File tree

3 files changed

+156
-3
lines changed

3 files changed

+156
-3
lines changed

‎sdk/monitor/Azure.Monitor.Query/MigrationGuideApplicationInsights.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Guide for migrating from Microsoft.Azure.ApplicationInsights.Query v1.0.0 to Azure.Monitor.Query v1.0.x
2+
3+
This guide assists you in the migration from [Microsoft.Azure.ApplicationInsights.Query](https://www.nuget.org/packages/Microsoft.Azure.ApplicationInsights.Query) v0.1.0 to [Azure.Monitor.Query](https://www.nuget.org/packages/Azure.Monitor.Query/) v1.0.x. Side-by-side comparisons are provided for similar operations between the two packages.
4+
5+
Familiarity with the `Microsoft.Azure.ApplicationInsights.Query` v1.0.0 package is assumed. If you're new to the Azure Monitor Query client library for .NET, see the [README file](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/monitor/Azure.Monitor.Query#readme) instead of this guide.
6+
7+
## Table of contents
8+
9+
- [Migration benefits](#migration-benefits)
10+
- [Cross-service SDK improvements](#cross-service-sdk-improvements)
11+
- [New features](#new-features)
12+
- [Important changes](#important-changes)
13+
- [The client](#the-client)
14+
- [Client constructors and authentication](#client-constructors-and-authentication)
15+
- [Send a single query request](#sending-a-single-query-request)
16+
- [Additional samples](#additional-samples)
17+
18+
## Migration benefits
19+
20+
A natural question to ask when considering whether to adopt a new version or library is what the benefits of doing so would be. As Azure has matured and been embraced by a more diverse group of developers, we've focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the .NET client libraries have.
21+
22+
Several areas of consistent feedback were expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services haven't had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was too steep. The APIs didn't offer an approachable and consistent onboarding story for those learning Azure or exploring a specific Azure service.
23+
24+
To improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [.NET specific guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html) was also introduced to ensure that .NET clients have a natural and idiomatic feel with respect to the .NET ecosystem. Further details are available in the guidelines.
25+
26+
### Cross-service SDK improvements
27+
28+
The Azure Monitor Query client library also takes advantage of the cross-service improvements made to the Azure development experience. Examples include:
29+
30+
- Using the new [Azure Identity](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity#readme) library to share a single authentication approach between clients.
31+
- A unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries.
32+
33+
### New features
34+
35+
There are a variety of new features in version 1.0 of the `Azure.Monitor.Query` library. Some highlights include:
36+
37+
- The ability to execute a batch of Kusto queries with the `LogsQueryClient.QueryBatch()` API.
38+
- The ability to configure the retry policy used by the operations on the client.
39+
- The ability to map a Logs query result to a strongly typed model.
40+
- The ability to retrieve by column name instead of by column index.
41+
- Authentication with Azure Active Directory (Azure AD) credentials using [`Azure.Identity`](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity#readme).
42+
43+
For more new features, changes, and bug fixes, see the [CHANGELOG](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.Query_1.0.1/sdk/monitor/Azure.Monitor.Query/CHANGELOG.md).
44+
45+
## Important changes
46+
47+
### The client
48+
49+
To provide a more intuitive experience, the top-level client to query logs was renamed to `LogsQueryClient` from `ApplicationInsightsDataClient`. `LogsQueryClient` can be authenticated using Azure AD. This client is the single entry point to execute a single Kusto query or a batch of Kusto queries.
50+
51+
#### Consistency
52+
53+
There are now methods with similar names, signatures, and locations to create senders and receivers. The result is consistency and predictability on the various features of the library.
54+
55+
### Client constructors and authentication
56+
57+
In `Microsoft.Azure.ApplicationInsights.Query` v1.0.0:
58+
59+
```csharp
60+
using Microsoft.Azure.ApplicationInsights.Query;
61+
using Microsoft.Rest;
62+
using Microsoft.Rest.Azure.Authentication;
63+
64+
// code omitted for brevity
65+
66+
var adSettings = new ActiveDirectoryServiceSettings
67+
{
68+
AuthenticationEndpoint = new Uri("https://login.microsoftonline.com"),
69+
TokenAudience = new Uri("https://api.loganalytics.io/"),
70+
ValidateAuthority = true
71+
};
72+
73+
ServiceClientCredentials credentials = ApplicationTokenProvider.LoginSilentAsync(
74+
"<domainId or tenantId>", "<clientId>", "<clientSecret>", adSettings).GetAwaiter().GetResult();
75+
var client = new ApplicationInsightsDataClient(credentials);
76+
```
77+
78+
In `Azure.Monitor.Query` v1.0.x:
79+
80+
```csharp
81+
using Azure.Identity;
82+
using Azure.Monitor.Query;
83+
84+
// code omitted for brevity
85+
86+
var credential = new ClientSecretCredential("<domainId or tenantId>", "<clientId>", "<clientSecret>");
87+
var client = new LogsQueryClient(credential);
88+
```
89+
90+
### Send a single query request
91+
92+
In `Microsoft.Azure.ApplicationInsights.Query` v1.0.0:
93+
94+
```csharp
95+
using Microsoft.Azure.ApplicationInsights.Query.Models
96+
97+
// code omitted for brevity
98+
QueryResults results = await client.Query.ExecuteAsync("<appId>", "AzureActivity | top 10 by TimeGenerated");
99+
```
100+
101+
In `Azure.Monitor.Query` v1.0.x:
102+
103+
- The `QueryBody` is flattened. Users are expected to pass the Kusto query directly to the API.
104+
- The `timespan` parameter is now required, which helps to avoid querying over the entire data set.
105+
106+
```csharp
107+
using Azure;
108+
using Azure.Monitor.Query;
109+
using Azure.Monitor.Query.Models;
110+
111+
// code omitted for brevity
112+
113+
Response<LogsQueryResult> response = await client.QueryWorkspaceAsync(
114+
workspaceId,
115+
"AzureActivity | top 10 by TimeGenerated",
116+
new QueryTimeRange(TimeSpan.FromDays(1)));
117+
```
118+
119+
### A note about the Events API
120+
121+
The `Microsoft.Azure.ApplicationInsights.Query` package includes an Events API, which is just a different "API head" on the same logs data. It enables the querying of some logs in Application Insights without writing Kusto queries. The API translates to Kusto queries in the background. The same data can be accessed via regular Kusto queries, as shown in the preceding example.
122+
123+
### Query metrics from a resource
124+
125+
In `Microsoft.Azure.ApplicationInsights.Query` v1.0.0:
126+
127+
```csharp
128+
using Microsoft.Azure.ApplicationInsights.Query.Models;
129+
130+
// code omitted for brevity
131+
132+
MetricsResult result = client.Metrics.GetAsync("<appId>", "<metricId>").Result;
133+
```
134+
135+
In `Azure.Monitor.Query` v1.0.x:
136+
137+
```csharp
138+
using Azure.Identity;
139+
using Azure.Monitor.Query;
140+
using Azure.Monitor.Query.Models;
141+
142+
// code omitted for brevity
143+
144+
var credential = new ClientSecretCredential("<domainId or tenantId>", "<clientId>", "<clientSecret>");
145+
var client = new MetricsQueryClient(credential);
146+
MetricsQueryResult result = await client.QueryResourceAsync("<resourceId>", new[]{ "<metricName>" }).Value;
147+
```
148+
149+
## Additional samples
150+
151+
For more examples, see [Samples for Azure.Monitor.Query](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/monitor/Azure.Monitor.Query#examples).

sdk/monitor/Azure.Monitor.Query/MigrationGuide.md renamed to sdk/monitor/Azure.Monitor.Query/MigrationGuideOperationalInsights.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ QueryResults response = await client.QueryAsync("AzureActivity | top 10 by TimeG
102102
In `Azure.Monitor.Query` v1.0.x:
103103

104104
- The `QueryBody` is flattened. Users are expected to pass the Kusto query directly to the API.
105-
- The `timespan` attribute is now required, which helped to avoid querying over the entire data set.
105+
- The `timespan` parameter is now required, which helps to avoid querying over the entire data set.
106106

107107
```csharp
108108
using Azure;

‎sdk/monitor/Azure.Monitor.Query/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ The Azure Monitor Query client library is used to execute read-only queries agai
1212
- [API reference documentation][msdocs_apiref]
1313
- [Service documentation][azure_monitor_overview]
1414
- [Change log][changelog]
15-
- [Migration guide][migration_guide]
15+
- [Migration guide from Application Insights][migration_guide_app_insights]
16+
- [Migration guide from Operational Insights][migration_guide_opp_insights]
1617

1718
## Getting started
1819

@@ -426,7 +427,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
426427
[changelog]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/monitor/Azure.Monitor.Query/CHANGELOG.md
427428
[kusto_query_language]: https://docs.microsoft.com/azure/data-explorer/kusto/query/
428429
[logging]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md
429-
[migration_guide]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/monitor/Azure.Monitor.Query/MigrationGuide.md
430+
[migration_guide_app_insights]: https://aka.ms/azsdk/net/migrate/ai-monitor-query
431+
[migration_guide_opp_insights]: https://aka.ms/azsdk/net/migrate/monitor-query
430432
[monitor_rest_api]: https://docs.microsoft.com/rest/api/monitor/
431433
[msdocs_apiref]: https://docs.microsoft.com/dotnet/api/overview/azure/monitor/query?view=azure-dotnet
432434
[package]: https://www.nuget.org/packages/Azure.Monitor.Query

0 commit comments

Comments
 (0)