Package: azure-ai-metricsadvisor
Azure Metrics Advisor client library for PythonMetrics Advisor is a scalable real-time time series monitoring, alerting, and root cause analysis platform. Use Metrics Advisor to:Analyze multi-dimensional data from multiple data sourcesIdentify and correlate anomaliesConfigure and fine-tune the anomaly detection model used on your dataDiagnose anomalies and help with root cause analysisSource code|Package (Pypi)|API reference documentation|Product documentation|SamplesGetting startedInstall the packageInstall the Azure Metrics Advisor client library for Python with pip:pip install azure-ai-metricsadvisor --prePrerequisitesPython 2.7, or 3.6 or later is required to use this package.You need anAzure subscription, and aMetrics Advisor serivceto use this package.Authenticate the clientYou will need two keys to authenticate the client:The subscription key to your Metrics Advisor resource. You can find this in the Keys and Endpoint section of your resource in the Azure portal.The API key for your Metrics Advisor instance. You can find this in the web portal for Metrics Advisor, in API keys on the left navigation menu.We can use the keys to create a newMetricsAdvisorClientorMetricsAdvisorAdministrationClient.importosfromazure.ai.metricsadvisorimport(MetricsAdvisorKeyCredential,MetricsAdvisorClient,MetricsAdvisorAdministrationClient,)service_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")client=MetricsAdvisorClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))admin_client=MetricsAdvisorAdministrationClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))Key conceptsMetricsAdvisorClientMetricsAdvisorClienthelps with:listing incidentslisting root causes of incidentsretrieving original time series data and time series data enriched by the service.listing alertsadding feedback to tune your modelMetricsAdvisorAdministrationClientMetricsAdvisorAdministrationClientallows you tomanage data feedsmanage anomaly detection configurationsmanage anomaly alerting configurationsmanage hooksDataFeedADataFeedis what Metrics Advisor ingests from your data source, such as Cosmos DB or a SQL server. A data feed contains rows of:timestampszero or more dimensionsone or more measuresMetricADataFeedMetricis a quantifiable measure that is used to monitor and assess the status of a specific business process. It can be a combination of multiple time series values divided into dimensions. For example a web health metric might contain dimensions for user count and the en-us market.AnomalyDetectionConfigurationAnomalyDetectionConfigurationis required for every time series, and determines whether a point in the time series is an anomaly.Anomaly & IncidentAfter a detection configuration is applied to metrics,AnomalyIncidents are generated whenever any series within it has anDataPointAnomaly.AlertYou can configure which anomalies should trigger anAnomalyAlert. You can set multiple alerts with different settings. For example, you could create an alert for anomalies with lower business impact, and another for more important alerts.Notification HookMetrics Advisor lets you create and subscribe to real-time alerts. These alerts are sent over the internet, using a notification hook likeEmailNotificationHookorWebNotificationHook.ExamplesAdd a data feed from a sample or data sourceCheck ingestion statusConfigure anomaly detection configurationConfigure alert configurationQuery anomaly detection resultsQuery incidentsQuery root causesAdd hooks for receiving anomaly alertsAdd a data feed from a sample or data sourceMetrics Advisor supports connecting different types of data sources. Here is a sample to ingest data from SQL Server.importosimportdatetimefromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorAdministrationClientfromazure.ai.metricsadvisor.modelsimport(SqlServerDataFeedSource,DataFeedSchema,DataFeedMetric,DataFeedDimension,DataFeedRollupSettings,DataFeedMissingDataPointFillSettings)service_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")sql_server_connection_string=os.getenv("SQL_SERVER_CONNECTION_STRING")query=os.getenv("SQL_SERVER_QUERY")client=MetricsAdvisorAdministrationClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))data_feed=client.create_data_feed(name="My data feed",source=SqlServerDataFeedSource(connection_string=sql_server_connection_string,query=query,),granularity="Daily",schema=DataFeedSchema(metrics=[DataFeedMetric(name="cost",display_name="Cost"),DataFeedMetric(name="revenue",display_name="Revenue")],dimensions=[DataFeedDimension(name="category",display_name="Category"),DataFeedDimension(name="city",display_name="City")],timestamp_column="Timestamp"),ingestion_settings=datetime.datetime(2019,10,1),data_feed_description="cost/revenue data feed",rollup_settings=DataFeedRollupSettings(rollup_type="AutoRollup",rollup_method="Sum",rollup_identification_value="__CUSTOM_SUM__"),missing_data_point_fill_settings=DataFeedMissingDataPointFillSettings(fill_type="SmartFilling"),access_mode="Private")returndata_feedCheck ingestion statusAfter we start the data ingestion, we can check the ingestion status.importdatetimefromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorAdministrationClientservice_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")data_feed_id=os.getenv("DATA_FEED_ID")client=MetricsAdvisorAdministrationClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))ingestion_status=client.list_data_feed_ingestion_status(data_feed_id,datetime.datetime(2020,9,20),datetime.datetime(2020,9,25))forstatusiningestion_status:print("Timestamp:{}".format(status.timestamp))print("Status:{}".format(status.status))print("Message:{}\n".format(status.message))Configure anomaly detection configurationWhile a default detection configuration is automatically applied to each metric, we can tune the detection modes used on our data by creating a customized anomaly detection configuration.fromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorAdministrationClientfromazure.ai.metricsadvisor.modelsimport(ChangeThresholdCondition,HardThresholdCondition,SmartDetectionCondition,SuppressCondition,MetricDetectionCondition,)service_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")metric_id=os.getenv("METRIC_ID")client=MetricsAdvisorAdministrationClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))change_threshold_condition=ChangeThresholdCondition(anomaly_detector_direction="Both",change_percentage=20,shift_point=10,within_range=True,suppress_condition=SuppressCondition(min_number=5,min_ratio=2))hard_threshold_condition=HardThresholdCondition(anomaly_detector_direction="Up",upper_bound=100,suppress_condition=SuppressCondition(min_number=2,min_ratio=2))smart_detection_condition=SmartDetectionCondition(anomaly_detector_direction="Up",sensitivity=10,suppress_condition=SuppressCondition(min_number=2,min_ratio=2))detection_config=client.create_detection_configuration(name="my_detection_config",metric_id=metric_id,description="anomaly detection config for metric",whole_series_detection_condition=MetricDetectionCondition(condition_operator="OR",change_threshold_condition=change_threshold_condition,hard_threshold_condition=hard_threshold_condition,smart_detection_condition=smart_detection_condition))returndetection_configConfigure alert configurationThen let's configure in which conditions an alert needs to be triggered.fromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorAdministrationClientfromazure.ai.metricsadvisor.modelsimport(MetricAlertConfiguration,MetricAnomalyAlertScope,TopNGroupScope,MetricAnomalyAlertConditions,SeverityCondition,MetricBoundaryCondition,MetricAnomalyAlertSnoozeCondition,)service_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")anomaly_detection_configuration_id=os.getenv("DETECTION_CONFIGURATION_ID")hook_id=os.getenv("HOOK_ID")client=MetricsAdvisorAdministrationClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))alert_config=client.create_alert_configuration(name="my alert config",description="alert config description",cross_metrics_operator="AND",metric_alert_configurations=[MetricAlertConfiguration(detection_configuration_id=anomaly_detection_configuration_id,alert_scope=MetricAnomalyAlertScope(scope_type="WholeSeries"),alert_conditions=MetricAnomalyAlertConditions(severity_condition=SeverityCondition(min_alert_severity="Low",max_alert_severity="High"))),MetricAlertConfiguration(detection_configuration_id=anomaly_detection_configuration_id,alert_scope=MetricAnomalyAlertScope(scope_type="TopN",top_n_group_in_scope=TopNGroupScope(top=10,period=5,min_top_count=5)),alert_conditions=MetricAnomalyAlertConditions(metric_boundary_condition=MetricBoundaryCondition(direction="Up",upper=50)),alert_snooze_condition=MetricAnomalyAlertSnoozeCondition(auto_snooze=2,snooze_scope="Metric",only_for_successive=True)),],hook_ids=[hook_id])returnalert_configQuery anomaly detection resultsWe can query the alerts and anomalies.importdatetimefromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorClientservice_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")alert_config_id=os.getenv("ALERT_CONFIG_ID")alert_id=os.getenv("ALERT_ID")client=MetricsAdvisorClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))results=client.list_alerts(alert_configuration_id=alert_config_id,start_time=datetime.datetime(2020,1,1),end_time=datetime.datetime(2020,9,9),time_mode="AnomalyTime",)forresultinresults:print("Alert id:{}".format(result.id))print("Create time:{}".format(result.created_time))results=client.list_anomalies(alert_configuration_id=alert_config_id,alert_id=alert_id,)forresultinresults:print("Create time:{}".format(result.created_time))print("Severity:{}".format(result.severity))print("Status:{}".format(result.status))Query incidentsWe can query the incidents for a detection configuration.importdatetimefromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorClientservice_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")anomaly_detection_configuration_id=os.getenv("DETECTION_CONFIGURATION_ID")client=MetricsAdvisorClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))results=client.list_incidents(detection_configuration_id=anomaly_detection_configuration_id,start_time=datetime.datetime(2020,1,1),end_time=datetime.datetime(2020,9,9),)forresultinresults:print("Metric id:{}".format(result.metric_id))print("Incident ID:{}".format(result.id))print("Severity:{}".format(result.severity))print("Status:{}".format(result.status))Query root causesWe can also query the root causes of an incidentfromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorClientservice_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")anomaly_detection_configuration_id=os.getenv("DETECTION_CONFIGURATION_ID")incident_id=os.getenv("INCIDENT_ID")client=MetricsAdvisorClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))results=client.list_incident_root_causes(detection_configuration_id=anomaly_detection_configuration_id,incident_id=incident_id,)forresultinresults:print("Score:{}".format(result.score))print("Description:{}".format(result.description))Add hooks for receiving anomaly alertsWe can add some hooks so when an alert is triggered, we can get call back.fromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredential,MetricsAdvisorAdministrationClientfromazure.ai.metricsadvisor.modelsimportEmailNotificationHookservice_endpoint=os.getenv("ENDPOINT")subscription_key=os.getenv("SUBSCRIPTION_KEY")api_key=os.getenv("API_KEY")client=MetricsAdvisorAdministrationClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))hook=client.create_hook(hook=EmailNotificationHook(name="email hook",description="my email hook",emails_to_alert=["alertme@alertme.com"],external_link="https://docs.microsoft.com/en-us/azure/cognitive-services/metrics-advisor/how-tos/alerts"))Async APIsThis library includes a complete async API supported on Python 3.6+. To use it, you must
first install an async transport, such asaiohttp.
Seeazure-core documentationfor more information.fromazure.ai.metricsadvisorimportMetricsAdvisorKeyCredentialfromazure.ai.metricsadvisor.aioimportMetricsAdvisorClient,MetricsAdvisorAdministrationClientclient=MetricsAdvisorClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))admin_client=MetricsAdvisorAdministrationClient(service_endpoint,MetricsAdvisorKeyCredential(subscription_key,api_key))TroubleshootingGeneralThe Azure Metrics Advisor clients will raise exceptions defined inAzure Core.LoggingThis library uses the standardlogginglibrary for logging.Basic information about HTTP sessions (URLs, headers, etc.) is logged atINFOlevel.DetailedDEBUGlevel logging, including request/response bodies andunredactedheaders, can be enabled on the client or per-operation with thelogging_enablekeyword argument.See full SDK logging documentation with exampleshere.Next stepsMore sample codeFor more details see thesamples README.ContributingThis 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, visitcla.microsoft.com.This project has adopted theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any
additional questions or comments.Release History1.0.0 (2021-07-06)Breaking ChangesChangedDetectionConditionsOperator->DetectionConditionOperatorcross_conditions_operator->condition_operatorAnomalyAlert.created_on->AnomalyAlert.created_timeAnomalyAlert.modified_on->AnomalyAlert.modified_timeAnomaly.created_on->Anomaly.created_timeadmin_emailshas been renamed toadminsinNotificationHookadmin_emailshas been renamed toadminsinDataFeedOptionsviewer_emailshas been renamed toviewersinDataFeedOptions1.0.0b4 (2021-06-07)New FeaturesAddedAzureLogAnalyticsDataFeedSourceandAzureEventHubsDataFeedSourceUpdate method now returns the updated objectAdded DatasourceCredentials and DatasourceCredential operationsAdded authentication type support for data feedBreaking ChangesDelete methods now take positional only argument as idupdate_subscription_keyandupdate_api_keyare merged into one methodupdate_keyRemovedDataFeedOptionsand moved all its properties to theDataFeedmodelDeprecated:HttpRequestDataFeedElasticsearchDataFeedRenamedAzureApplicationInsightsDataFeed->AzureApplicationInsightsDataFeedSourceAzureBlobDataFeed->AzureBlobDataFeedSourceAzureCosmosDBDataFeed->AzureCosmosDbDataFeedSourceAzureDataExplorerDataFeed->AzureDataExplorerDataFeedSourceAzureTableDataFeed->AzureTableDataFeedSourceInfluxDBDataFeed->InfluxDbDataFeedSourceMySqlDataFeed->MySqlDataFeedSourcePostgreSqlDataFeed->PostgreSqlDataFeedSourceSQLServerDataFeed->SqlServerDataFeedSourceMongoDBDataFeed->MongoDbDataFeedSourceAzureDataLakeStorageGen2DataFeed->AzureDataLakeStorageGen2DataFeedSourceDependency UpdatesBumpmsrestrequirement from0.6.12to0.6.211.0.0b3 (2021-02-09)New FeaturesAAD support authentication    #15922MetricsAdvisorKeyCredentialsupport for rotating the subscription and api keys to update long-lived clientsBreaking Changeslist_dimension_valueshas been renamed tolist_anomaly_dimension_valuesupdate methods now return NoneUpdated DataFeed.metric_ids to be a dict rather than a listHotfixesBumpsixrequirement from1.6to 1.11.0`1.0.0b2 (2020-11-10)Breaking Changescreate_hooknow takes as input anEmailHookorWebHookAnomalyhas been renamed toDataPointAnomalyIncidenthas been renamed toAnomalyIncidentIncidentPropertyIncidentStatushas been renamed toAnomalyIncidentStatusAlerthas been renamed toAnomalyAlertSeverityhas been renamed toAnomalySeverityMetrichas been renamed toDataFeedMetricDimensionhas been renamed toDataFeedDimensionEmailHookhas been renamed toEmailNotificationHookWebHookhas been renamed toWebNotificationHookHookhas been renamed toNotificationHookTimeModehas been renamed toAlertQueryTimeModeadminshas been renamed toadmin_emailsonNotificationHookadminshas been renamed toadmin_emailsonDataFeedOptionsviewershas been renamed toviewer_emailsonDataFeedOptionstimestamp_listhas been renamed totimestampsonMetricSeriesDatavalue_listhas been renamed tovaluesonMetricSeriesDataSeriesResulthas been renamed toMetricEnrichedSeriesDatacreate_anomaly_alert_configurationhas been renamed tocreate_alert_configurationget_anomaly_alert_configurationhas been renamed toget_alert_configurationdelete_anomaly_alert_configurationhas been renamed todelete_alert_configurationupdate_anomaly_alert_configurationhas been renamed toupdate_alert_configurationlist_anomaly_alert_configurationshas been renamed tolist_alert_configurationscreate_metric_anomaly_detection_configurationhas been renamed tocreate_detection_configurationget_metric_anomaly_detection_configurationhas been renamed toget_detection_configurationdelete_metric_anomaly_detection_configurationhas been renamed todelete_detection_configurationupdate_metric_anomaly_detection_configurationhas been renamed toupdate_detection_configurationlist_metric_anomaly_detection_configurationshas been renamed tolist_detection_configurationslist_feedbackshas been renamed tolist_feedbacklist_alerts_for_alert_configurationhas been renamed tolist_alertslist_anomalies_for_alert&list_anomalies_for_detection_configurationhave been grouped intolist_anomalieslist_dimension_values_for_detection_configurationhas been renamed tolist_dimension_valueslist_incidents_for_alert&list_incidents_for_detection_configurationhave been grouped intolist_incidentsNew Features__repr__added to all models1.0.0b1 (2020-10-07)First preview release