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=2019-01-01

URI Parameters

Name In Required Type Description
subscriptionId
path True
  • string

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

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])?$

diagnosticId
path True
  • string

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

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

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.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.enableHttpCorrelationHeaders
  • boolean

Whether to process Correlation Headers coming to Api Management Service. Only applicable to Application Insights diagnostics. Default is true.

properties.frontend

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

properties.loggerId True
  • string

Resource Id of a target logger.

properties.sampling

Sampling settings for Diagnostic.

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=2019-01-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.

DiagnosticContract

Diagnostic details.

ErrorFieldContract

Error Field contract.

ErrorResponse

Error Response.

HttpMessageDiagnostic

Http message diagnostic settings.

PipelineDiagnosticSettings

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

SamplingSettings

Sampling settings for Diagnostic.

SamplingType

Sampling type.

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.

DiagnosticContract

Diagnostic details.

Name Type Description
id
  • string

Resource ID.

name
  • string

Resource name.

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.enableHttpCorrelationHeaders
  • boolean

Whether to process Correlation Headers coming to Api Management Service. Only applicable to Application Insights diagnostics. Default is true.

properties.frontend

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

properties.loggerId
  • string

Resource Id of a target logger.

properties.sampling

Sampling settings for Diagnostic.

type
  • string

Resource type for API Management resource.

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.

HttpMessageDiagnostic

Http message diagnostic settings.

Name Type Description
body

Body logging settings.

headers
  • string[]

Array of HTTP Headers to log.

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.