Diagnostic - Create Or Update

Creates a new Diagnostic or updates an existing one.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/diagnostics/{diagnosticId}?api-version=2021-08-01

URI Parameters

Name In Required Type Description
diagnosticId
path True
  • string

Diagnostic identifier. Must be unique in the current API Management service instance.

Regex pattern: ^[^*#&+:<>?]+$

resourceGroupName
path True
  • string

The name of the resource group.

serviceName
path True
  • string

The name of the API Management service.

Regex pattern: ^[a-zA-Z](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$

subscriptionId
path True
  • string

Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.

api-version
query True
  • string

Version of the API to be used with the client request.

Request Header

Name Required Type Description
If-Match
  • string

ETag of the Entity. Not required when creating an entity, but required when updating an entity.

Request Body

Name Required Type Description
properties.loggerId True
  • string

Resource Id of a target logger.

properties.alwaysLog

Specifies for what type of messages sampling settings should not apply.

properties.backend

Diagnostic settings for incoming/outgoing HTTP messages to the Backend

properties.frontend

Diagnostic settings for incoming/outgoing HTTP messages to the Gateway.

properties.httpCorrelationProtocol

Sets correlation protocol to use for Application Insights diagnostics.

properties.logClientIp
  • boolean

Log the ClientIP. Default is false.

properties.operationNameFormat

The format of the Operation Name for Application Insights telemetries. Default is Name.

properties.sampling

Sampling settings for Diagnostic.

properties.verbosity

The verbosity level applied to traces emitted by trace policies.

Responses

Name Type Description
200 OK

Diagnostic successfully updated

Headers

  • ETag: string
201 Created

Diagnostic was successfully created.

Headers

  • ETag: string
Other Status Codes

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

ApiManagementCreateDiagnostic

Sample Request

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/diagnostics/applicationinsights?api-version=2021-08-01
{
  "properties": {
    "alwaysLog": "allErrors",
    "loggerId": "/loggers/azuremonitor",
    "sampling": {
      "samplingType": "fixed",
      "percentage": 50
    },
    "frontend": {
      "request": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      },
      "response": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      }
    },
    "backend": {
      "request": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      },
      "response": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      }
    }
  }
}

Sample Response

{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/diagnostics/applicationinsights",
  "type": "Microsoft.ApiManagement/service/diagnostics",
  "name": "applicationinsights",
  "properties": {
    "alwaysLog": "allErrors",
    "loggerId": "/loggers/azuremonitor",
    "sampling": {
      "samplingType": "fixed",
      "percentage": 50
    },
    "frontend": {
      "request": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      },
      "response": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      }
    },
    "backend": {
      "request": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      },
      "response": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      }
    }
  }
}
{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/diagnostics/applicationinsights",
  "type": "Microsoft.ApiManagement/service/diagnostics",
  "name": "applicationinsights",
  "properties": {
    "alwaysLog": "allErrors",
    "loggerId": "/loggers/applicationinsights",
    "sampling": {
      "samplingType": "fixed",
      "percentage": 50
    },
    "frontend": {
      "request": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      },
      "response": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      }
    },
    "backend": {
      "request": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      },
      "response": {
        "headers": [
          "Content-type"
        ],
        "body": {
          "bytes": 512
        }
      }
    }
  }
}

Definitions

AlwaysLog

Specifies for what type of messages sampling settings should not apply.

BodyDiagnosticSettings

Body logging settings.

DataMasking
DataMaskingEntity
DataMaskingMode

Data masking mode.

DiagnosticContract

Diagnostic details.

ErrorFieldContract

Error Field contract.

ErrorResponse

Error Response.

HttpCorrelationProtocol

Sets correlation protocol to use for Application Insights diagnostics.

HttpMessageDiagnostic

Http message diagnostic settings.

OperationNameFormat

The format of the Operation Name for Application Insights telemetries. Default is Name.

PipelineDiagnosticSettings

Diagnostic settings for incoming/outgoing HTTP messages to the Gateway.

SamplingSettings

Sampling settings for Diagnostic.

SamplingType

Sampling type.

Verbosity

The verbosity level applied to traces emitted by trace policies.

AlwaysLog

Specifies for what type of messages sampling settings should not apply.

Name Type Description
allErrors
  • string

Always log all erroneous request regardless of sampling settings.

BodyDiagnosticSettings

Body logging settings.

Name Type Description
bytes
  • integer

Number of request body bytes to log.

DataMasking

Name Type Description
headers

Masking settings for headers

queryParams

Masking settings for Url query parameters

DataMaskingEntity

Name Type Description
mode

Data masking mode.

value
  • string

The name of an entity to mask (e.g. a name of a header or a query parameter).

DataMaskingMode

Data masking mode.

Name Type Description
Hide
  • string

Hide the presence of an entity.

Mask
  • string

Mask the value of an entity.

DiagnosticContract

Diagnostic details.

Name Type Description
id
  • string

Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

name
  • string

The name of the resource

properties.alwaysLog

Specifies for what type of messages sampling settings should not apply.

properties.backend

Diagnostic settings for incoming/outgoing HTTP messages to the Backend

properties.frontend

Diagnostic settings for incoming/outgoing HTTP messages to the Gateway.

properties.httpCorrelationProtocol

Sets correlation protocol to use for Application Insights diagnostics.

properties.logClientIp
  • boolean

Log the ClientIP. Default is false.

properties.loggerId
  • string

Resource Id of a target logger.

properties.operationNameFormat

The format of the Operation Name for Application Insights telemetries. Default is Name.

properties.sampling

Sampling settings for Diagnostic.

properties.verbosity

The verbosity level applied to traces emitted by trace policies.

type
  • string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

ErrorFieldContract

Error Field contract.

Name Type Description
code
  • string

Property level error code.

message
  • string

Human-readable representation of property-level error.

target
  • string

Property name.

ErrorResponse

Error Response.

Name Type Description
error.code
  • string

Service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.

error.details

The list of invalid fields send in request, in case of validation error.

error.message
  • string

Human-readable representation of the error.

HttpCorrelationProtocol

Sets correlation protocol to use for Application Insights diagnostics.

Name Type Description
Legacy
  • string

Inject Request-Id and Request-Context headers with request correlation data. See https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/HttpCorrelationProtocol.md.

None
  • string

Do not read and inject correlation headers.

W3C
  • string

Inject Trace Context headers. See https://w3c.github.io/trace-context.

HttpMessageDiagnostic

Http message diagnostic settings.

Name Type Description
body

Body logging settings.

dataMasking

Data masking settings.

headers
  • string[]

Array of HTTP Headers to log.

OperationNameFormat

The format of the Operation Name for Application Insights telemetries. Default is Name.

Name Type Description
Name
  • string

API_NAME;rev=API_REVISION - OPERATION_NAME

Url
  • string

HTTP_VERB URL

PipelineDiagnosticSettings

Diagnostic settings for incoming/outgoing HTTP messages to the Gateway.

Name Type Description
request

Diagnostic settings for request.

response

Diagnostic settings for response.

SamplingSettings

Sampling settings for Diagnostic.

Name Type Description
percentage
  • number

Rate of sampling for fixed-rate sampling.

samplingType

Sampling type.

SamplingType

Sampling type.

Name Type Description
fixed
  • string

Fixed-rate sampling.

Verbosity

The verbosity level applied to traces emitted by trace policies.

Name Type Description
error
  • string

Only traces with 'severity' set to 'error' will be sent to the logger attached to this diagnostic instance.

information
  • string

Traces with 'severity' set to 'information' and 'error' will be sent to the logger attached to this diagnostic instance.

verbose
  • string

All the traces emitted by trace policies will be sent to the logger attached to this diagnostic instance.