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	ManagedDynatrace for Government	`https://{your-domain}/e/{your-environment-id}/api/v1/timeseries/{timeseriesIdentifier}`
	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v1/timeseries/{timeseriesIdentifier}`
	Environment ActiveGate	`https://{your-activegate-domain}/e/{your-environment-id}/api/v1/timeseries/{timeseriesIdentifier}`

Authentication

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

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

Parameters

Parameter Type Description In Required

timeseriesIdentifier

string

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. The length of ID is limited to 256 characters.	path	required
body	TimeseriesRegistrationMessage	The JSON body of the request. Contains parameters of the new custom metric.	body	optional

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.

The length of ID is limited to 256 characters.

path

required

body

TimeseriesRegistrationMessage

The JSON body of the request. Contains parameters of the new custom metric.

body

optional

Request body objects

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. To edit the value of that field, you need the Write configuration (`WriteConfig`) or the Write settings (`settings.write`) permission assigned to your API token.	optional
unit	string	The unit the metric will use. To edit the value of that field, you need the Write configuration (`WriteConfig`) or the Write settings (`settings.write`) permission assigned to your API token. The element can hold these values `Billion (Gcount)` `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)` `DecibelMilliWatt (dBm)` `G` `GibiByte (GiB)` `GibiBytePerHour (GiB/h)` `GibiBytePerMinute (GiB/min)` `GibiBytePerSecond (GiB/s)` `GigaByte (GB)` `GigaBytePerHour (GB/h)` `GigaBytePerMinute (GB/min)` `GigaBytePerSecond (GB/s)` `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` `MSU` `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)` `Million (Mcount)` `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` `Trillion (Tcount)` `Unspecified` `Week (ws)` `Year (ys)` `k` `km/h` `m/h` `m/s` `mCores`	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. You can use alphanumeric characters and the following punctuation marks: periods (`.`), hyphens (`-`), and underscores (`_`). The CUSTOM_DEVICE dimension is added to each new custom metric automatically. The length of dimension keys and values is limited to 128 characters each.	optional
types	string[]	The definition of the technology type. It is 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`. The field is required when creating a new metric.	optional

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.

json
{
  "displayName": "received.coffees",
  "unit": "Count",
  "dimensions": [
    "coffee"
  ],
  "types": [
    "coffee machine"
  ]
}

Response

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

Response codes

Code	Type	Description
201	TimeseriesDefinition	Success. The custom metric has been created.

Response body objects

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. The element can hold these values `AVG` `COUNT` `MAX` `MEDIAN` `MIN` `PERCENTILE` `SUM`
unit	string	The unit of the metric. The element can hold these values `Billion (Gcount)` `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)` `DecibelMilliWatt (dBm)` `G` `GibiByte (GiB)` `GibiBytePerHour (GiB/h)` `GibiBytePerMinute (GiB/min)` `GibiBytePerSecond (GiB/s)` `GigaByte (GB)` `GigaBytePerHour (GB/h)` `GigaBytePerMinute (GB/min)` `GigaBytePerSecond (GB/s)` `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` `MSU` `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)` `Million (Mcount)` `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` `Trillion (Tcount)` `Unspecified` `Week (ws)` `Year (ys)` `k` `km/h` `m/h` `m/s` `mCores`
filter	string	The feature, where the metric originates. The element can hold these values `ALL` `BUILTIN` `CUSTOM` `PLUGIN` `REMOTE_PLUGIN`
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.
warnings	string[]	The warnings that occurred while creating the metric.

Response body JSON model

json
{
  "timeseriesId": "com.dynatrace.builting:host.cpu.idle",
  "displayName": "CPU idle",
  "dimensions": [
    "HOST"
  ],
  "aggregationTypes": [
    "AVG",
    "SUM",
    "MIN",
    "MAX"
  ],
  "unit": "Percent",
  "filter": "BUILTIN",
  "detailedSource": "Infrastructure",
  "types": [
    "Test"
  ],
  "warnings": []
}

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

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

Request URL

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

Request body

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

Response body

json
{
  "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

Timeseries API v1 - PUT a custom metric

Authentication

Parameters

Request body objects

The TimeseriesRegistrationMessage object

Request body JSON model

Response

Response codes

Response body objects

The TimeseriesDefinition object

Response body JSON model

Example

Curl

Request URL

Request body

Response body

Response code

The `TimeseriesRegistrationMessage` object

The `TimeseriesDefinition` object