Try it free

Smartscape - Extensions - Networking

  • Latest Dynatrace
  • Reference

This section documents the generic network model for Smartscape. The model consists of two entities - Network Device and Network Interface - which are populated by network extensions and integrations (both Dynatrace-developed and custom).

IDs

The Smartscape ID for Network Devices (EXT_NETWORK_DEVICE) is calculated based on the its chassis' MAC address which can be defined as the first valid MAC address assigned to the device components.

For Network Interfaces (EXT_NETWORK_INTERFACE) the Smartscape ID is calculated based on both the underlying device's chassis MAC address as well as the interface's name.

Device types

The device_type field allows narrowing down the scope of queries by the device's technology type. Within the SNMP Autodiscovery extension, this value is computed based on the device's System Object ID (1.3.6.1.2.1.1.2) and allows mapping to a recommended Dynatrace Extension for further monitoring.

Integrators can reuse the same value or provide their own alternative to describe the general family of such devices.

Monitoring modes

The monitoring_mode field indicates the level of data available for a particular device. SNMP Autodiscovery uses two such values:

  • Discovery - indicates that the device is part of the extension's discovery configuration and it has been polled successfully. The entity has complete metadata information, but lacks any health/performance insights - it is a candidate for monitoring with the recommended extension.
  • Neighbor - indicates that the device has not been polled directly but is referenced by another device as a link neighbor. The entity was created from potentially incomplete data and will be replaced once direct polling is enabled.

Dynatrace Extensions as well as other integrators are advised to use the value Extension. This indicates that the device is polled directly and benefits of monitoring insights from a specialized integration.

Network Device

Smartscape node type: EXT_NETWORK_DEVICE

A Network Device entity. Represents a physical device with network connectivity.

Query

Fetch all network device entities.

smartscapeNodes EXT_NETWORK_DEVICE

Count network devices by their monitoring mode.

smartscapeNodes EXT_NETWORK_DEVICE
| summarize count(), by: { monitoring_mode }

Find devices that are network neighbors and include their names.

smartscapeEdges calls
| filter target_type == "EXT_NETWORK_DEVICE"
| fieldsAdd source_name=getNodeName(source_id), target_name=getNodeName(target_id)

Query all SNMP Trap logs and add the associated network device information

fetch logs
| filter contains(log.source, "trap")
| fieldsAdd ip=toIp(device.address)
| fieldsAdd network.device=lookup([
    smartscapeNodes EXT_NETWORK_DEVICE
    | fieldsAdd ips=arrayRemoveNulls(arrayConcat(if(isNull(ip), array(null), else: ip), array(toIp(snmp.ip))))
    | expand ips
    | fields id, name, ips
  ], sourceField:ip, lookupField:ips)

Fetch all network devices and count the number of SNMP Traps received within the timeframe.

smartscapeNodes EXT_NETWORK_DEVICE
| fieldsAdd ips=arrayRemoveNulls(arrayConcat(if(isNull(ip), array(null), else: ip), array(toIp(snmp.ip))))
| fields id, name, ips
| expand ips
| fieldsAdd traps=lookup([
    fetch logs
    | filter contains(log.source, "trap")
    | fieldsAdd ip=toIp(device.address)
    | summarize count=count(), by:{ip}
  ], sourceField: ips, lookupField: ip)
| summarize { ips=collectDistinct(ips), traps.count=sum(traps[count])}, by: {id, name}

Query all syslog records and add the associated network device information

fetch logs
| filter dt.openpipeline.source == "extension:syslog"
| fieldsAdd ip=toIp(dt.ingest.source.ip)
| fieldsAdd network.device=lookup([
    smartscapeNodes EXT_NETWORK_DEVICE
    | fieldsAdd ips=arrayRemoveNulls(arrayConcat(if(isNull(ip), array(null), else: ip), array(toIp(snmp.ip))))
    | expand ips
    | fields id, name, ips
  ], sourceField:ip, lookupField:ips)
| dedup timestamp, content, ip, network.device

Base entity fields

The following base fields are used for all entities.

AttributeTypeDescriptionExamples

id

smartscapeId

stable
Display name: ID
A Smartscape ID consists of two components: an UPPER_CASE entity type and a random 16-character hexadecimal unique identifier, separated by a dash. Use Smartscape conversion functions when working with strings that represent Smartscape IDs.

<type>-017198AD253CBD63

id_classic

string

deprecated
Display name: Classic ID
The entity ID that was used in the classic entity store. This ID is present in old monitoring data. Not all entities have this ID, and it is not generated for new entities. Use the id field instead, which is the Smartscape ID.

<type>-017198AD253CBD63

name

string

stable
Display name: Name
The entity name.

localhost; easyTravel; product-catalog

type

string

stable
Display name: Type
The entity type. UPPER_SNAKE_CASE string that represents the type of the entity.

TYPE_A

tags

record

stable
Display name: Tags
A consolidated record that aggregates all tag values originating from different contexts. Each nested field within tags represents a specific key (for example, release or name). The value of each nested field is the tag value from one or multiple contexts. Tags for specific context can be queried via tags:context field. Note that rule-based tags do not exist in the new model.

tags[tag_key-1] = [context_A_tag_val-1, context_B_tag_val-1]; tags[tag_key-2] = context_C_tag_val-1; tags:context_A[tag_key-1] = context_A_tag_val-1

lifetime

timeframe

stable
Display name: Lifetime
The lifetime of the entity. This is a record with two nested fields: start and end, which represent the time when the entity was first and last observed, respectively. Each time an entity is updated, the end time is updated to the current time.

{ start: 2022-07-06T13:36:00.808Z, end: 2024-04-11T06:56:01.204Z }

references

record

stable
Display name: References
Provides access to static edges pointing to other entities. In this record each nested field represents a relationship type and target type, and the value is an array of target smartscape IDs. This field is hidden by default but can be added using the fieldsAdd command.

{ references[runs_on.host] : [HOST-C251A1173C2B4B39,HOST-0E9038C7C4409D69], references[runs_on.container] : [CONTAINER-68A08967EF4F675B] }

dt.security_context

string[]

resource stable
Display name: DT security context
The security contexts associated with the entity. For Smartscape entities, this field is always an array.
Tags: permission

[]

External network entity fields

Fields common to all entities within the shared network model

AttributeTypeDescriptionExamples

description

string

stable
Display name: Description
A description of the network entity.

Cisco IOS Software, C2960X Software (C2960X-UNIVERSALK9-M); GigabitEthernet0/1; Vlan10

ip

ipAddress[]

experimental
A collection of IP addresses that can be used to identify this entity.

['192.168.0.1', '10.10.10.10']; ['10.10.10.10']; ['2001:0000:130F:0000:0000:09C0:876A:130B']

mac

string[]

experimental
A collection of MAC addresses that can be used to identify this entity.

['4C:03:4F:5B:E8:89']

External network device fields

Fields that describe all network devices

AttributeTypeDescriptionExamples

lldp.chassis_id

string

stable
Display name: LLDP chassis ID
The LLDP Chassis ID of this network device

00:1A:2B:3C:4D:5E; device.example.com; XTU123P4

cdp.device_id

string

stable
Display name: CDP device ID
The CDP Device ID of this network device

00:1A:2B:3C:4D:5E; device.example.com; XTU123P4

monitoring_mode

string

stable
Display name: Monitoring mode
The type of monitoring data available for this network device. Extension indicates monitoring data is available, Discovery indicates only topology data is available and this is a candidate for monitoring, and Neighbor indicates limited information is available (this is a link layer neighbor reference)

Discovery; Extension; Neighbor

device_type

string

stable
Display name: Device type
A string to represent the broader make, model, or family of network device.

f5-big-ip; dell-powerconnect; cisco-nexus; infoblox-ipam

chassis_mac

string

experimental
Display name: Chassis MAC
The MAC address of the device chassis; defined as the first non-empty MAC address of the device.

00:1A:2B:3C:4D:5E

contact

string

stable
Display name: Contact
Identification of the contact person for this device, together with information on how to contact them. If no contact information is known, use n/a instead.

John Doe, Network Administrator; john.doe@example.com; n/a

location

string

stable
Display name: Location
The physical location of this device. If the location is unknown, use n/a instead.

Some data center, Rack 123ABC; Some network cabinet, Floor 123; n/a

capabilities

string[]

experimental
Display name: Capabilities
The set of capabilities supported by this network device as advertised in link layer discovery.

['bridge', 'wlanAccessPoint']; ['router', 'telephone']

firmware_revision

string

experimental
Display name: Firmware revision
A version or revision identifer for the firmware in use on the network device.

1000234

hardware_revision

string

experimental
Display name: Hardware revision
A version or revision identifer for the hardware in use on the network device.

45.1C

software_revision

string

experimental
Display name: Software revision
A version or revision identifer for the software on the network device.

1.63.1

part_number

string

experimental
Display name: Part number
Identifer of the chassis part number of the network device.

EUKY55658

serial_number

string

experimental
Display name: Serial number
A serial number for the network device.

FTX123456789

vendor

string

experimental
Display name: Vendor
Name of the vendor for the network device.

Cisco; Juniper

os.name

string

resource stable
Display name: OS name
The OS name in a short, human-readable format.

iOS

External network SNMP device fields

Fields specific to network devices discovered via SNMP

AttributeTypeDescriptionExamples

snmp.sys_object_id

string

resource stable
Display name: SNMP system object ID
OID 1.3.6.1.2.1.1.2 (SNMPv2-MIB::sysObjectId): The vendor's authoritative identification of the network management subsystem contained in the entity.

1.3.6.1.4.1.25461.2.3.38; 1.3.6.1.4.1.9.1.1046

snmp.ip

string

resource stable
An IP address that is enabled for SNMP queries on the device.

10.0.0.1

External network autodiscovered device fields

Fields specific to network devices created by the SNMP Autodiscovery extension

AttributeTypeDescriptionExamples

autodiscovery.config_label

string

stable
Display name: Autodiscovery config label
The label assigned to the Autodiscovery configuration that includes this device

Data Center ABC; On prem

autodiscovery.group_label

string

stable
Display name: Autodiscovery group label
The label assigned to the Autodiscovery group that includes this device

Core Routers; Edge Switches; Subnet 3A

autodiscovery.default_extension

string

stable
Display name: Autodiscovery default extension
Indicates the default Dynatrace Extension recommended for insights into this device type

com.dynatrace.extension.f5.bigip; com.dynatrace.extension.snmp-generic-cisco-device

Network Device relationships

TypeTarget typeKindDescription

calls

EXT_NETWORK_DEVICE

static

stable
Defines a "horizontal" relationship between two entities that "call" each other. The "calls" relation does not imply a parent/child or other strong structural relation but rather a dynamic communication association. Examples: Typical examples include services calling other services, but also services calling databases, queue brokers, or other infrastructure entities.

Network Interface

Smartscape node type: EXT_NETWORK_INTERFACE

A Network Interface entity. Represents a physical or virtual network interface or port on a network device.

Query

Fetch all network interface entities.

smartscapeNodes EXT_NETWORK_INTERFACE

Fetch traffic in and out timeseries for all network interfaces.

timeseries {
  traffic.in=avg(com.dynatrace.extension.network_device.if.bytes_in.count, scalar: true),
  traffic.out=avg(com.dynatrace.extension.network_device.if.bytes_out.count, scalar: true)
},
filter: { isNotNull(dt.smartscape.ext_network_interface) },
by: { dt.smartscape.ext_network_interface }

Fetch all interfaces that are link neighbors with each other, along with the devices they belong to.

smartscapeEdges calls
| filter source_type == "EXT_NETWORK_INTERFACE"
| fields
  neighbor.device=getNodeName(getNodeField(source_id, "references")[belongs_to.ext_network_device][0]),
  neighbor.interface=getNodeName(source_id),
  relation=concat("--- ", type, " --->"),
  base.interface=getNodeName(target_id),
  base.device=getNodeName(getNodeField(target_id, "references")[belongs_to.ext_network_device][0])

Base entity fields

The following base fields are used for all entities.

AttributeTypeDescriptionExamples

id

smartscapeId

stable
Display name: ID
A Smartscape ID consists of two components: an UPPER_CASE entity type and a random 16-character hexadecimal unique identifier, separated by a dash. Use Smartscape conversion functions when working with strings that represent Smartscape IDs.

<type>-017198AD253CBD63

id_classic

string

deprecated
Display name: Classic ID
The entity ID that was used in the classic entity store. This ID is present in old monitoring data. Not all entities have this ID, and it is not generated for new entities. Use the id field instead, which is the Smartscape ID.

<type>-017198AD253CBD63

name

string

stable
Display name: Name
The entity name.

localhost; easyTravel; product-catalog

type

string

stable
Display name: Type
The entity type. UPPER_SNAKE_CASE string that represents the type of the entity.

TYPE_A

tags

record

stable
Display name: Tags
A consolidated record that aggregates all tag values originating from different contexts. Each nested field within tags represents a specific key (for example, release or name). The value of each nested field is the tag value from one or multiple contexts. Tags for specific context can be queried via tags:context field. Note that rule-based tags do not exist in the new model.

tags[tag_key-1] = [context_A_tag_val-1, context_B_tag_val-1]; tags[tag_key-2] = context_C_tag_val-1; tags:context_A[tag_key-1] = context_A_tag_val-1

lifetime

timeframe

stable
Display name: Lifetime
The lifetime of the entity. This is a record with two nested fields: start and end, which represent the time when the entity was first and last observed, respectively. Each time an entity is updated, the end time is updated to the current time.

{ start: 2022-07-06T13:36:00.808Z, end: 2024-04-11T06:56:01.204Z }

references

record

stable
Display name: References
Provides access to static edges pointing to other entities. In this record each nested field represents a relationship type and target type, and the value is an array of target smartscape IDs. This field is hidden by default but can be added using the fieldsAdd command.

{ references[runs_on.host] : [HOST-C251A1173C2B4B39,HOST-0E9038C7C4409D69], references[runs_on.container] : [CONTAINER-68A08967EF4F675B] }

dt.security_context

string[]

resource stable
Display name: DT security context
The security contexts associated with the entity. For Smartscape entities, this field is always an array.
Tags: permission

[]

External network entity fields

Fields common to all entities within the shared network model

AttributeTypeDescriptionExamples

description

string

stable
Display name: Description
A description of the network entity.

Cisco IOS Software, C2960X Software (C2960X-UNIVERSALK9-M); GigabitEthernet0/1; Vlan10

ip

ipAddress[]

experimental
A collection of IP addresses that can be used to identify this entity.

['192.168.0.1', '10.10.10.10']; ['10.10.10.10']; ['2001:0000:130F:0000:0000:09C0:876A:130B']

mac

string[]

experimental
A collection of MAC addresses that can be used to identify this entity.

['4C:03:4F:5B:E8:89']

External network interface fields

Fields representing all network interfaces when running on network devices

AttributeTypeDescriptionExamples

device.chassis_mac

string

experimental
Display name: Device chassis MAC
The MAC address of the device chassis; defined as the first non-empty MAC address of the device hosting the interface.

00:1A:2B:3C:4D:5E

interface_type

string

experimental
Display name: Interface type
The type of network interface. If possible, should use the standard types defined by IANA.

ethernetCsmacd; propVirtual; l2vlan; tunnel

alias

string

stable
Display name: Alias
An alternative name for the interface; relates to the ifAlias SNMP field.

lan; Configured from Cisco DNA-Center; Fabric Physical Link

operational_status

string

stable
Display name: Operational status
The operational status of the interface

up; down; testing

admin_status

string

stable
Display name: Admin status
The admin status of the interface

up; down; testing

speed

string

experimental
Display name: Speed
The speed of the interface in bits per second

1000000000; 10000000000

Network Interface relationships fields

TypeTarget typeKindDescription

belongs_to

EXT_NETWORK_DEVICE

static

stable
This is similar to an aggregation in UML. It is a many-to-many relationship without existential properties (the destination is not composed of the sources).

calls

EXT_NETWORK_INTERFACE

static

stable
Defines a "horizontal" relationship between two entities that "call" each other. The "calls" relation does not imply a parent/child or other strong structural relation but rather a dynamic communication association. Examples: Typical examples include services calling other services, but also services calling databases, queue brokers, or other infrastructure entities.