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.

Early Adopter

This request is an Early Adopter release and may be changed in non-compatible way.

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

Authentication

To execute this request, you need the Write configuration (WriteConfig) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter Type Description In Required
metricKey string

The required key of the custom log metric. The key must have the calc:log. prefix.

The key in the body of the request must match this key.

path required
body LogMetricConfig

The JSON body of the request. Contains the definition of the custom log metric.

body optional

The LogMetricConfig object

Custom log metric definition.

Element Type Description Required
metricKey string

The unique key of the metric.

The key must have the calc:log. prefix.

required
active boolean

The metric is enabled (true) or disabled (false).

optional
displayName string

The name of the metric, displayed in the UI.

required
unit string

The unit of the metric.

The unit element can hold these values.
required
unitDisplayName string

The display name of the unit.

Only applicable if the unit is set to UNSPECIFIED.

optional
searchString string

The pattern to look for in logs.

Use the Dynatrace search query language to specify it. Quotes must be escaped.

To return all results, leave the field blank.

required
metricValueType string

The type of the metric data points calculation. For now the only allowed value is OCCURRENCES.

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

A list of filters to define the logs to look into.

If several filters are specified, the OR logic applies.

required

The LogSourceFilter object

Configuration of the log filter for a custom log metric.

If several criteria are specified, the AND logic applies.

Element Type Description Required
pathDefinitions PathDefinition[]

A list of filtering criteria for log path.

If several criteria are specified, the OR logic applies.

optional
sourceEntities string[]

A list of Dynatrace entities, where the log can originate from. Specify Dynatrace entity IDs here.

Allowed types of entities are PROCESS_GROUP and PROCESS_GROUP_INSTANCE. You can't mix entity types.

If several entities are specified, the OR logic applies.

This field is mutually exclusive with the osTypes field.

optional
hostFilters string[]

A list of hosts, where the log can originate from. Specify Dynatrace entity IDs here.

If several hosts are specified, the OR logic applies.

optional
osTypes string[]

A list of operating system types, where the log can originate from.

If set, only OS logs are included in the result.

If several OS are specified, the OR logic applies.

This field is mutually exclusive with the sourceEntities field.

The osTypes element can hold these values.
optional

The PathDefinition object

A filtering criterion for log path.

Element Type Description Required
definition string

The path to the required log path.

If the type is set to WILDCARD, it may contain wildcard characters (*).

required
type string

The type of the log path definition: fixed or an expression with wildcards.

The type element can hold these values.
required

The ColumnDefinition object

Definition of numeric column.

Element Type Description Required
name string required
type string

Defines the actual set of fields depending on the value. See one of the following objects:

  • CUSTOM -> CustomColumnDefinition
  • JSON -> JsonColumnDefinition
The type element can hold these values.
required

Possible values

Possible values for the osTypes 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 type element in the ColumnDefinition object:

  • CUSTOM
  • JSON

Possible values for the metricValueType element in the LogMetricConfig object:

  • FP_COLUMN_AVG
  • FP_COLUMN_COUNT
  • FP_COLUMN_MAX
  • FP_COLUMN_MIN
  • FP_COLUMN_SUM
  • FP_COLUMN_TOP_X_AVG
  • FP_COLUMN_TOP_X_COUNT
  • FP_COLUMN_TOP_X_MAX
  • FP_COLUMN_TOP_X_MIN
  • FP_COLUMN_TOP_X_SUM
  • INT_COLUMN_AVG
  • INT_COLUMN_COUNT
  • INT_COLUMN_MAX
  • INT_COLUMN_MIN
  • INT_COLUMN_SUM
  • INT_COLUMN_TOP_X_AVG
  • INT_COLUMN_TOP_X_COUNT
  • INT_COLUMN_TOP_X_MAX
  • INT_COLUMN_TOP_X_MIN
  • INT_COLUMN_TOP_X_SUM
  • 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
  • DAY
  • DECIBEL_MILLI_WATT
  • GIBI_BYTE
  • GIGA
  • GIGA_BYTE
  • HOUR
  • KIBI_BYTE
  • KIBI_BYTE_PER_HOUR
  • KIBI_BYTE_PER_MINUTE
  • KIBI_BYTE_PER_SECOND
  • KILO
  • 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
  • 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
  • MONTH
  • NANO_SECOND
  • NANO_SECOND_PER_MINUTE
  • NOT_APPLICABLE
  • PERCENT
  • PER_HOUR
  • PER_MINUTE
  • PER_SECOND
  • PIXEL
  • PROMILLE
  • RATIO
  • SECOND
  • STATE
  • UNSPECIFIED
  • WEEK
  • YEAR

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 metric definition has been created. The response body contains the key and the name of the new metric.

204

Success. The 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.

The request consumes an application/json payload.

Early Adopter

This request is an Early Adopter release and may be changed in non-compatible way.

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

Authentication

To execute this request, you need the Write configuration (WriteConfig) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.

Response codes

Code Description
204 Validated. The submitted configuration is valid. Response doesn't 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/calculatedMetrics/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/calculatedMetrics/log/calc:log.unsecuredcall

Request body

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