Change metrics configuration structure - Configuration Documentation …

…- General improvements (#41)

* Change metrics model

* Provide better documentation on the configuration

* Change environment variable name for scraping endpoint

* Provide better support for endpoint with '/'

* Add link to more information for Azure Monitor RBAC roles

docs/configuration.md

@@ -3,14 +3,23 @@ layout: default
 title: Promitor - Configuration
 ---
 
-Coming soon.
+Here is an overview of how you can configure Promitor.
 
-## Environment variables
+# Scraping
+Promitor automatically scrapes Azure Monitor and makes the information available based on the metrics configuration.
 
-- **PROMITOR_CONFIGURATION_PATH** *(Mandatory)* - Location of the YAML file describing what metrics to query in Azure Monitor
-- **PROMITOR_SCRAPEENDPOINT_BASEPATH** *(Optional)* - Path where the scrape endpoint for Prometheus will be exposed.
-   - Default is `/prometheus/scrape`
-- **PROMITOR_SCRAPE_SCHEDULE** *(Optional)* - Cron schedule to scrape Azure Monitor for all metrics.
-   - Default is `*/5 * * * *`
+The behavior of this can be configured with the following environment variables:
+- **PROMITOR_CONFIGURATION_PATH** - Defines the location of the YAML file that defines what metrics to scrape.
+- **PROMITOR_SCRAPE_BASEPATH** - Controls the path where the scraping endpoint for Prometheus is being exposed. If nothing is specified, `/prometheus/scrape` will be used.
+- **PROMITOR_SCRAPE_SCHEDULE** - A cron expression that controls the fequency in which all the configured metrics will be scraped from Azure Monitor. If configured is specified, `*/5 * * * *` will be used.
+
+# Authentication with Azure Monitor
+Authentication with Azure Monitor is fully integrated with Azure AD where you will need to create an entity, preferably an Azure AD Application, that will be used for integrating with the Azure Monitor API.
+
+The following environment variables need to be provided:
+- **PROMITOR_AUTH_APPID** - Id of the Azure AD entity to authenticate with
+- **PROMITOR_AUTH_APPKEY** - Secret of the Azure AD entity to authenticate with
+
+The entity in the Azure AD needs to have `Monitoring Reader` permission on the resource group that will be queried. More information can be found [here](https://docs.microsoft.com/en-us/azure/monitoring-and-diagnostics/monitoring-roles-permissions-security).
 
 [← back](.)

src/Promitor.Scraper/Configuration/EnvironmentVariables.cs

@@ -13,7 +13,7 @@ public class Authentication
         public class Scraping
         {
             public const string CronSchedule = "PROMITOR_SCRAPE_SCHEDULE";
-            public const string EndpointPath = "PROMITOR_SCRAPEENDPOINT_BASEPATH";
+            public const string Path = "PROMITOR_SCRAPE_BASEPATH";
         }
     }
 }

src/Promitor.Scraper/Extensions/IApplicationBuilderExtensions.cs

@@ -30,11 +30,6 @@ public static void UseOpenApiUi(this IApplicationBuilder app)
         /// <param name="scrapeEndpointPath">Path where the scrape endpoint will be exposed</param>
         public static IApplicationBuilder UsePrometheusScraper(this IApplicationBuilder app, string scrapeEndpointPath)
         {
-            if (scrapeEndpointPath.StartsWith("/"))
-            {
-                scrapeEndpointPath = scrapeEndpointPath.Substring(1);
-            }
-
             var prometheusOptions = new PrometheusOptions
             {
                 MapPath = scrapeEndpointPath,

src/Promitor.Scraper/Extensions/IServiceCollectionExtensions.cs

@@ -43,7 +43,7 @@ public static void UseOpenApiSpecifications(this IServiceCollection services, st
                     Url = "https://blog.tomkerkhove.be"
                 },
                 Title = $"Promitor v{apiVersion}",
-                Description = $"Collection of APIs to manage the Azure Monitor scrape endpoint for Prometheus.\r\nThe scrape endpoint is exposed at '<a href=\"./../{prometheusScrapeEndpointPath}\" target=\"_blank\">{prometheusScrapeEndpointPath}</a>'",
+                Description = $"Collection of APIs to manage the Azure Monitor scrape endpoint for Prometheus.\r\nThe scrape endpoint is exposed at '<a href=\"./../{prometheusScrapeEndpointPath}\" target=\"_blank\">/{prometheusScrapeEndpointPath}</a>'",
                 Version = $"v{apiVersion}",
                 License = new License
                 {

src/Promitor.Scraper/Model/Configuration/AzureMetricConfiguration.cs

@@ -0,0 +1,17 @@
+using Microsoft.Azure.Management.Monitor.Models;
+
+namespace Promitor.Scraper.Model.Configuration
+{
+    public class AzureMetricConfiguration
+    {
+        /// <summary>
+        ///     Type of aggregation to query the Azure Monitor metric
+        /// </summary>
+        public AggregationType Aggregation { get; set; }
+
+        /// <summary>
+        ///     Name of the Azure Monitor metric to query
+        /// </summary>
+        public string MetricName { get; set; }
+    }
+}

src/Promitor.Scraper/Model/Configuration/Metrics/MetricDefinition.cs

@@ -1,18 +1,11 @@
-using Microsoft.Azure.Management.Monitor.Models;
-
-namespace Promitor.Scraper.Model.Configuration.Metrics
+namespace Promitor.Scraper.Model.Configuration.Metrics
 {
     public class MetricDefinition
     {
         /// <summary>
-        ///     Name of the Azure Monitor metric to query
-        /// </summary>
-        public string AzureMetricName { get; set; }
-
-        /// <summary>
-        ///     Type of aggregation to query the Azure Monitor metric
+        ///     Configuration about the Azure Monitor metric to scrape
         /// </summary>
-        public AggregationType AzureMetricAggregation { get; set; }
+        public AzureMetricConfiguration AzureMetricConfiguration { get; set; }
 
         /// <summary>
         ///     Description concerning metric that will be made available in the scraping endpoint

src/Promitor.Scraper/Scraping/ResouceTypes/ServiceBusQueueScraper.cs

@@ -23,7 +23,7 @@ public ServiceBusQueueScraper(AzureMetadata azureMetadata, AzureCredentials azur
         protected override async Task ScrapeResourceAsync(MonitorManagementClient monitoringClient, ServiceBusQueueMetricDefinition metricDefinition)
         {
             var resourceUri = string.Format(ResourceUriTemplate, AzureMetadata.SubscriptionId, AzureMetadata.ResourceGroupName, metricDefinition.Namespace);
-            var foundMetric = await QueryAzureMonitorAsync(monitoringClient, resourceUri, metricDefinition.QueueName, metricDefinition.AzureMetricName, metricDefinition.AzureMetricAggregation);
+            var foundMetric = await QueryAzureMonitorAsync(monitoringClient, resourceUri, metricDefinition.QueueName, metricDefinition.AzureMetricConfiguration.MetricName, metricDefinition.AzureMetricConfiguration.Aggregation);
 
             var gauge = Metrics.CreateGauge(metricDefinition.Name, metricDefinition.Description);
             gauge.Set(foundMetric);

src/Promitor.Scraper/Scraping/ScrapeEndpoint.cs

@@ -3,7 +3,6 @@
 
 namespace Promitor.Scraper.Scraping
 {
-    // TODO: Write unit tests for all scenarios
     public static class ScrapeEndpoint
     {
         private const string DefaultScrapeEndpoint = "prometheus/scrape";
@@ -13,13 +12,13 @@ public static class ScrapeEndpoint
         /// </summary>
         public static string GetBasePath(IConfiguration configuration)
         {
-            var scrapeEndpointPath = configuration.GetValue<string>(EnvironmentVariables.Scraping.EndpointPath);
+            var scrapeEndpointPath = configuration.GetValue<string>(EnvironmentVariables.Scraping.Path);
             if (string.IsNullOrWhiteSpace(scrapeEndpointPath))
             {
                 return DefaultScrapeEndpoint;
             }
 
-            return scrapeEndpointPath.StartsWith("/") == false ? $"/{scrapeEndpointPath}" : scrapeEndpointPath;
+            return scrapeEndpointPath.StartsWith("/") ? scrapeEndpointPath.Substring(1) : scrapeEndpointPath;
         }
     }
 }

src/Promitor.Scraper/Startup.cs

@@ -1,8 +1,4 @@
 using System.Collections.Generic;
-using System;
-using System.ComponentModel.DataAnnotations;
-using System.IO;
-using System.Linq;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Configuration;
@@ -11,10 +7,8 @@
 using Promitor.Scraper.Configuration.Providers.Interfaces;
 using Promitor.Scraper.Scraping;
 using Promitor.Scraper.Validation;
-using Promitor.Scraper.Validation;
 using Promitor.Scraper.Validation.Interfaces;
 using Promitor.Scraper.Validation.Steps;
-using Validator = Promitor.Scraper.Validation.Validator;
 
 namespace Promitor.Scraper
 {