Timeseries API - 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 |
|
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
timeseriesIdentifier | string |
The ID for the new metric. It must start with the 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 |
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 |
optional |
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.
{
"displayName": "received.coffees",
"unit": "Count",
"dimensions": [
"coffee"
],
"types": [
"coffee machine"
]
}
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)
- 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)
- 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)
- N/A
- NanoSecond (ns)
- NanoSecondPerMinute (ns/min)
- PerHour (count/h)
- PerMinute (count/min)
- PerSecond (count/s)
- Percent (%)
- Promille (‰)
- Ratio
- Second (s)
- State
- Unspecified
- 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. |
unit | string | The unit of the metric. |
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. |
aggregationTypes | string[] | The list of allowed aggregations for this metric. |
filter | string | The feature, where the metric originates. |
{}
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.dexp.ae/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.dexp.ae/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