SFR3 - Deployment/Usage Telemetry

ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry

Modules MUST provide the capability to collect deployment/usage telemetry as detailed in Telemetry further.

To highlight that AVM modules use telemetry, an information notice MUST be included in the footer of each module’s README.md file with the below content. See the telemetry guidance for more details.

Telemetry Information Notice

Note

The following information notice is automatically added at the bottom of the README.md file of the module when

Bicep: Using the utilities/tools/Set-AVMModule.ps1 utility
Terraform: Running avm pre-commit with the note and header ## Data Collection placed in the module’s _footer.md beforehand

### Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the [repository](https://aka.ms/avm/telemetry). There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at <https://go.microsoft.com/fwlink/?LinkID=824704>. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Module Class Applicability

This specification applies to all AVM module classes (resource, pattern, utility), however, in case of utility modules, telemetry collection MUST only be added when the utility module deploys any resources (e.g., a deployment script resource). If the utility module does not deploy any resources, telemetry collection MUST NOT be added.

Bicep

Important

Published CSV files in the AVM Central Repo (Azure/Azure-Verified-Modules) remain available for consumers and checks that look up assigned telemetry prefixes. To see their formatted content with additional information, visit the AVM Module Indexes page.

Record the assigned current prefix in telemetryIdPrefix in the module’s metadata.json, including a child’s own file when applicable. Place it alongside the module’s main.bicep before compiling, and read only that value in Bicep with loadJsonContent('metadata.json', 'telemetryIdPrefix') instead of hardcoding it. Retain previous identifiers in alternativeTelemetryIdPrefixes when assigning a new current prefix. Corrections follow the metadata review process; assignment of a new identifier requires the AVM core team.

Assigned values are also published in the Resource Module, Pattern Module, and Utility Module indexes. Ask the AVM core team to resolve any discrepancy with metadata rather than changing an identifier without approval.

The Bicep ARM deployment name used for telemetry MUST follow <telemetryIdPrefix>.<version>.<uniqueness> and MUST be no longer than 64 characters, as shown in BCPFR4.

<telemetryIdPrefix> is the current value in the module’s metadata.json and MUST use 46d3xbcp.<res|ptn|utl>.<seven lowercase hexadecimal characters> (20 characters).
<version> is the module version token with periods replaced by hyphens.
<uniqueness> is a four-character value derived from uniqueString and the deployment context.

Do not truncate an identifier or version to meet the 64-character limit. When replacing a previous prefix, retain it and any earlier prefixes in alternativeTelemetryIdPrefixes in the same module’s metadata.json for historical reporting.

Tip

Terraform: Terraform uses a metadata-backed empty Azure deployment generated by Avm.Authoring; it does not require a separate telemetry provider.

General: See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

Terraform

Instrumented Terraform roots and child modules MUST obtain their assigned 46d3xtrf telemetryIdPrefix and canonicalType from their own metadata.json. The prefix MUST NOT be reconstructed from a module source or hardcoded in generated Terraform. Current Terraform prefixes MUST be 46d3xtrf.<res|ptn|utl>.<seven lowercase hexadecimal characters> (20 characters). Previously deployed identifiers, including descriptive Terraform prefixes up to 59 characters, MAY be retained in alternativeTelemetryIdPrefixes with the same ecosystem and module kind; generated deployments use only the current prefix. Children without a telemetry prefix, including telemetry-free helpers and utilities, MUST NOT create a telemetry deployment.

Avm.Authoring MUST generate and maintain main.telemetry.tf rather than requiring module authors to maintain telemetry resources. When var.enable_telemetry is true, this file MUST create an empty, incremental Microsoft.Resources/deployments@2025-04-01 deployment using azapi_resource at the active subscription scope. The deployment location follows SFR4.

The deployment name is the reporting payload. It MUST have the form <telemetryIdPrefix>.<version>.<source>.<instance> and MUST NOT exceed 64 characters:

Segment	Value
`telemetryIdPrefix`	The fixed metadata identifier, which the module catalog maps to its canonical type.
`version`	The installed full version from the Terraform modules manifest entry matching `path.module`, with periods replaced by hyphens. Use `0-0-0` when a version is unavailable.
`source`	One character derived from the manifest source: `t` for Terraform Registry, `o` for OpenTofu Registry, `g` for Git, or `x` for other sources. Never include a raw source path.
`instance`	The first four lowercase hex characters of a hash of the stable provider-free `terraform_data.telemetry` instance ID.

The generated resource MUST reject an invalid or overlong version token rather than truncate reporting data. It MUST NOT send telemetry tags; Azure deployment events provide the time, subscription, and caller context. An output in the empty template MUST change with plantimestamp() on every normal plan solely to force an in-place deployment write, including on otherwise no-op applies; this output is not reporting data. Refresh-only operations do not create a telemetry write.

The deployment MUST fail the apply if Azure rejects it, unless the consumer disables telemetry with enable_telemetry = false. With telemetry enabled, the deployment identity needs Microsoft.Resources/deployments/read, Microsoft.Resources/deployments/write, and Microsoft.Resources/deployments/delete at the active subscription scope. See the telemetry guidance for the opt-out and required location input.

The generated configuration MUST NOT require the modtm provider or add per-resource AzAPI telemetry headers. During the supported migration window, existing modtm_telemetry.telemetry and telemetry-only random_uuid.telemetry state MUST be forgotten with declarative removed blocks using destroy = false, without destroying either object. Terraform still needs the old providers available for one final initialization when an existing state refers to them; new installations and subsequent plans do not require modtm.