Azure Resource Metrics - Apply doc template and add generic setup section

[alaudazzi]

This PR:

• applies the doc template to Resource metrics
• integrates a more generic setup section similar to the one in Azure Billing metrics
• harmonizes the text according to the new structure

Relates #123

[elasticmachine]

🚀 Benchmarks report

Package azure_metrics 👍(2) 💚(1) 💔(1)

Expand to view

Data stream	Previous EPS	New EPS	Diff (%)	Result
container_service	200000	142857.14	-57142.86 (-28.57%)	💔

To see the full report comment with /test benchmark fullreport

[alaudazzi]

@zmoog
Here is a doc preview.

Having the Exported fields table following each type of data streams makes this page not readable. I can test the collapse/expand feature in MD and see how it renders in MDX, but if it doesn't work I suggest we move the Exported fields table at the end of the page, just before the Changelog section. WDYT?

[zmoog]

After reading the preview, I have the feeling that we should move this section with the metricset description and tables (generaged by {{fields "monitor"}}) at the bottom of the doc in a "references" section.

The {{fields "monitor"}} expands in a large table, and IMO it's easy to miss the content after the tables.

What about adding something in the lines of "see references section for all the gory details of these metricsets" right after the metricset list?

[alaudazzi]

Yes 👍 that's what I also suggested here. If the test with collapse/expand feature doesn't work, we'll put the tables at the end of the page and reference them where needed.

[alaudazzi]

@zmoog
Consider some further optimization on this page:

The first block of text of Integration specific configuration notes and the entire section of Additional notes about metrics and costs can be combined into a single and more linear section called Authentication and costs.

For example:

---

---

If agreed, this change would be reflected on all these pages:

• generic integrations
  Monitor metrics

• specialized integrations

  • Container instance metrics
  • Container registry metrics
  • Container service metrics
  • Database Account metrics
  • Storage Account metrics
  • Virtual machines metrics
  • Virtual machines scaleset metrics

[zmoog]

The first block of text of Integration specific configuration notes and the entire section of Additional notes about metrics and costs can be combined into a single and more linear section called Authentication and costs.

Yep, it makes senso combine these two sections into one.

Two notes on the content:

• In all our Azure-related docs, we always use the term "Azure AD" (or "Azure Active Directory"). It seems that Microsoft renamed Azure AD in Microsoft Entra ID. Updating these names in all docs will probably require a dedicated PR, so I don't know if we can start updating the portions we change in this one.
• In these section, we use the term "service principal". IIRC, this is a different name for the "app registration" concept. We need to double-check if "service principal" and "app registration" are the same thing or not and decide how to deal with them.

[zmoog]

If we want to continue using the ASCII art for diagrams, I can share the text for azure_resource_metrics_req.png.

[zmoog]

In these section, we use the term "service principal". IIRC, this is a different name for the "app registration" concept. We need to double-check if "service principal" and "app registration" are the same thing or not and decide how to deal with them.

The name "service principal" is commonly used to represent the identity of an application for authentication purposes. Other cloud providers, for example GCP, use the term service principal for this concept.

On Azure, they seem to use "app registration" on the Portal, and "service principal" on the CLI and API:

• https://learn.microsoft.com/en-us/cli/azure/azure-cli-sp-tutorial-1?tabs=bash

On the Azure CLI, if I list the service principals:

$ az ad sp list | jq -r '.[] | [.appDisplayName] | @tsv' | grep branca

mbranca-app-registration-or-service-principal
mbranca-elastic-agent

I get the same result if I open the app registrations section on the Portal:

[alaudazzi]

@zmoog

On Azure, they seem to use "app registration" on the Portal, and "service principal" on the CLI and API:

So, the concept is the same, the only difference is that app registration is on the UI and service principal is on the CLI?

Microsoft renamed Azure AD in Microsoft Entra

We fix the occurrences in this PR and handle the remaining ones in a separate PR

[zmoog]

@alaudazzi, here is the ASCII version of the diagram:

                       ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐

                       │  ┌─────────────────┐  │
┌─────────────────┐       │  azure-monitor  │       ┌─────────────────┐
│    Azure API    │◀───┼──│  <<metricset>>  │──┼───▶│  Elasticsearch  │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                       │                       │
                        ─ Elastic Agent ─ ─ ─ ─

[zmoog]

The name "service principal" is commonly used to represent the identity of an application for authentication purposes. Other cloud providers, for example GCP, use the term service principal for this concept.

It turns out that on Azure "app registration" and "service principal" are related but NOT the same.

Quoting Create a Microsoft Entra application and service principal that can access resources from the Azure docs:

When you register a new application in Microsoft Entra ID, a service principal is automatically created for the app registration. The service principal is the app's identity in the Microsoft Entra tenant.

So, "app registration" and "service principal" are different entities. Azure creates the related service principal for you if you create an app registration. And it works both ways!

So users have the option of creating:

• (A) an app registration on the Azure Portal (probably easier to do manually), and get the service principal for free.
• (B) a service registration using the CLI or the API (probably more accessible to automate), and get an app registration for free.

[zmoog]

I would use the app registration in our docs to resolve the "app registration" vs. "service principal" dilemma. The App registration is the most visible term in Azure Portal, the UI we primarily use in our docs.

Then, if we link to Azure docs that explain how to create a service principal using the CLI (bash or PowerShell), in that case, we can mention that creating a service principal will also create a linked app registration that will be visible on the Portal.

@alaudazzi, WDYT?

[alaudazzi]

@zmoog

I would use the app registration in our docs to resolve the "app registration" vs. "service principal" dilemma. The App registration is the most visible term in Azure Portal, the UI we primarily use in our docs.

makes sense

Then, if we link to Azure docs that explain how to create a service principal using the CLI (bash or PowerShell), in that case, we can mention that creating a service principal will also create a linked app registration that will be visible on the Portal.

I added a note in the Authentication and costs section.

The PR is ready for you to review. I guess we integrated all the comments raised so far.

[zmoog]

LGTM!

nit: I think we can remove

[zmoog]

LGTM!

Nit: I think we can remove the .png file since we opted to use the ASCII version of the diagram.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: e99d6bf

History

• 💚 Build #9062 succeeded ce66b2c
• 💚 Build #9001 succeeded 08374f1
• 💚 Build #8908 succeeded 084f3eb
• 💚 Build #8844 succeeded f00af8f
• 💚 Build #8840 succeeded 418d8c1
• 💔 Build #8807 failed 10bfe92

[elastic-sonarqube]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarQube

[elasticmachine]

Package azure_metrics - 1.4.2 containing this change is available at https://epr.elastic.co/search?package=azure_metrics