Azure Monitor Workspace query client library for JavaScript

Azure Monitor is a comprehensive solution for collecting, analyzing, and acting on telemetry from your cloud and on-premises environments.

Use the client library for Azure Monitor to:

• Query logs using the Kusto query language
• Query metrics

Source code | Package (NPM) | [API reference documentation] | Product documentation Samples

Getting started

Install the package

npm install @azure/monitor-query

Prerequisites

• You must have an Azure Subscription and an Azure Monitor resource to use this package.
• Node.js version 8.x.x or higher

Create an Azure Monitor resource

You can use the Azure Portal or the Azure CLI to create an Azure Monitor resource.

Instructions:

• Using the Azure Portal
• Using the Azure CLI

Authenticate the client

[LogsQueryClient] and [MetricsQueryClient] authenticate using a service principal.

Authenticating with a service principal

Authentication via service principal is done by:

• Creating a credential using the @azure/identity package.
• Setting appropriate RBAC rules on your Azure Monitor resource. More information on Azure Monitor roles can be found here.

Using DefaultAzureCredential

const { DefaultAzureCredential } = require("@azure/identity");
const { LogsQueryClient, MetricsQueryClient } = require("@azure/monitor-query");

const credential = new DefaultAzureCredential();

const logsQueryClient = new LogsQueryClient(credential);
// or
const metricsQueryClient = new MetricsQueryClient(credential);

More information about @azure/identity can be found here

Key concepts

The [LogsQueryClient] allows you to query logs, using the Kusto query language. This data can be queried in the portal using tables like AppEvents, AppDependencies and others.

The [MetricsQueryClient] allows you to query metrics.

Examples

Querying logs

The LogsQueryClient can be used to query a Monitor workspace using the Kusto Query language.

const { LogsQueryClient } = require("@azure/monitor-query");
const { DefaultAzureCredential } = require("@azure/identity");

const azureLogAnalyticsWorkspaceId = "<the Workspace Id for your Azure Log Analytics resource>";
const logsQueryClient = new LogsQueryClient(new DefaultAzureCredential());

async function run() {
  const kustoQuery = "AppEvents | limit 1";
  const result = await logsQueryClient.queryLogs(azureLogAnalyticsWorkspaceId, kustoQuery);
  const tablesFromResult = result.tables;

  if (tablesFromResult == null) {
    console.log(`No results for query '${kustoQuery}'`);
    return;
  }

  console.log(`Results for query '${kustoQuery}'`);

  for (const table of tablesFromResult) {
    const columnHeaderString = table.columns
      .map((column) => `${column.name}(${column.type}) `)
      .join("| ");
    console.log("| " + columnHeaderString);

    for (const row of table.rows) {
      const columnValuesString = row.map((columnValue) => `'${columnValue}' `).join("| ");
      console.log("| " + columnValuesString);
    }
  }
}
run().catch((err) => console.log("ERROR:", err));

For more samples see here: samples.

Troubleshooting

Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.

Next steps

The following samples show you the various ways you can query your Log Analytics workspace:

• [logsQuery.ts] - Query logs in a Monitor workspace
• [logsQueryBatchSample.ts] - Run multiple queries, simultaneously, with a batch in a Monitor workspace
• [metricsQuerySample.ts] - Query metrics in a Monitor workspace

More in-depth examples can be found in the samples folder on GitHub.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

This module's tests are a mixture of live and unit tests, which require you to have an Azure Monitor instance. To execute the tests you'll need to run:

1. rush update
2. rush build -t @azure/monitor-query
3. cd into sdk/monitor/monitor-query
4. Copy the sample.env file to .env
5. Open the .env file in an editor and fill in the values.
6. npm run test.

View our tests folder for more details.

Related projects

• Microsoft Azure SDK for JavaScript
• Azure Monitor