Log monitoring metrics API - PUT a metric

Updates the definition of the specified custom log metric.

The request consumes and produces an application/json payload.

This request is currently in preview and is subject to change. Changes may not be compatible with your current configuration.

PUT
  • Managed https://{your-domain}/e/{your-environment-id}/api/config/v1/customMetric/log/{metricKey}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/customMetric/log/{metricKey}

Parameters

Parameter Type Description In Required
metricKey string

The key of the metric to create or update. The key of the log metric in the body of the request must match this key.

path required
body LogMetricConfig

JSON body of the request containing custom log metric definition.

body optional

The LogMetricConfig object

Log Analytics metric configuration.

Element Type Description Required
metricKey string

A unique metric key.

required
active boolean

Metric activity flag. Value 'false' means metric is ignored when detecting metric occurrences.

optional
displayName string

The name of this subscribed metric. Should not be empty.

required
unit string

Metric unit.

The unit element can hold these values.
required
unitDisplayName string

The unit display name. Taken into account if unit is 'UNSPECIFIED'.

optional
searchString string

Text pattern to search in logs in form of Dynatrace Search Query Language. When blank every log entry is assumed as matching.

required
metricValueType string

Defines metric value i.e. how the value is calculated.

The metricValueType element can hold these values.
required
logSourceFilters LogSourceFilter[]

Defines list of filters on log source. Separate source filters from this collection are joined with OR operator.

required

The LogSourceFilter object

Defines filtering conditions on log source various attributes (filtering criteria). Various filtering criteria (e.g. pathDefinitions and sourceEntities) from this filter are joined with AND operator with exception of hostFilters and hostGroups that are joined with OR operator.

Element Type Description Required
pathDefinitions PathDefinition[]

List of filtering conditions on log path. Joined with OR operator if specified more than one.

optional
sourceEntities string[]

List of Dynatrace entity IDs that log can originate from. Allowed types of entities: PROCESS_GROUP, PROCESS_GROUP_INSTANCE. Entity types cannot be mixed. Can be specified only alternatively to filtering criteria: osTypes.

optional
hostFilters string[]

List of hosts as Dynatrace entity IDs that log can originate from. Can be specified only alternatively to filtering criteria: sourceTypes. Collection elements are joined with OR operator.

optional
osTypes string[]

OS types as Dynatrace OS identifiers related to log file originating host. When specified, operating system logs are filtered. Can be specified only alternatively to filtering criteria: sourceEntities, sourceTypes.

optional

The PathDefinition object

Defines filtering condition on log path.

Element Type Description Required
definition string

Log path. If type is WILDCARD, may contain '*' characters working as wildcards

required
type string

Specifies log path definition type: FIXED or WILDCARD.

The type element can hold these values.
required

Possible values

Possible values for the items element in the LogSourceFilter object:

  • AIX
  • DARWIN
  • HPUX
  • LINUX
  • SOLARIS
  • WINDOWS
  • ZOS

Possible values for the type element in the PathDefinition object:

  • FIXED
  • WILDCARD

Possible values for the metricValueType element in the LogMetricConfig object:

  • OCCURRENCES

Possible values for the unit element in the LogMetricConfig object:

  • BIT
  • BIT_PER_HOUR
  • BIT_PER_MINUTE
  • BIT_PER_SECOND
  • BYTE
  • BYTE_PER_HOUR
  • BYTE_PER_MINUTE
  • BYTE_PER_SECOND
  • CORES
  • COUNT
  • GIBI_BYTE
  • GIGA_BYTE
  • HOUR
  • KIBI_BYTE
  • KIBI_BYTE_PER_HOUR
  • KIBI_BYTE_PER_MINUTE
  • KIBI_BYTE_PER_SECOND
  • KILO_BYTE
  • KILO_BYTE_PER_HOUR
  • KILO_BYTE_PER_MINUTE
  • KILO_BYTE_PER_SECOND
  • MEBI_BYTE
  • MEBI_BYTE_PER_HOUR
  • MEBI_BYTE_PER_MINUTE
  • MEBI_BYTE_PER_SECOND
  • MEGA_BYTE
  • MEGA_BYTE_PER_HOUR
  • MEGA_BYTE_PER_MINUTE
  • MEGA_BYTE_PER_SECOND
  • MICRO_SECOND
  • MILLI_CORES
  • MILLI_SECOND
  • MILLI_SECOND_PER_MINUTE
  • MINUTE
  • NANO_SECOND
  • NANO_SECOND_PER_MINUTE
  • NOT_APPLICABLE
  • PERCENT
  • PER_HOUR
  • PER_MINUTE
  • PER_SECOND
  • PROMILLE
  • RATIO
  • SECOND
  • STATE
  • UNSPECIFIED

Response format

The EntityShortRepresentation object

The short representation of a Dynatrace entity.

Element Type Description
id string

The ID of the Dynatrace entity.

name string

The name of the Dynatrace entity.

description string

A short description of the Dynatrace entity.

Response codes

Code Description
201

Success. The new log metric has been created. The response body contains its key and name.

204

Success. Log metric definition has been updated. Response doesn't have a body.

400

Failed. The input is invalid.

Validate payload

We recommend that you validate the payload before submitting it with an actual request. A response code of 204 indicates a valid payload.

The request consumes an application/json payload.

This request is currently in preview and is subject to change. Changes may not be compatible with your current configuration.

POST
  • Managed https://{your-domain}/e/{your-environment-id}/api/config/v1/customMetric/log/{metricKey}/validator
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/customMetric/log/{metricKey}/validator

Response codes

Code Description
204 Validated. The submitted configuration is valid. Response does not have a body.
400 Failed. The input is invalid.

Example

In this example, the request creates a new custom log metric with the key of calc:log.unsecuredcall. The metric counts the occurrences of the phrase UNSECURED_SHARED_CALL in all logs from the process with Dynatrace entity ID PROCESS_GROUP_INSTANCE-6CD96121AD8F5308 that runs on the host with Dynatrace entity ID HOST-5AA1203365B14DB.

The API token is passed in the Authorization header.

Because the request body is lengthy, it is truncated in this example Curl section. See the full body in the Request body section. You can download or copy the example request body to try it out on your own. Before using it, make sure that you're using Dynatrace entity IDs that are available in your environment.

Curl

curl -X PUT \
  https://mySampleEnv.live.dynatrace.com/api/config/v1/customMetric/log/calc:log.unsecuredcall \
  -H 'Authorization: Api-token abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \
  -d '{<truncated - see the Request body section >}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/config/v1/customMetric/log/calc:log.unsecuredcall

Request body

api-examples/config/log-monitoring/metrics/put.json
Download
{
  "metricKey": "calc:log.unsecuredcall",
  "active": true,
  "displayName": "Unsecured call",
  "unit": "COUNT",
  "searchString": "UNSECURED_SHARED_CALL",
  "metricValueType": "OCCURRENCES",
  "logSourceFilters": [
    {
      "pathDefinitions": [],
      "sourceEntities": [
        "PROCESS_GROUP_INSTANCE-6CD96121AD8F5308"
      ],
      "hostFilters": [
        "HOST-5AA1203365B14DBC"
      ],
      "osTypes": []
    }
  ]
}

Response body

{
  "id": "calc:log.unsecuredcall",
  "name": "Unsecured call"
}

Response code

201