Azure Metrics Advisor-clientbibliotheek voor JavaScript - versie 1.0.0

Artikel
04/05/2023

Metrics Advisor is een onderdeel van Azure Cognitive Services dat AI gebruikt voor het uitvoeren van gegevensbewaking en anomaliedetectie in tijdreeksgegevens. De service automatiseert het proces van het toepassen van modellen op uw gegevens en biedt een werkruimte met een set web-API's voor gegevensopname, anomaliedetectie en diagnoses. Hiervoor is geen kennis van machine learning vereist. Met Metrics Advisor kunt u:

Multidimensionale gegevens van meerdere gegevensbronnen analyseren
Anomalieën identificeren en correleren
Het anomaliedetectiemodel dat wordt gebruikt voor uw gegevens configureren en afstemmen
Anomalieën diagnosticeren en helpen bij hoofdoorzaakanalsye.

Belangrijke koppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

LTS-versies van Node.js
Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

Een Azure-abonnement.
Een bestaande Cognitive Services - of Metrics Advisor-resource. Als u de resource wilt maken, kunt u azure portal of Azure CLI gebruiken.

Als u de Azure CLI gebruikt, vervangt u en <your-resource-name> door <your-resource-group-name> uw eigen unieke namen:

az cognitiveservices account create --kind MetricsAdvisor --resource-group <your-resource-group-name> --name <your-resource-name> --sku <sku level> --location <location>

Installeer het pakket `@azure/ai-metrics-advisor`

Installeer de Azure Metrics Advisor-clientbibliotheek voor JavaScript met npm:

npm install @azure/ai-metrics-advisor

Maken en verifiëren `MetricsAdvisorClient` of `MetricsAdvisorAdministrationClient`

Als u een clientobject wilt maken voor toegang tot de Metrics Advisor-API, hebt u de endpoint van uw Metrics Advisor-resource en een credentialnodig. De Metrics Advisor-clients gebruiken een Metrics Advisor-sleutelreferentie om te verifiëren.

U vindt het eindpunt voor uw Metrics Advisor-resource in de Azure-portal of met behulp van het azure CLI-fragment hieronder:

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Abonnementssleutel en API-sleutel gebruiken

U hebt twee sleutels nodig om de client te verifiëren:

De abonnementssleutel voor uw Metrics Advisor-resource. U vindt dit in de sectie Sleutels en eindpunten van uw resource in Azure Portal.
De API-sleutel voor uw Metrics Advisor-exemplaar. U vindt deze in de webportal voor Metrics Advisor, in API-sleutels in het navigatiemenu aan de linkerkant. De URL van uw webportal vindt u in de sectie Overzicht van uw resource in Azure Portal.

Gebruik Azure Portal om naar uw Metrics Advisor-resource te bladeren en een abonnementssleutel op te halen, of gebruik het onderstaande Azure CLI-fragment :

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Daarnaast hebt u ook de API-sleutel per gebruiker nodig van uw Metrics Advisor-webportal.

Zodra u de twee sleutels en het eindpunt hebt, kunt u de MetricsAdvisorKeyCredential klasse gebruiken om de clients als volgt te verifiëren:

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorClient,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

const credential = new MetricsAdvisorKeyCredential("<subscription Key>", "<API key>");

const client = new MetricsAdvisorClient("<endpoint>", credential);
const adminClient = new MetricsAdvisorAdministrationClient("<endpoint>", credential);

Azure Service Directory gebruiken

Autorisatie van API-sleutels wordt in de meeste voorbeelden gebruikt, maar u kunt de client ook verifiëren met Azure Active Directory met behulp van de Azure Identity-bibliotheek. Als u de DefaultAzureCredential-provider wilt gebruiken die hieronder wordt weergegeven of als u andere referentieproviders wilt gebruiken die bij de Azure SDK worden geleverd, installeert u het @azure/identity pakket:

npm install @azure/identity

Als u wilt verifiëren met behulp van een service-principal, moet u ook een AAD-toepassing registreren en toegang verlenen tot Metrics Advisor door de rol 'Cognitive Services-gebruiker' toe te wijzen aan uw service-principal (opmerking: andere rollen zoals 'Eigenaar' verlenen niet de benodigde machtigingen, alleen 'Cognitive Services-gebruiker' is voldoende om de voorbeelden en de voorbeeldcode uit te voeren).

Stel de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET. We ondersteunen ook verificatie door Azure Active Directoty Credential. U hebt de Azure-tenant-id, De Azure-client-id en het Azure-clientgeheim nodig als omgevingsvariabelen.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorClient,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");
import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
const client = new MetricsAdvisorClient("<endpoint>", credential);
const adminClient = new MetricsAdvisorAdministrationClient("<endpoint>", credential);

Belangrijkste concepten

MetricsAdvisorClient

MetricsAdvisorClient is de primaire interface voor het uitvoeren van query's voor ontwikkelaars die gebruikmaken van de Metrics Advisor-clientbibliotheek. Het biedt asynchrone methoden voor toegang tot een specifiek gebruik van Metrics Advisor, zoals het vermelden van incidenten, het ophalen van hoofdoorzaken van incidenten, het ophalen van oorspronkelijke tijdreeksgegevens en tijdreeksgegevens die door de service zijn verrijkt.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient is de interface die verantwoordelijk is voor het beheren van entiteiten in de Metrics Advisor-resources, zoals het beheren van gegevensfeeds, configuraties voor anomaliedetectie en configuraties voor anomaliewaarschuwingen.

Gegevensfeed

Een gegevensfeed is wat Metrics Advisor opneemt uit uw gegevensbron, zoals Cosmos DB of een SQL-server. Een gegevensfeed bevat rijen van:

Tijdstempels
nul of meer dimensies
een of meer metingen

Metrisch

Een metrische waarde is een meetbare meting die wordt gebruikt om de status van een specifiek bedrijfsproces te bewaken en te beoordelen. Dit kan een combinatie zijn van meerdere tijdreekswaarden, onderverdeeld in dimensies. Een metrisch gegeven dat de status van het web aangeeft, kan bijvoorbeeld dimensies bevatten voor het aantal gebruikers en voor het en-us-taalgebied.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration is vereist voor elke tijdreeks en bepaalt of een punt in de tijdreeks een anomalie is.

Incident met anomalie &

Nadat een detectieconfiguratie is toegepast op metrische gegevens, AnomalyIncidentworden s gegenereerd wanneer een reeks erin een DataPointAnomalyheeft.

Waarschuwing

U kunt configureren welke afwijkingen een AnomalyAlertmoeten activeren. U kunt meerdere waarschuwingen met verschillende instellingen instellen. U kunt bijvoorbeeld een waarschuwing maken voor afwijkingen met een lagere bedrijfsimpact en een andere voor belangrijkere waarschuwingen.

Haak

Met Metrics Advisor kunt u realtime waarschuwingen maken en erop abonneren. Deze waarschuwingen worden via internet verzonden met behulp van een meldingshook.

Raadpleeg de documentatiepagina Metrische advieswoordenlijst voor een uitgebreide lijst met concepten.

Voorbeelden

De volgende sectie bevat verschillende JavaScript-codefragmenten die veelvoorkomende patronen illustreren die worden gebruikt in de Metrics Advisor-clientbibliotheken.

Een gegevensfeed uit een voorbeeldgegevensbron toevoegen
Opnamestatus controleren
Configuratie voor anomaliedetectie configureren
Hooks toevoegen voor het ontvangen van anomaliewaarschuwingen
Waarschuwingsconfiguratie configureren
Resultaten van anomaliedetectie opvragen

Een gegevensfeed uit een voorbeeldgegevensbron toevoegen

Metrics Advisor biedt ondersteuning voor het met elkaar verbinden van verschillende typen gegevensbronnen. Hier volgt een voorbeeld van het opnemen van gegevens uit SQL Server.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const sqlServerConnectionString =
    process.env["METRICS_ADVISOR_SQL_SERVER_CONNECTION_STRING"] ||
    "<connection string to SQL Server>";
  const sqlServerQuery =
    process.env["METRICS_ADVISOR_AZURE_SQL_SERVER_QUERY"] || "<SQL Server query to retrive data>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);

  const created = await createDataFeed(adminClient, sqlServerConnectionString, sqlServerQuery);
  console.log(`Data feed created: ${created.id}`);
}

async function createDataFeed(adminClient, sqlServerConnectionString, sqlServerQuery) {
  console.log("Creating Datafeed...");
  const dataFeed = {
    name: "test_datafeed_" + new Date().getTime().toString(),
    source: {
      dataSourceType: "SqlServer",
      connectionString: sqlServerConnectionString,
      query: sqlServerQuery,
      authenticationType: "Basic"
    },
    granularity: {
      granularityType: "Daily"
    },
    schema: {
      metrics: [
        {
          name: "revenue",
          displayName: "revenue",
          description: "Metric1 description"
        },
        {
          name: "cost",
          displayName: "cost",
          description: "Metric2 description"
        }
      ],
      dimensions: [
        { name: "city", displayName: "city display" },
        { name: "category", displayName: "category display" }
      ],
      timestampColumn: null
    },
    ingestionSettings: {
      ingestionStartTime: new Date(Date.UTC(2020, 5, 1)),
      ingestionStartOffsetInSeconds: 0,
      dataSourceRequestConcurrency: -1,
      ingestionRetryDelayInSeconds: -1,
      stopRetryAfterInSeconds: -1
    },
    rollupSettings: {
      rollupType: "AutoRollup",
      rollupMethod: "Sum",
      rollupIdentificationValue: "__CUSTOM_SUM__"
    },
    missingDataPointFillSettings: {
      fillType: "SmartFilling"
    },
    accessMode: "Private",
    admins: ["xyz@example.com"]
  };
  const result = await adminClient.createDataFeed(dataFeed);

  return result;
}

Opnamestatus controleren

Nadat de gegevensopname is gestart, kunt u de opnamestatus controleren.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const dataFeedId = process.env["METRICS_DATAFEED_ID"] || "<data feed id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  await checkIngestionStatus(
    adminClient,
    dataFeedId,
    new Date(Date.UTC(2020, 8, 1)),
    new Date(Date.UTC(2020, 8, 12))
  );
}

async function checkIngestionStatus(adminClient, datafeedId, startTime, endTime) {
  // This shows how to use for-await-of syntax to list status
  console.log("Checking ingestion status...");
  const iterator = adminClient.listDataFeedIngestionStatus(datafeedId, startTime, endTime);
  for await (const status of iterator) {
    console.log(`  [${status.timestamp}] ${status.status} - ${status.message}`);
  }
}

Configuratie van anomaliedetectie configureren

Er is een anomaliedetectieconfiguratie vereist om te bepalen of een punt in de tijdreeks een anomalie is. Hoewel er op elk metrisch gegeven automatisch een standaard detectieconfiguratie wordt toegepast, kunt u de detectiemodi die op uw gegevens worden gebruikt, afstemmen door een aangepaste anomaliedetectieconfiguratie te maken.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const metricId = process.env["METRICS_ADVISOR_METRIC_ID"] || "<metric id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);

  const detectionConfig = await configureAnomalyDetectionConfiguration(adminClient, metricId);
  console.log(`Detection configuration created: ${detectionConfig.id}`);
}

async function configureAnomalyDetectionConfiguration(adminClient, metricId) {
  console.log(`Creating an anomaly detection configuration on metric '${metricId}'...`);
  const anomalyConfig = {
    name: "test_detection_configuration" + new Date().getTime().toString(),
    metricId,
    wholeSeriesDetectionCondition: {
      smartDetectionCondition: {
        sensitivity: 100,
        anomalyDetectorDirection: "Both",
        suppressCondition: {
          minNumber: 1,
          minRatio: 1
        }
      }
    },
    description: "Detection configuration description"
  };
  return await adminClient.createDetectionConfig(anomalyConfig);
}

Hooks toevoegen voor het ontvangen van anomaliewaarschuwingen

We gebruiken hooks abonneren op realtime waarschuwingen. In dit voorbeeld maken we een webhook voor de Metrics Advisor-service waar de waarschuwing moet worden geplaatst.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  const hook = await createWebhookHook(adminClient);
  console.log(`Webhook hook created: ${hook.id}`);
}

async function createWebhookHook(adminClient) {
  console.log("Creating a webhook hook");
  const hook = {
    hookType: "Webhook",
    name: "web hook " + new Date().getTime().toString(),
    description: "description",
    hookParameter: {
      endpoint: "https://example.com/handleAlerts",
      username: "username",
      password: "password"
      // certificateKey: "certificate key",
      // certificatePassword: "certificate password"
    }
  };

  return await adminClient.createHook(hook);
}

Configuratie van waarschuwingen configureren

Vervolgens gaan we configureren in welke voorwaarden een waarschuwing moet worden geactiveerd en welke hooks de waarschuwing moeten verzenden.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const detectionConfigId = process.env["METRICS_ADVISOR_DETECTION_CONFIG_ID"] || "<detection id>";
  const hookId = process.env["METRICS_ADVISOR_HOOK_ID"] || "<hook id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  const alertConfig = await configureAlertConfiguration(adminClient, detectionConfigId, [hookId]);
  console.log(`Alert configuration created: ${alertConfig.id}`);
}

async function configureAlertConfiguration(adminClient, detectionConfigId, hookIds) {
  console.log("Creating a new alerting configuration...");
  const anomalyAlertConfig = {
    name: "test_alert_config_" + new Date().getTime().toString(),
    crossMetricsOperator: "AND",
    metricAlertConfigurations: [
      {
        detectionConfigurationId: detectionConfigId,
        alertScope: {
          scopeType: "All"
        },
        alertConditions: {
          severityCondition: { minAlertSeverity: "Medium", maxAlertSeverity: "High" }
        },
        snoozeCondition: {
          autoSnooze: 0,
          snoozeScope: "Metric",
          onlyForSuccessive: true
        }
      }
    ],
    hookIds,
    description: "Alerting config description"
  };
  return await adminClient.createAlertConfig(anomalyAlertConfig);
}

Query's uitvoeren op de anomaliedetectieresultaten

We kunnen een query uitvoeren op de waarschuwingen en afwijkingen.

const { MetricsAdvisorKeyCredential, MetricsAdvisorClient } = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const alertConfigId = process.env["METRICS_ADVISOR_ALERT_CONFIG_ID"] || "<alert config id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const client = new MetricsAdvisorClient(endpoint, credential);

  const alerts = await queryAlerts(
    client,
    alertConfigId,
    new Date(Date.UTC(2020, 8, 1)),
    new Date(Date.UTC(2020, 8, 12))
  );

  if (alerts.length > 1) {
    // query anomalies using an alert id.
    await queryAnomaliesByAlert(client, alerts[0]);
  } else {
    console.log("No alerts during the time period");
  }
}

async function queryAlerts(client, alertConfigId, startTime, endTime) {
  let alerts = [];
  const iterator = client.listAlerts(alertConfigId, startTime, endTime, "AnomalyTime");
  for await (const alert of iterator) {
    alerts.push(alert);
  }

  return alerts;
}

async function queryAnomaliesByAlert(client, alert) {
  console.log(
    `Listing anomalies for alert configuration '${alert.alertConfigId}' and alert '${alert.id}'`
  );
  const iterator = client.listAnomaliesForAlert(alert);
  for await (const anomaly of iterator) {
    console.log(
      `  Anomaly ${anomaly.severity} ${anomaly.status} ${anomaly.seriesKey} ${anomaly.timestamp}`
    );
  }
}

Problemen oplossen

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. Logboekregistratie kan ook worden ingeschakeld tijdens runtime door aan te roepen setLogLevel in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.

Volgende stappen

Bekijk de map met voorbeelden voor gedetailleerde voorbeelden van het gebruik van deze bibliotheek.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de handleiding voor bijdragen voor meer informatie over het bouwen en testen
de code.

Microsoft Azure SDK voor Javascript

Weergaven

Delen via

Azure Metrics Advisor-clientbibliotheek voor JavaScript - versie 1.0.0

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

Installeer het pakket `@azure/ai-metrics-advisor`

Maken en verifiëren `MetricsAdvisorClient` of `MetricsAdvisorAdministrationClient`

Abonnementssleutel en API-sleutel gebruiken

Azure Service Directory gebruiken

Belangrijkste concepten

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Gegevensfeed

Metrisch

AnomalyDetectionConfiguration

Incident met anomalie &

Waarschuwing

Haak

Voorbeelden

Een gegevensfeed uit een voorbeeldgegevensbron toevoegen

Opnamestatus controleren

Configuratie van anomaliedetectie configureren

Hooks toevoegen voor het ontvangen van anomaliewaarschuwingen

Configuratie van waarschuwingen configureren

Query's uitvoeren op de anomaliedetectieresultaten

Problemen oplossen

Logboekregistratie

Volgende stappen

Bijdragen

Feedback

Aanvullende resources

Delen via

Azure Metrics Advisor-clientbibliotheek voor JavaScript - versie 1.0.0

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

Installeer het pakket @azure/ai-metrics-advisor

Maken en verifiëren MetricsAdvisorClient of MetricsAdvisorAdministrationClient

Abonnementssleutel en API-sleutel gebruiken

Azure Service Directory gebruiken

Belangrijkste concepten

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Gegevensfeed

Metrisch

AnomalyDetectionConfiguration

Incident met anomalie &

Waarschuwing

Haak

Voorbeelden

Een gegevensfeed uit een voorbeeldgegevensbron toevoegen

Opnamestatus controleren

Configuratie van anomaliedetectie configureren

Hooks toevoegen voor het ontvangen van anomaliewaarschuwingen

Configuratie van waarschuwingen configureren

Query's uitvoeren op de anomaliedetectieresultaten

Problemen oplossen

Logboekregistratie

Volgende stappen

Bijdragen

Verwante projecten

Feedback

Aanvullende resources

Installeer het pakket `@azure/ai-metrics-advisor`

Maken en verifiëren `MetricsAdvisorClient` of `MetricsAdvisorAdministrationClient`