Azure SB Metric Streaming – meshIQ

The functionality described in this article is available in the meshIQ Platform versions 11.1.1 and later. See meshIQ platform Highlights v11.1 for an overview of feature changes.

Set up Azure SB Monitoring Application Service Principal

This part is not needed if you already have your service principal set to access Azure SB metrics or if you are using Azure Managed Identities for it.

Create a service principal and assign the Reader role to the service principal.

This can be done using these CLI commands:

az login
az account set --subscription "<your subscription id>"
# Azure SB resource group format is: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
#                              like: /subscriptions/c3xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxf8/resourceGroups/AndriusSB-RG
az ad sp create-for-rbac -n "readSBMetric" --role Reader --scope "<list of Azure SB bound resource groups to read metrics>"

The last command in the example above produces output like this:

{
"appId": "ec599183-xxxx-xxxx-xxxx-xxxxxxxxxc8f",
"displayName": "readSBMetric",
"password": "FGixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxubwF",
"tenant": "5029a0f1-xxxx-xxxx-xxxx-xxxxxxxxxx78"
}

Configure the TNT4J stream to read and forward the metrics

meshIQ Streams 11.0.1 or higher is required. See the meshIQ Streams Express Guide for more information about meshIQ Streams.

All required configuration must be done in the tnt-data-source.xml file.

Configure streamed data broadcasting:
- Route streamed data to Autopilot only. Set: <property name="event.sink.factory.BroadcastSequence" value="ap"/>
- Route streamed data to XRay only. Set: <property name="event.sink.factory.BroadcastSequence" value="xray"/>
- Route streamed data to both Autopilot and XRay simultaneously. Set: <property name="event.sink.factory.BroadcastSequence" value="ap,xray"/>

Configure XRay access (optional if not present in broadcasting sequence):

Set your XRay access token:

<property name="event.sink.factory.EventSinkFactory.prod.Url" value="https://stream.meshiq.com"/>
<property name="event.sink.factory.EventSinkFactory.prod.Token" value="388xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxb3"/>

Configure AutoPilot access (optional if not present in broadcasting sequence):

Set your AutoPilot CEP facts streaming endpoint:

<property name="event.sink.factory.EventSinkFactory.ap.Host" value="<AP_CEP_IP/HOST>"/>
<property name="event.sink.factory.EventSinkFactory.ap.Port" value="6060"/>

Configure your Azure SB namespace access:
- Set configuration to obtain Azure SB metrics access token (use either the GetAPITokenSPN step or the GetAPITokenIMDS step, but not both).
  - Set your REST API access service principal (SPN) credentials (GetAPITokenSPN step). (These are the credentials provided by the az ad sp create-for-rbac command executed above.)
```
<property name="AzureTenant" value="5029a0f1-xxxx-xxxx-xxxx-xxxxxxxxxx78"/>
<property name="AzureAppId" value="ec599183-xxxx-xxxx-xxxx-xxxxxxxxxc8f"/>
<property name="AzureSecret" value="FGixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxubwF"/>
```

Set your configuration to obtain Azure Managed Identities (MI) token from Azure Instance Metadata Service (IMDS):

Set your IMDS URL

 <request id="GetTokenIMDS"><![CDATA[
http://169.254.169.254/metadata/identity/oauth2/token
]]>

Set request parameter api-version to match one run by your IMDS service:

<!-- may be one of: `2018-02-01`, `2018-11-01`, `2019-06-01`, `2019-08-01`, `2020-06-01`, `2021-05-01`, `2021-12-13`, `2022-08-01`, `2023-01-01` -->
<req-param id="api-version" value="2020-06-01"/>

Set optional request parameter if needed:

<req-param id="object_id" value="xxxxxxx"/>
<req-param id="client_id" value="xxxxxxx"/>
<req-param id="msi_res_id" value="xxxxxxx"/>

- Set your Azure SB cluster info to collect metrics (GetAzureSBMetricsstep):
```
<property name="AzureSubscriptionId" value="c3cbb071-xxxx-xxxx-xxxx-xxxxxxxxxxf8"/>
<property name="AzureResourceGroup" value="AndriusSB-RG"/>
@@ -123,6 +145,7 @@ Execute shell script:
```
- Set the metrics collection request interval by changing the configuration entries below accordingly. The default interval is 5 minutes.

<!-- The interval (i.e. timegrain) of the query. Values may be: PT1M, PT5M, PT15M, PT30M, PT1H, PT6H, PT12H, P1D -->
<property name="AzureMetricsInterval" value="PT5M"/>
...
<!-- The interval of REST API calls to collect Azure SB metrics -->
<schedule-simple interval="5" units="Minutes" startDelay="10" startDelayUnits="Seconds" repeatCount="-1"/>
...
<!-- Sets metrics timespan start date and time: groovy expression to calculate timestamp for 5 minutes back from now -->
<req-param id="timespanStart" value="${groovy:5.minutes.ago}" format="yyyy-MM-dd'T'HH:mm:ss'Z'" timezone="UTC" transient="true"/>

Configure metrics collection properties. There are three Azure REST API requests named:
- GetNamespaceMetrics - to collect your namespace scoped metrics
- GetEntitiesMetrics - to collect namespace bound entity scoped metrics
- GetThrottleMetrics - to collect ThrottledRequests scoped by MessagingErrorSubCode.
The REST API calls interval is configured through a simple scheduler configuration:
```
<schedule-simple interval="5" units="Minutes" startDelay="10" startDelayUnits="Seconds" repeatCount="-1"/>
```
- interval - defines REST API call interval
- units - defines call interval time units
- startDelay - defines how long to delay the request after the application starts. We want to obtain access token before.
- startDelayUnits - defines delay time units
- repeatCount - defines how many requests to schedule. -1 means infinite.
Azure API call requests have similar parameters to configure:
- metricnames - the names of the metrics to retrieve (comma separated). If a metricname contains a comma, use %2 to indicate the coma within the name. Example: Metric,Name1 should be Metric%2Name1
- aggregation - the list of aggregation types to retrieve (comma separated)
- timespan - the timespan of the query. It is a string with the following format startDateTime_ISO/endDateTime_ISO. Supported ISO-8601 time interval format: Datetime/Datetime, Datetime/Duration, Duration/Datetime, Duration
- interval - the interval (i.e. timegrain) of the query. Values may be: PT1M, PT5M, PT15M, PT30M, PT1H, PT6H, PT12H, P1D
- $filter - used to reduce the set of metric data returned. Example: Metric contains metadata A, B and C.
  - Return all time series of C where A = a1 and B = b1 or b2 $filter=A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'
  - Invalid variant: $filter=A eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'. This is invalid because the logical or operator cannot separate two different metadata names.
  - Return all time series where A = a1, B = b1 and C = c1: $filter=A eq 'a1' and B eq 'b1' and C eq 'c1'
  - Return all time series where A = a1 $filter=A eq 'a1' and B eq '' and C eq ''.
  Special case: When dimension name or dimension value uses round brackets.
  For example: When dimension name is dim (test) 1, instead of using
  $filter= "dim (test) 1 eq '' "
  use
  $filter= "dim %2528test%2529 1 eq '' "
  When dimension name is dim (test) 3 and dimension value is dim3 (test) val, instead of using $filter= "dim (test) 3 eq 'dim3 (test) val' "
  use
  $filter= "dim %2528test%2529 3 eq 'dim3 %2528test%2529 val' "
- metricnamespace - metric namespace to query metric definitions for
- orderby - the aggregation to use for sorting results and the direction of the sort. Only one order can be specified. Example: sum asc.
- resultType - reduces the set of data collected. The syntax allowed depends on the operation. See the operation's description for details. Values may be: Data, Metadata
- top - the maximum number of records to retrieve. Valid only if $filter is specified. Defaults to 10.

Run the stream

Execute shell script:

Linux

./run.sh

MS Windows

run.bat

Additional resources

Create token to access Azure Rest API

See the following articles:

Set up Microsoft Entra ID (formerly Azure Active Directory)

See Get Microsoft Entra ID (formerly Azure ID) tokens for service principals

REST API call configuration

See the following resources: