DCI

Represents Data Collection Item (DCI).

Instance attributes

activeThresholdSeverity: int: Severity of the active threshold. If there are no active thresholds, defaults to 0 (NORMAL).

cachedRawValue ⇒ String or Table: Last collected raw value from the in-memory cache. For single value DCIs the value is returned as a string; for table DCIs it is a Table object, or null if the table has no value yet.

cachedValue ⇒ String or Table: Last collected (transformed) value from the in-memory cache. For single value DCIs the value is converted to the DCI’s transformed data type (integer or floating point for numeric types, string otherwise); for table DCIs it is a Table object. Returns null if the DCI has no value yet.

comments: String: DCI Comments

currentRawValue ⇒ String or Table: Same as cachedRawValue, but returns null if the DCI is in error state.

currentValue ⇒ String or Table: Same as cachedValue, but returns null if the DCI is in error state.

dataType: int: Data type of the DCI. null for table DCIs.

description: String: Description

errorCount: int: Number of consecutive data collection errors

flags: int: DCI flags

hasActiveThreshold: bool: TRUE if DCI has active threshold

id: int: Unique DCI identifier

instance: String: DCI instance (only for single value DCIs): %{instance}

instanceName: String: DCI instance name (only for single value DCIs): %{instance-name}

instanceValue: String: Alias for instance.

lastPollTime: int64: Time of last DCI poll (either successful or not) as number of milliseconds since epoch (1 Jan 1970 00:00:00 UTC).

lastCollectionTime: int64: Time of last successful DCI poll as number of milliseconds since epoch (1 Jan 1970 00:00:00 UTC).

Added in version 4.0

mappingTableId: int: ID of the mapping table assigned to this DCI, or 0 if no mapping table is assigned. null for table DCIs.

name: String: Name of the metric collected by this DCI

origin: int: Data origin of the DCI.

owner ⇒ NetObj: Object this DCI belongs to (node, cluster, template, etc.), or null if the owner object no longer exists.

ownerId: int: ID of the object this DCI belongs to.

pollingInterval: int: Effective polling interval in seconds (the custom interval if one is set, otherwise the server default interval)

pollingSchedules: Array: Array of custom schedules in cron format

pollingScheduleType: int

Collection schedule:

0 = Server default interval
1 = Custom interval
2 = Advanced schedule

relatedObject ⇒ NetObj: Related object or null if there is no object

status: int: Data status of the DCI.

systemTag: String: System tag. Contains information about DCI Interpretation.

template ⇒ Template: Template object if DCI came from Template or NULL.

templateId: int: Template id if DCI came from Template or 0.

templateItemId: int: DCI item id in template if DCI came from Template or 0.

thresholdDisableEndTime: int: UNIX time (number of seconds since epoch) till which threshold processing for this DCI is disabled. -1 if threshold processing is disabled infinitely. 0 if threshold processing is enabled.

transformedDataType: int: Data type of the value after transformation. null for table DCIs.

type: int

DCI type:

1 = single value
2 = table

userTag: String: User tag.

Added in version 5.2

Instance methods

delete(): bool

Delete this DCI from its owner object. DCIs created from a template are managed by that template and cannot be deleted this way.

Return

true on success, false on failure (caller has no modify access to the owner object, DCI was created from a template, or owner object or DCI no longer exists).

for (dci : $node.findAllDCIs("Temporary.*"))
   dci.delete();

detectAnomalies(timeFrom, timeTo, threshold): Array

Detect anomalies for this DCI within the given period. Only works for single value DCIs.

Table 1. Parameters
timeFrom	Integer	Start of the period (as UNIX timestamp, in seconds).
timeTo	Integer	End of the period (as UNIX timestamp, in seconds). Optional, current time is used if not specified.
threshold	Number	Anomaly detection threshold. Optional, defaults to 0.75.

Return

Array of ScoredDciValue objects with an anomaly score at or above threshold, sorted by score (highest first), or null on error or if there is no data for the period.

dci = $node.findDCIByName("System.CPU.Usage");
anomalies = dci.detectAnomalies(time() - 86400); // Last 24 hours
for (a : anomalies)
   println("Timestamp: " .. a.timestamp .. " Value: " .. a.value .. " Score: " .. a.score);

enable(flag): bool

Enable or disable data collection for this DCI.

Table 2. Parameters
flag	Boolean	`true` to enable data collection, `false` to disable.

Return

true on success, false on failure (caller has no modify access to the owner object or the DCI, or owner object or DCI no longer exists).

// Disable all SNMP DCIs on nodes without SNMP support
if (!$node.isSNMP)
{
   for (dci : $node.findAllDCIs())
   {
      if (dci.origin == DataSource::SNMP)
         dci.enable(false);
   }
}

forcePoll(): void: Start DCI force poll.

generateAnomalyProfile(): bool: Triggers asynchronous generation of an AI-based anomaly detection profile for this DCI. Only works for single value DCIs.

Return

true if profile generation was started, false if DCI is not a single value type.

getAverageValue(timeFrom, timeTo): String

Get the average value of this DCI for the given period. Only works for single value DCIs of numeric type.

Table 3. Parameters
timeFrom	Integer	Start of the period (as UNIX timestamp, in seconds).
timeTo	Integer	End of the period (as UNIX timestamp, in seconds). Optional, current time is used if not specified.

Return

Average value as string, or null on failure, if there is no data for the period, or if this is a table DCI.

dci = $node.findDCIByName("System.CPU.Usage");
avg = dci.getAverageValue(time() - 3600); // Average over last hour
println("Average CPU: " .. avg);

getMaxValue(timeFrom, timeTo): String

Get the maximum value of this DCI for the given period. Only works for single value DCIs of numeric type.

Table 4. Parameters
timeFrom	Integer	Start of the period (as UNIX timestamp, in seconds).
timeTo	Integer	End of the period (as UNIX timestamp, in seconds). Optional, current time is used if not specified.

Return

Maximum value as string, or null on failure, if there is no data for the period, or if this is a table DCI.

getMinValue(timeFrom, timeTo): String

Get the minimum value of this DCI for the given period. Only works for single value DCIs of numeric type.

Table 5. Parameters
timeFrom	Integer	Start of the period (as UNIX timestamp, in seconds).
timeTo	Integer	End of the period (as UNIX timestamp, in seconds). Optional, current time is used if not specified.

Return

Minimum value as string, or null on failure, if there is no data for the period, or if this is a table DCI.

getSumValue(timeFrom, timeTo): String

Get the sum of values of this DCI for the given period. Only works for single value DCIs of numeric type.

Table 6. Parameters
timeFrom	Integer	Start of the period (as UNIX timestamp, in seconds).
timeTo	Integer	End of the period (as UNIX timestamp, in seconds). Optional, current time is used if not specified.

Return

Sum of values as string, or null on failure, if there is no data for the period, or if this is a table DCI.

getValues(timeFrom, timeTo, rawValue, tier, function): Array

Get all collected values for this DCI within the given period. Only works for single value DCIs.

Table 7. Parameters
timeFrom	Integer	Start of the period (as UNIX timestamp, in seconds).
timeTo	Integer	End of the period (as UNIX timestamp, in seconds). Optional, current time is used if not specified.
rawValue	Boolean	`true` to return raw values, `false` for transformed values. Optional, defaults to `false`.
tier	String	Data tier to read from: `"auto"`, `"raw"`, `"hourly"`, or `"daily"` (case-insensitive). Optional, defaults to `"auto"`. Ignored when `rawValue` is `true`. An explicitly requested aggregated tier falls back to raw data when aggregation is not available for this DCI. Any other name causes a runtime error.
function	String	Aggregation function for tiered data: `"avg"`, `"min"`, or `"max"` (case-insensitive). Optional, defaults to `"avg"`. Any other name, including `"minmax"`, causes a runtime error.

Return

Array of value strings ordered from latest to earliest, or null on failure or if this is a table DCI.

dci = $node.findDCIByName("System.CPU.Usage");
values = dci.getValues(time() - 3600); // Values for last hour
for (v : values)
   println(v);

getValuesAsDataPoints(timeFrom, timeTo, rawValue, tier, function): Array

Get all collected values for this DCI within the given period as DataPoint objects. Only works for single value DCIs.

Table 8. Parameters
timeFrom	Integer	Start of the period (as UNIX timestamp, in seconds).
timeTo	Integer	End of the period (as UNIX timestamp, in seconds). Optional, current time is used if not specified.
rawValue	Boolean	`true` to return raw values, `false` for transformed values. Optional, defaults to `false`.
tier	String	Data tier to read from: `"auto"`, `"raw"`, `"hourly"`, or `"daily"` (case-insensitive). Optional, defaults to `"auto"`. Ignored when `rawValue` is `true`. An explicitly requested aggregated tier falls back to raw data when aggregation is not available for this DCI. Any other name causes a runtime error.
function	String	Aggregation function for tiered data: `"avg"`, `"min"`, or `"max"` (case-insensitive). Optional, defaults to `"avg"`. Any other name, including `"minmax"`, causes a runtime error.

Return

Array of DataPoint objects ordered from latest to earliest, or null on failure or if this is a table DCI.

timeFrom and timeTo are in seconds, but the returned DataPoint objects contain timestamps in milliseconds since epoch.

dci = $node.findDCIByName("System.CPU.Usage");
dataPoints = dci.getValuesAsDataPoints(time() - 3600);
for (dp : dataPoints)
   println("Timestamp: " .. dp.timestamp .. ", Value: " .. dp.value);