Timeseries API v1 - PUT a custom metric

Registers your custom metric. You need to specify the ID, the display name, and type of the metric.

If you use the ID of an existing metric, the respective parameters will be updated.

The request consumes and produces an application/json payload.

PUT
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/timeseries/{timeseriesIdentifier}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/timeseries/{timeseriesIdentifier}

Authentication

To execute this request, you need the Access problem and event feed, metrics, and topology (DataExport) permission assigned to your API token. To learn how to obtain and use it, see Authentication.

Parameters

Parameter Type Description In Required
timeseriesIdentifier string

The ID for the new metric. It must start with the custom: prefix.

You can use alphanumeric characters and the following punctuation marks: periods (.), hyphens (-), and commas (,). A number cannot follow a punctuation mark.

If you use the ID of an existing metric the respective parameters will be updated.

path required
body TimeseriesRegistrationMessage

The JSON body of the request, containing metric parameters.

body optional

The TimeseriesRegistrationMessage object

The definition of a custom metric.

Element Type Description Required
displayName string

The name of the metric that will appear in the user interface. It is limited to 256 characters.

optional
unit string

The unit the metric will use. If the parameter is not specified or the wrong value is specified, the Count value will be assigned.

The unit element can hold these values.
optional
dimensions string[]

The metric dimension key that will be used to report multiple dimensions. For example, a dimension key to report the metric for different network cards for the same firewall.

The name of dimensions is only allowed to contain alphanumeric characters, dots ., hyphens -, and underscores _.

The CUSTOM_DEVICE dimension is added to each new custom metric automatically.

optional
types string[]

The definition of the technology type. Used to group metrics under a logical technology name in the UI.

Metrics must be assigned a software technology type that is identical to the technology type of the custom device you are sending the metric to.

For example, if you define your custom device using type F5-Firewall you must also register all related custom metrics as type F5-Firewall.

optional

Possible values

Possible values for the unit element in the TimeseriesRegistrationMessage object:

  • Bit (bit)
  • BitPerHour (bit/h)
  • BitPerMinute (bit/min)
  • BitPerSecond (bit/s)
  • Byte (B)
  • BytePerHour (B/h)
  • BytePerMinute (B/min)
  • BytePerSecond (B/s)
  • Cores
  • Count (count)
  • Day (ds)
  • G
  • GibiByte (GiB)
  • GigaByte (GB)
  • Hour (hs)
  • KibiByte (KiB)
  • KibiBytePerHour (KiB/h)
  • KibiBytePerMinute (KiB/min)
  • KibiBytePerSecond (KiB/s)
  • KiloByte (kB)
  • KiloBytePerHour (kB/h)
  • KiloBytePerMinute (kB/min)
  • KiloBytePerSecond (kB/s)
  • M
  • MebiByte (MiB)
  • MebiBytePerHour (MiB/h)
  • MebiBytePerMinute (MiB/min)
  • MebiBytePerSecond (MiB/s)
  • MegaByte (MB)
  • MegaBytePerHour (MB/h)
  • MegaBytePerMinute (MB/min)
  • MegaBytePerSecond (MB/s)
  • MicroSecond (µs)
  • MilliSecond (ms)
  • MilliSecondPerMinute (ms/min)
  • Minute (mins)
  • Month (mos)
  • N/A
  • NanoSecond (ns)
  • NanoSecondPerMinute (ns/min)
  • PerHour (count/h)
  • PerMinute (count/min)
  • PerSecond (count/s)
  • Percent (%)
  • Pixel (px)
  • Promille (‰)
  • Ratio
  • Second (s)
  • State
  • Unspecified
  • Week (ws)
  • Year (ys)
  • k
  • mCores

Response format

The result is JSON containing the metadata of the newly created metric.

The TimeseriesDefinition object

The configuration of a metric with all its parameters.

Element Type Description
timeseriesId string

The ID of the metric.

displayName string

The name of the metric in the user interface.

dimensions string[]

The fine metric division, for example process group and process ID for some process-related metric.

aggregationTypes string[]

The list of allowed aggregations for this metric.

unit string

The unit of the metric.

The unit element can hold these values.
filter string

The feature, where the metric originates.

The filter element can hold these values.
detailedSource string

The feature, where the metric originates.

pluginId string

The ID of the plugin, where the metric originates.

types string[]

Technology type definition. Used to group metrics under a logical technology name.

Possible values

Possible values for the filter element in the TimeseriesDefinition object:

  • ALL
  • BUILTIN
  • CUSTOM
  • PLUGIN
  • REMOTE_PLUGIN

Possible values for the unit element in the TimeseriesDefinition object:

  • Bit (bit)
  • BitPerHour (bit/h)
  • BitPerMinute (bit/min)
  • BitPerSecond (bit/s)
  • Byte (B)
  • BytePerHour (B/h)
  • BytePerMinute (B/min)
  • BytePerSecond (B/s)
  • Cores
  • Count (count)
  • Day (ds)
  • G
  • GibiByte (GiB)
  • GigaByte (GB)
  • Hour (hs)
  • KibiByte (KiB)
  • KibiBytePerHour (KiB/h)
  • KibiBytePerMinute (KiB/min)
  • KibiBytePerSecond (KiB/s)
  • KiloByte (kB)
  • KiloBytePerHour (kB/h)
  • KiloBytePerMinute (kB/min)
  • KiloBytePerSecond (kB/s)
  • M
  • MebiByte (MiB)
  • MebiBytePerHour (MiB/h)
  • MebiBytePerMinute (MiB/min)
  • MebiBytePerSecond (MiB/s)
  • MegaByte (MB)
  • MegaBytePerHour (MB/h)
  • MegaBytePerMinute (MB/min)
  • MegaBytePerSecond (MB/s)
  • MicroSecond (µs)
  • MilliSecond (ms)
  • MilliSecondPerMinute (ms/min)
  • Minute (mins)
  • Month (mos)
  • N/A
  • NanoSecond (ns)
  • NanoSecondPerMinute (ns/min)
  • PerHour (count/h)
  • PerMinute (count/min)
  • PerSecond (count/s)
  • Percent (%)
  • Pixel (px)
  • Promille (‰)
  • Ratio
  • Second (s)
  • State
  • Unspecified
  • Week (ws)
  • Year (ys)
  • k
  • mCores

Possible values for the aggregationTypes element in the TimeseriesDefinition object:

  • AVG
  • COUNT
  • MAX
  • MEDIAN
  • MIN
  • PERCENTILE
  • SUM

Example

In this example, the request creates a new custom metric with the custom:firewall.connections.dropped ID of the F5-Firewall type. Its unit is count. The nic dimension key is used to report the metric for different network cards for the same firewall.

The API token is passed in the Authorization header.

The request returns parameters of the newly created metric as confirmation.

Curl

curl -X PUT \
  https://mySampleEnv.live.dynatrace.com/api/v1/timeseries/custom:firewall.connections.dropped \
  -H 'Authorization: Api-Token abcdefjhij1234567890' \  
  -H 'Content-Type: application/json' \  
  -d '{
	"displayName" : "Dropped TCP connections",
	"unit" : "Count",
	"dimensions": [		
		"nic"
	],
	"types": [
		"F5-Firewall"
	]
}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v1/timeseries/custom:firewall.connections.dropped

Request body

{
  "displayName" : "Dropped TCP connections",
  "unit" : "Count",
	"dimensions": [
    "nic"
  ],
  "types": [
    "F5-Firewall"
	]
}

Response body

{
  "timeseriesId": "custom:firewall.connections.dropped",
  "displayName": "Dropped TCP connections",
  "dimensions": [
    "CUSTOM_DEVICE",
    "nic"
  ],
  "unit": "Count (count)",
  "detailedSource": "API",
  "types": [
    "F5-Firewall"
  ],
  "aggregationTypes": [
    "AVG",
    "SUM",
    "MIN",
    "MAX"
  ],
  "filter": "CUSTOM"
}

Response code

201