|
| 1 | +# Guide for migrating to `azure-monitor-query` from `azure-loganalytics` |
| 2 | + |
| 3 | +This guide assists in migrating from `azure-loganalytics` to `azure-monitor-query`. |
| 4 | + |
| 5 | +## Migration benefits |
| 6 | + |
| 7 | +A natural question to ask when considering whether or not to adopt a new version or library is its benefits. As Azure has matured and been embraced by a more diverse group of developers, we have been |
| 8 | +focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the Java client libraries have. |
| 9 | + |
| 10 | +There were several areas of consistent feedback expressed across the Azure client library ecosystem. The most important is that the client libraries for different Azure services have not had a |
| 11 | +consistent organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent |
| 12 | +onboarding story for those learning Azure or exploring a specific Azure service. |
| 13 | + |
| 14 | +To improve the development experience across Azure services, a set of uniform [design guidelines][Guidelines] was created for all languages to drive a |
| 15 | +consistent experience with established API patterns for all services. A set of [Java design guidelines][GuidelinesJava] was introduced to ensure that Java clients have a natural and idiomatic feel |
| 16 | +with respect to the Java ecosystem. Further details are available in the guidelines for those interested. |
| 17 | + |
| 18 | +In addition to the improved development experience, the new `azure-monitor-query` also has new features that are not available in `azure-loganalytics`. This library supports querying Azure Monitor for |
| 19 | +both logs and metrics while the `azure-loganalytics` library only supported querying logs. The new library also includes additional capabilities for querying logs like executing a batch of queries, |
| 20 | +setting the server timeout, getting the visualization information and statistics for a query. |
| 21 | + |
| 22 | +Another key difference is that `azure-loganalytics` only has a preview release. It's not recommended for use in a production environment. The `azure-monitor-query` package has a stable release. The latest stable version can be found in the [README][README]. |
| 23 | + |
| 24 | +### Cross-service SDK improvements |
| 25 | + |
| 26 | +The modern Azure Monitor Query client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience. Some improvements include: |
| 27 | + |
| 28 | +- A unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries. |
| 29 | +- A unified asynchronous programming model using [Project Reactor][project-reactor]. |
| 30 | +- A unified method of creating clients via client builders to interact with Azure services. |
| 31 | + |
| 32 | +## Important changes |
| 33 | + |
| 34 | +### Group ID, artifact ID, and package names |
| 35 | + |
| 36 | +Group IDs, artifact IDs, and package names for the modern Azure client libraries for Java have changed. They follow the [Java SDK naming guidelines][GuidelinesJavaDesign]. Each will have the group ID `com.azure`, an artifact ID following the pattern `azure-[area]-[service]`, and the root package name `com.azure.[area].[Service]`. The legacy clients have a group ID of `com.microsoft.azure`, and their package names followed the pattern `com.microsoft. Azure.[service]`. This provides a quick and accessible means to help understand, at a glance, whether you're using modern or legacy clients. |
| 37 | + |
| 38 | +The Azure Monitor Query client library's package and namespaces begin with `com.azure.monitor.query` and were released starting with version 1.0.0. The legacy client library had a package name starting with `com.microsoft.azure.loganalytics` and a version of 1.0.0-beta.1. |
| 39 | + |
| 40 | +#### Instantiate clients |
| 41 | + |
| 42 | +In `azure-loganalytics`, the `LogAnalyticsDataClient` is instantiated via the `LogAnalyticsDataClientImpl` constructor. The client contains both sync and async methods. |
| 43 | + |
| 44 | +```java |
| 45 | +// ApplicationTokenCredentials work well for service principal authentication |
| 46 | +ApplicationTokenCredentials credentials = new ApplicationTokenCredentials( |
| 47 | + "<clientId>", |
| 48 | + "<tenantId>", |
| 49 | + "<clientSecret>", |
| 50 | + AzureEnvironment.AZURE |
| 51 | + ); |
| 52 | + |
| 53 | +// New up client. Accepts credentials, or a pre-authenticated restClient |
| 54 | +LogAnalyticsDataClient client = new LogAnalyticsDataClientImpl(credentials); |
| 55 | +``` |
| 56 | + |
| 57 | +In `azure-monitor-query`: |
| 58 | + |
| 59 | +- The creation of the client is done through the [LogsQueryClientBuilder][LogsQueryClientBuilder]. The sync and async operations are separated to [LogsQueryClient] and [LogsQueryAsyncClient]. |
| 60 | +- The authentication is done through `TokenCredential`. There are several `TokenCredential` types implemented in the `azure-identity` library that support Azure AD auth. For more details on `azure-identity`, see the [Azure Identity README][azure-identity-readme]. |
| 61 | + |
| 62 | +***Create a sync client*** |
| 63 | +```java |
| 64 | +TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build(); |
| 65 | +LogsQueryClient logsQueryClient = new LogsQueryClientBuilder() |
| 66 | + .credential(tokenCredential) |
| 67 | + .buildClient(); |
| 68 | +``` |
| 69 | + |
| 70 | +***Create an async client*** |
| 71 | +```java |
| 72 | +TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build(); |
| 73 | +LogsQueryAsyncClient logsQueryAsyncClient = new LogsQueryClientBuilder() |
| 74 | + .credential(tokenCredential) |
| 75 | + .buildAsyncClient(); |
| 76 | +``` |
| 77 | + |
| 78 | +#### Query logs synchronously |
| 79 | +In `azure-loganalytics`, logs can be queried synchronously as shown below: |
| 80 | + |
| 81 | +```java |
| 82 | +String query = "Heartbeat | take 1"; |
| 83 | +String workspaceId = "<workspace-id>"; |
| 84 | +QueryResults queryResults = logAnalyticsClient.query(workspaceId, new QueryBody().withQuery(query)); |
| 85 | +``` |
| 86 | + |
| 87 | +In `azure-monitor-query`, logs can be queried synchronously using the sync client as shown below: |
| 88 | + |
| 89 | +```java |
| 90 | +String query = "Heartbeat | take 1"; |
| 91 | +String workspaceId = "<workspace-id>"; |
| 92 | +LogsQueryResult queryResults = logsQueryClient.queryWorkspace(workspaceId, query, QueryTimeInterval.ALL); |
| 93 | +``` |
| 94 | + |
| 95 | +#### Query logs asynchronously |
| 96 | +In `azure-loganalytics`, logs can be queried asynchronously as shown below: |
| 97 | + |
| 98 | +```java |
| 99 | +String query = "Heartbeat | take 1"; |
| 100 | +String workspaceId = "<workspace-id>"; |
| 101 | +Observable<QueryResults> queryResultsObservable = logAnalyticsClient.queryAsync(workspaceId, new QueryBody().withQuery(query)); |
| 102 | +queryResultsObservable.subscribe(queryResults -> { |
| 103 | + // process results |
| 104 | + queryResults.tables(); |
| 105 | + }); |
| 106 | +``` |
| 107 | + |
| 108 | +In `azure-monitor-query`, logs can be queried synchronously using the sync client as shown below: |
| 109 | + |
| 110 | +```java |
| 111 | +String query = "Heartbeat | take 1"; |
| 112 | +String workspaceId = "<workspace-id>"; |
| 113 | +Mono<LogsQueryResult> queryResultsMono = logsQueryAsyncClient.queryWorkspace(workspaceId, query, QueryTimeInterval.ALL); |
| 114 | +queryResultsMono.subscribe(queryResult -> { |
| 115 | + // process results |
| 116 | + queryResult.getAllTables(); |
| 117 | + }); |
| 118 | +``` |
| 119 | + |
| 120 | +## Additional samples |
| 121 | + |
| 122 | +More examples can be found at [Azure Monitor Query samples][README-Samples]. |
| 123 | + |
| 124 | +<!-- Links --> |
| 125 | +[LogsQueryClientBuilder]: https://azuresdkdocs.blob.core.windows.net/$web/java/azure-monitor-query/latest/com/azure/monitor/query/LogsQueryClientBuilder.html |
| 126 | +[LogsQueryClient]: https://azuresdkdocs.blob.core.windows.net/$web/java/azure-monitor-query/latest/com/azure/monitor/query/LogsQueryClient.html |
| 127 | +[LogsQueryAsyncClient]: https://azuresdkdocs.blob.core.windows.net/$web/java/azure-monitor-query/latest/com/azure/monitor/query/LogsQueryAsyncClient.html |
| 128 | +[Guidelines]: https://azure.github.io/azure-sdk/general_introduction.html |
| 129 | +[GuidelinesJava]: https://azure.github.io/azure-sdk/java_introduction.html |
| 130 | +[GuidelinesJavaDesign]: https://azure.github.io/azure-sdk/java_introduction.html#namespaces |
| 131 | +[project-reactor]: https://projectreactor.io/ |
| 132 | +[README-Samples]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-query/src/samples/java/README.md |
| 133 | +[README]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-query/README.md |
| 134 | +[azure-identity-readme]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/identity/azure-identity/README.md |
| 135 | + |
| 136 | + |
0 commit comments