Share via

Microsoft.ApiManagement service/diagnostics

Bicep resource definition

The service/diagnostics resource type can be deployed with operations that target:

For a list of changed properties in each API version, see change log.

Resource format

To create a Microsoft.ApiManagement/service/diagnostics resource, add the following Bicep to your template.

resource symbolicname 'Microsoft.ApiManagement/service/diagnostics@2024-10-01-preview' = {
  parent: resourceSymbolicName
  name: 'string'
  properties: {
    alwaysLog: 'string'
    backend: {
      request: {
        body: {
          bytes: int
        }
        dataMasking: {
          headers: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
          queryParams: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
        }
        headers: [
          'string'
        ]
      }
      response: {
        body: {
          bytes: int
        }
        dataMasking: {
          headers: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
          queryParams: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
        }
        headers: [
          'string'
        ]
      }
    }
    frontend: {
      request: {
        body: {
          bytes: int
        }
        dataMasking: {
          headers: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
          queryParams: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
        }
        headers: [
          'string'
        ]
      }
      response: {
        body: {
          bytes: int
        }
        dataMasking: {
          headers: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
          queryParams: [
            {
              mode: 'string'
              value: 'string'
            }
          ]
        }
        headers: [
          'string'
        ]
      }
    }
    httpCorrelationProtocol: 'string'
    largeLanguageModel: {
      logs: 'string'
      requests: {
        maxSizeInBytes: int
        messages: 'string'
      }
      responses: {
        maxSizeInBytes: int
        messages: 'string'
      }
    }
    logClientIp: bool
    loggerId: 'string'
    metrics: bool
    operationNameFormat: 'string'
    sampling: {
      percentage: int
      samplingType: 'string'
    }
    verbosity: 'string'
  }
}

Property Values

Microsoft.ApiManagement/service/diagnostics

Name Description Value
name The resource name string

Constraints:
Min length = 1
Max length = 80
Pattern = ^[^*#&+:<>?]+$ (required)
parent In Bicep, you can specify the parent resource for a child resource. You only need to add this property when the child resource is declared outside of the parent resource.

For more information, see Child resource outside parent resource.		 Symbolic name for resource of type: service
properties Diagnostic entity contract properties. DiagnosticContractProperties

BodyDiagnosticSettings

Name Description Value
bytes Number of request body bytes to log. int

Constraints:
Max value = 8192

DataMasking

Name Description Value
headers Masking settings for headers DataMaskingEntity[]
queryParams Masking settings for Url query parameters DataMaskingEntity[]

DataMaskingEntity

Name Description Value
mode Data masking mode. 'Hide'
'Mask'
value The name of an entity to mask (e.g. a name of a header or a query parameter). string

DiagnosticContractProperties

Name Description Value
alwaysLog Specifies for what type of messages sampling settings should not apply. 'allErrors'
backend Diagnostic settings for incoming/outgoing HTTP messages to the Backend PipelineDiagnosticSettings
frontend Diagnostic settings for incoming/outgoing HTTP messages to the Gateway. PipelineDiagnosticSettings
httpCorrelationProtocol Sets correlation protocol to use for Application Insights diagnostics. 'Legacy'
'None'
'W3C'
largeLanguageModel Large Language Models diagnostic settings LLMDiagnosticSettings
logClientIp Log the ClientIP. Default is false. bool
loggerId Resource Id of a target logger. string (required)
metrics Emit custom metrics via emit-metric policy. Applicable only to Application Insights diagnostic settings. bool
operationNameFormat The format of the Operation Name for Application Insights telemetries. Default is Name. 'Name'
'Url'
sampling Sampling settings for Diagnostic. SamplingSettings
verbosity The verbosity level applied to traces emitted by trace policies. 'error'
'information'
'verbose'

HttpMessageDiagnostic

Name Description Value
body Body logging settings. BodyDiagnosticSettings
dataMasking Data masking settings. DataMasking
headers Array of HTTP Headers to log. string[]

LLMDiagnosticSettings

Name Description Value
logs Specifies whether default diagnostic should be enabled for Large Language Models or not. 'disabled'
'enabled'
requests Diagnostic settings for Large Language Models requests. LLMMessageDiagnosticSettings
responses Diagnostic settings for Large Language Models responses. LLMMessageDiagnosticSettings

LLMMessageDiagnosticSettings

Name Description Value
maxSizeInBytes Maximum size of message to logs in bytes. The default size is 32KB. int

Constraints:
Min value = 1
Max value = 262144
messages Specifies which message should be logged. Currently there is only 'all' option. 'all'

PipelineDiagnosticSettings

Name Description Value
request Diagnostic settings for request. HttpMessageDiagnostic
response Diagnostic settings for response. HttpMessageDiagnostic

SamplingSettings

Name Description Value
percentage Rate of sampling for fixed-rate sampling. int

Constraints:
Min value = 0
Max value = 100
samplingType Sampling type. 'fixed'

Usage Examples

Azure Quickstart Samples

The following Azure Quickstart templates contain Bicep samples for deploying this resource type.

Bicep File Description
Application Gateway with internal API Management and Web App Application Gateway routing Internet traffic to a virtual network (internal mode) API Management instance which services a web API hosted in an Azure Web App.
Create API Management in Internal VNet with App Gateway This template demonstrates how to Create a instance of Azure API Management on a private network protected by Azure Application Gateway.

ARM template resource definition

The service/diagnostics resource type can be deployed with operations that target:

For a list of changed properties in each API version, see change log.

Resource format

To create a Microsoft.ApiManagement/service/diagnostics resource, add the following JSON to your template.

{
  "type": "Microsoft.ApiManagement/service/diagnostics",
  "apiVersion": "2024-10-01-preview",
  "name": "string",
  "properties": {
    "alwaysLog": "string",
    "backend": {
      "request": {
        "body": {
          "bytes": "int"
        },
        "dataMasking": {
          "headers": [
            {
              "mode": "string",
              "value": "string"
            }
          ],
          "queryParams": [
            {
              "mode": "string",
              "value": "string"
            }
          ]
        },
        "headers": [ "string" ]
      },
      "response": {
        "body": {
          "bytes": "int"
        },
        "dataMasking": {
          "headers": [
            {
              "mode": "string",
              "value": "string"
            }
          ],
          "queryParams": [
            {
              "mode": "string",
              "value": "string"
            }
          ]
        },
        "headers": [ "string" ]
      }
    },
    "frontend": {
      "request": {
        "body": {
          "bytes": "int"
        },
        "dataMasking": {
          "headers": [
            {
              "mode": "string",
              "value": "string"
            }
          ],
          "queryParams": [
            {
              "mode": "string",
              "value": "string"
            }
          ]
        },
        "headers": [ "string" ]
      },
      "response": {
        "body": {
          "bytes": "int"
        },
        "dataMasking": {
          "headers": [
            {
              "mode": "string",
              "value": "string"
            }
          ],
          "queryParams": [
            {
              "mode": "string",
              "value": "string"
            }
          ]
        },
        "headers": [ "string" ]
      }
    },
    "httpCorrelationProtocol": "string",
    "largeLanguageModel": {
      "logs": "string",
      "requests": {
        "maxSizeInBytes": "int",
        "messages": "string"
      },
      "responses": {
        "maxSizeInBytes": "int",
        "messages": "string"
      }
    },
    "logClientIp": "bool",
    "loggerId": "string",
    "metrics": "bool",
    "operationNameFormat": "string",
    "sampling": {
      "percentage": "int",
      "samplingType": "string"
    },
    "verbosity": "string"
  }
}

Property Values

Microsoft.ApiManagement/service/diagnostics

Name Description Value
apiVersion The api version '2024-10-01-preview'
name The resource name string

Constraints:
Min length = 1
Max length = 80
Pattern = ^[^*#&+:<>?]+$ (required)
properties Diagnostic entity contract properties. DiagnosticContractProperties
type The resource type 'Microsoft.ApiManagement/service/diagnostics'

BodyDiagnosticSettings

Name Description Value
bytes Number of request body bytes to log. int

Constraints:
Max value = 8192

DataMasking

Name Description Value
headers Masking settings for headers DataMaskingEntity[]
queryParams Masking settings for Url query parameters DataMaskingEntity[]

DataMaskingEntity

Name Description Value
mode Data masking mode. 'Hide'
'Mask'
value The name of an entity to mask (e.g. a name of a header or a query parameter). string

DiagnosticContractProperties

Name Description Value
alwaysLog Specifies for what type of messages sampling settings should not apply. 'allErrors'
backend Diagnostic settings for incoming/outgoing HTTP messages to the Backend PipelineDiagnosticSettings
frontend Diagnostic settings for incoming/outgoing HTTP messages to the Gateway. PipelineDiagnosticSettings
httpCorrelationProtocol Sets correlation protocol to use for Application Insights diagnostics. 'Legacy'
'None'
'W3C'
largeLanguageModel Large Language Models diagnostic settings LLMDiagnosticSettings
logClientIp Log the ClientIP. Default is false. bool
loggerId Resource Id of a target logger. string (required)
metrics Emit custom metrics via emit-metric policy. Applicable only to Application Insights diagnostic settings. bool
operationNameFormat The format of the Operation Name for Application Insights telemetries. Default is Name. 'Name'
'Url'
sampling Sampling settings for Diagnostic. SamplingSettings
verbosity The verbosity level applied to traces emitted by trace policies. 'error'
'information'
'verbose'

HttpMessageDiagnostic

Name Description Value
body Body logging settings. BodyDiagnosticSettings
dataMasking Data masking settings. DataMasking
headers Array of HTTP Headers to log. string[]

LLMDiagnosticSettings

Name Description Value
logs Specifies whether default diagnostic should be enabled for Large Language Models or not. 'disabled'
'enabled'
requests Diagnostic settings for Large Language Models requests. LLMMessageDiagnosticSettings
responses Diagnostic settings for Large Language Models responses. LLMMessageDiagnosticSettings

LLMMessageDiagnosticSettings

Name Description Value
maxSizeInBytes Maximum size of message to logs in bytes. The default size is 32KB. int

Constraints:
Min value = 1
Max value = 262144
messages Specifies which message should be logged. Currently there is only 'all' option. 'all'

PipelineDiagnosticSettings

Name Description Value
request Diagnostic settings for request. HttpMessageDiagnostic
response Diagnostic settings for response. HttpMessageDiagnostic

SamplingSettings

Name Description Value
percentage Rate of sampling for fixed-rate sampling. int

Constraints:
Min value = 0
Max value = 100
samplingType Sampling type. 'fixed'

Usage Examples

Azure Quickstart Templates

The following Azure Quickstart templates deploy this resource type.

Template Description
Application Gateway with internal API Management and Web App

Deploy to Azure		 Application Gateway routing Internet traffic to a virtual network (internal mode) API Management instance which services a web API hosted in an Azure Web App.
Create API Management in Internal VNet with App Gateway

Deploy to Azure		 This template demonstrates how to Create a instance of Azure API Management on a private network protected by Azure Application Gateway.

Terraform (AzAPI provider) resource definition

The service/diagnostics resource type can be deployed with operations that target:

For a list of changed properties in each API version, see change log.

Resource format

To create a Microsoft.ApiManagement/service/diagnostics resource, add the following Terraform to your template.

resource "azapi_resource" "symbolicname" {
  type = "Microsoft.ApiManagement/service/diagnostics@2024-10-01-preview"
  name = "string"
  parent_id = "string"
  body = {
    properties = {
      alwaysLog = "string"
      backend = {
        request = {
          body = {
            bytes = int
          }
          dataMasking = {
            headers = [
              {
                mode = "string"
                value = "string"
              }
            ]
            queryParams = [
              {
                mode = "string"
                value = "string"
              }
            ]
          }
          headers = [
            "string"
          ]
        }
        response = {
          body = {
            bytes = int
          }
          dataMasking = {
            headers = [
              {
                mode = "string"
                value = "string"
              }
            ]
            queryParams = [
              {
                mode = "string"
                value = "string"
              }
            ]
          }
          headers = [
            "string"
          ]
        }
      }
      frontend = {
        request = {
          body = {
            bytes = int
          }
          dataMasking = {
            headers = [
              {
                mode = "string"
                value = "string"
              }
            ]
            queryParams = [
              {
                mode = "string"
                value = "string"
              }
            ]
          }
          headers = [
            "string"
          ]
        }
        response = {
          body = {
            bytes = int
          }
          dataMasking = {
            headers = [
              {
                mode = "string"
                value = "string"
              }
            ]
            queryParams = [
              {
                mode = "string"
                value = "string"
              }
            ]
          }
          headers = [
            "string"
          ]
        }
      }
      httpCorrelationProtocol = "string"
      largeLanguageModel = {
        logs = "string"
        requests = {
          maxSizeInBytes = int
          messages = "string"
        }
        responses = {
          maxSizeInBytes = int
          messages = "string"
        }
      }
      logClientIp = bool
      loggerId = "string"
      metrics = bool
      operationNameFormat = "string"
      sampling = {
        percentage = int
        samplingType = "string"
      }
      verbosity = "string"
    }
  }
}

Property Values

Microsoft.ApiManagement/service/diagnostics

Name Description Value
name The resource name string

Constraints:
Min length = 1
Max length = 80
Pattern = ^[^*#&+:<>?]+$ (required)
parent_id The ID of the resource that is the parent for this resource. ID for resource of type: service
properties Diagnostic entity contract properties. DiagnosticContractProperties
type The resource type "Microsoft.ApiManagement/service/diagnostics@2024-10-01-preview"

BodyDiagnosticSettings

Name Description Value
bytes Number of request body bytes to log. int

Constraints:
Max value = 8192

DataMasking

Name Description Value
headers Masking settings for headers DataMaskingEntity[]
queryParams Masking settings for Url query parameters DataMaskingEntity[]

DataMaskingEntity

Name Description Value
mode Data masking mode. 'Hide'
'Mask'
value The name of an entity to mask (e.g. a name of a header or a query parameter). string

DiagnosticContractProperties

Name Description Value
alwaysLog Specifies for what type of messages sampling settings should not apply. 'allErrors'
backend Diagnostic settings for incoming/outgoing HTTP messages to the Backend PipelineDiagnosticSettings
frontend Diagnostic settings for incoming/outgoing HTTP messages to the Gateway. PipelineDiagnosticSettings
httpCorrelationProtocol Sets correlation protocol to use for Application Insights diagnostics. 'Legacy'
'None'
'W3C'
largeLanguageModel Large Language Models diagnostic settings LLMDiagnosticSettings
logClientIp Log the ClientIP. Default is false. bool
loggerId Resource Id of a target logger. string (required)
metrics Emit custom metrics via emit-metric policy. Applicable only to Application Insights diagnostic settings. bool
operationNameFormat The format of the Operation Name for Application Insights telemetries. Default is Name. 'Name'
'Url'
sampling Sampling settings for Diagnostic. SamplingSettings
verbosity The verbosity level applied to traces emitted by trace policies. 'error'
'information'
'verbose'

HttpMessageDiagnostic

Name Description Value
body Body logging settings. BodyDiagnosticSettings
dataMasking Data masking settings. DataMasking
headers Array of HTTP Headers to log. string[]

LLMDiagnosticSettings

Name Description Value
logs Specifies whether default diagnostic should be enabled for Large Language Models or not. 'disabled'
'enabled'
requests Diagnostic settings for Large Language Models requests. LLMMessageDiagnosticSettings
responses Diagnostic settings for Large Language Models responses. LLMMessageDiagnosticSettings

LLMMessageDiagnosticSettings

Name Description Value
maxSizeInBytes Maximum size of message to logs in bytes. The default size is 32KB. int

Constraints:
Min value = 1
Max value = 262144
messages Specifies which message should be logged. Currently there is only 'all' option. 'all'

PipelineDiagnosticSettings

Name Description Value
request Diagnostic settings for request. HttpMessageDiagnostic
response Diagnostic settings for response. HttpMessageDiagnostic

SamplingSettings

Name Description Value
percentage Rate of sampling for fixed-rate sampling. int

Constraints:
Min value = 0
Max value = 100
samplingType Sampling type. 'fixed'

Usage Examples

Terraform Samples

A basic example of deploying API Management Service Diagnostic.

terraform {
  required_providers {
    azapi = {
      source = "Azure/azapi"
    }
  }
}

provider "azapi" {
  skip_provider_registration = false
}

variable "resource_name" {
  type    = string
  default = "acctest0001"
}

variable "location" {
  type    = string
  default = "westeurope"
}

resource "azapi_resource" "resourceGroup" {
  type     = "Microsoft.Resources/resourceGroups@2020-06-01"
  name     = var.resource_name
  location = var.location
}

resource "azapi_resource" "component" {
  type      = "Microsoft.Insights/components@2020-02-02"
  parent_id = azapi_resource.resourceGroup.id
  name      = var.resource_name
  location  = var.location
  body = {
    kind = "web"
    properties = {
      Application_Type                = "web"
      DisableIpMasking                = false
      DisableLocalAuth                = false
      ForceCustomerStorageForProfiler = false
      RetentionInDays                 = 90
      SamplingPercentage              = 100
      publicNetworkAccessForIngestion = "Enabled"
      publicNetworkAccessForQuery     = "Enabled"
    }
  }
  schema_validation_enabled = false
  response_export_values    = ["*"]
}

resource "azapi_resource" "service" {
  type      = "Microsoft.ApiManagement/service@2021-08-01"
  parent_id = azapi_resource.resourceGroup.id
  name      = var.resource_name
  location  = var.location
  body = {
    properties = {
      certificates = [
      ]
      customProperties = {
        "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30" = "false"
        "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10" = "false"
        "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11" = "false"
        "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls10"         = "false"
        "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls11"         = "false"
      }
      disableGateway      = false
      publicNetworkAccess = "Enabled"
      publisherEmail      = "pub1@email.com"
      publisherName       = "pub1"
      virtualNetworkType  = "None"
    }
    sku = {
      capacity = 0
      name     = "Consumption"
    }
  }
  schema_validation_enabled = false
  response_export_values    = ["*"]
}

resource "azapi_resource" "logger" {
  type      = "Microsoft.ApiManagement/service/loggers@2021-08-01"
  parent_id = azapi_resource.service.id
  name      = var.resource_name
  body = {
    properties = {
      credentials = {
        instrumentationKey = azapi_resource.component.output.properties.InstrumentationKey
      }
      description = ""
      isBuffered  = true
      loggerType  = "applicationInsights"
    }
  }
  schema_validation_enabled = false
  response_export_values    = ["*"]
  lifecycle {
    ignore_changes = [body.properties.credentials.instrumentationKey]
  }
}

resource "azapi_resource" "diagnostic" {
  type      = "Microsoft.ApiManagement/service/diagnostics@2021-08-01"
  parent_id = azapi_resource.service.id
  name      = "applicationinsights"
  body = {
    properties = {
      loggerId            = azapi_resource.logger.id
      operationNameFormat = "Name"
    }
  }
  schema_validation_enabled = false
  response_export_values    = ["*"]
}
  • Last updated on