Log Monitoring metrics API - PUT a metric

Updates the descriptor of the specified calculated Log Monitoring metric.

The request consumes and produces an application/json payload.

PUT	ManagedDynatrace for Government	`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}`
	Environment ActiveGate	`https://{your-activegate-domain}:9999/e/{your-environment-id}/api/config/v1/calculatedMetrics/log/{metricKey}`

Authentication

To execute this request, you need an access token with WriteConfig scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter Type Description In Required

metricKey

string

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 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

Request body objects

The `LogMetricConfig` object

Custom log metric definition.

Element	Type	Description	Required
active	boolean	The metric is enabled (`true`) or disabled (`false`).	optional
columnDefiningValue	ColumnDefinition	Definition of numeric column.	optional
displayName	string	The name of the metric, displayed in the UI.	required
logSourceFilters	LogSourceFilter[]	A list of filters to define the logs to look into. If several filters are specified, the OR logic applies.	required
metricKey	string	The unique key of the metric. The key must have the `calc:log.` prefix.	required
metricValueType	string	The type of the metric data points calculation. For now the only allowed value is `OCCURRENCES`. `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`	required
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
unit	string	The unit of the metric. `AMPERE` `BILLION` `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` `GIBI_BYTE_PER_HOUR` `GIBI_BYTE_PER_MINUTE` `GIBI_BYTE_PER_SECOND` `GIGA` `GIGA_BYTE` `GIGA_BYTE_PER_HOUR` `GIGA_BYTE_PER_MINUTE` `GIGA_BYTE_PER_SECOND` `HERTZ` `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` `KILO_METRE_PER_HOUR` `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` `METRE_PER_HOUR` `METRE_PER_SECOND` `MICRO_SECOND` `MILLION` `MILLI_CORES` `MILLI_SECOND` `MILLI_SECOND_PER_MINUTE` `MINUTE` `MONTH` `MSU` `NANO_SECOND` `NANO_SECOND_PER_MINUTE` `NOT_APPLICABLE` `PERCENT` `PER_HOUR` `PER_MINUTE` `PER_SECOND` `PIXEL` `PROMILLE` `RATIO` `SECOND` `STATE` `TRILLION` `UNSPECIFIED` `VOLT` `WATT` `WEEK` `YEAR`	required
unitDisplayName	string	The display name of the unit. Only applicable if the unit is set to `UNSPECIFIED`.	optional

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 `CUSTOM` `JSON`	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
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. `AIX` `DARWIN` `HPUX` `LINUX` `SOLARIS` `WINDOWS` `ZOS`	optional
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

The `PathDefinition` object

A filtering criterion for log path.

Element Type Description Required

definition

string

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. `FIXED` `WILDCARD`	required

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.

FIXED
WILDCARD

required

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

1{
2  "active": true,
3  "displayName": "Sample metric",
4  "logSourceFilters": [
5    {
6      "hostFilters": [
7        "HOST-066703AD79C38DB5"
8      ],
9      "osTypes": [],
10      "pathDefinitions": [
11        {
12          "definition": "/var/log/sample.log",
13          "type": "FIXED"
14        }
15      ],
16      "sourceEntities": [
17        "PROCESS_GROUP_INSTANCE-63FC6E7C73DC893F"
18      ]
19    }
20  ],
21  "metricKey": "calc:log.metric",
22  "metricValueType": "OCCURRENCES",
23  "searchString": "\"memory fault\"",
24  "unit": "HOUR",
25  "unitDisplayName": ""
26}

Response

Response codes

Code	Type	Description
201	EntityShortRepresentation	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	ErrorEnvelope	Failed. The input is invalid.

Response body objects

The `EntityShortRepresentation` object

The short representation of a Dynatrace entity.

Element	Type	Description
description	string	A short description of the Dynatrace entity.
id	string	The ID of the Dynatrace entity.
name	string	The name of the Dynatrace entity.

Response body JSON model

1{
2  "description": "Dynatrace entity for the REST API example",
3  "id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a",
4  "name": "Dynatrace entity"
5}

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.

POST	ManagedDynatrace for Government	`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`
	Environment ActiveGate	`https://{your-activegate-domain}:9999/e/{your-environment-id}/api/config/v1/calculatedMetrics/log/{metricKey}/validator`

Authentication

To execute this request, you need an access token with WriteConfig scope.

To learn how to obtain and use it, see Tokens and authentication.

Response

Response codes

Code	Type	Description
204	-	Validated. The submitted configuration is valid. Response doesn't have a body.
400	ErrorEnvelope	Failed. See the response body for details

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

1curl -X PUT \
2  https://mySampleEnv.live.dynatrace.com/api/config/v1/calculatedMetrics/log/calc:log.unsecuredcall \
3  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
4  -H 'Content-Type: application/json' \
5  -d '{<truncated - see the Request body section >}'

Request URL

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

Request body

1{
2  "metricKey": "calc:log.unsecuredcall",
3  "active": true,
4  "displayName": "Unsecured call",
5  "unit": "COUNT",
6  "searchString": "UNSECURED_SHARED_CALL",
7  "metricValueType": "OCCURRENCES",
8  "logSourceFilters": [
9    {
10      "pathDefinitions": [],
11      "sourceEntities": ["PROCESS_GROUP_INSTANCE-6CD96121AD8F5308"],
12      "hostFilters": ["HOST-5AA1203365B14DBC"],
13      "osTypes": []
14    }
15  ]
16}

Response body

1{
2  "id": "calc:log.unsecuredcall",
3  "name": "Unsecured call"
4}

Response code

201

Log Monitoring metrics API - PUT a metric

Authentication

Parameters

Request body objects

The LogMetricConfig object

The ColumnDefinition object

The LogSourceFilter object

The PathDefinition object

Request body JSON model

Response

Response codes

Response body objects

The EntityShortRepresentation object

Response body JSON model

Validate payload

Authentication

Response

Response codes

Example

Curl

Request URL

Request body

Response body

Response code

Related topics

The `LogMetricConfig` object

The `ColumnDefinition` object

The `LogSourceFilter` object

The `PathDefinition` object

The `EntityShortRepresentation` object