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

stableDisplay name: IDA 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

deprecatedDisplay name: Classic IDThe 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

stableDisplay name: NameThe entity name.

localhost; easyTravel; product-catalog

type

string

stableDisplay name: TypeThe entity type. UPPER_SNAKE_CASE string that represents the type of the entity.

TYPE_A

tags

record

stableDisplay name: TagsA 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

stableDisplay name: LifetimeThe 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

stableDisplay name: ReferencesProvides 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 stableDisplay name: DT security contextThe 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

stableDisplay name: DescriptionA description of the network entity.

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

ip

ipAddress[]

experimentalA collection of IP addresses that may 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[]

experimentalA 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

stableDisplay name: LLDP chassis IDThe LLDP Chassis ID of this network device

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

cdp.device_id

string

stableDisplay name: CDP device IDThe CDP Device ID of this network device

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

monitoring_mode

string

stableDisplay name: Monitoring modeThe 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

stableDisplay name: Device typeA string to represent the broader make, model, or family of network device.

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

chassis_mac

string

experimentalDisplay name: Chassis MACThe 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

stableDisplay name: ContactIdentification 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

stableDisplay name: LocationThe 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[]

experimentalDisplay name: CapabilitiesThe set of capabilities supported by this network device as advertised in link layer discovery.

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

firmware_revision

string

experimentalDisplay name: Firmware revisionA version or revision identifer for the firmware in use on the network device.

1000234

hardware_revision

string

experimentalDisplay name: Hardware revisionA version or revision identifer for the hardware in use on the network device.

45.1C

software_revision

string

experimentalDisplay name: Software revisionA version or revision identifer for the software on the network device.

1.63.1

part_number

string

experimentalDisplay name: Part numberIdentifer of the chassis part number of the network device.

EUKY55658

serial_number

string

experimentalDisplay name: Serial numberA serial number for the network device.

FTX123456789

vendor

string

experimentalDisplay name: VendorName of the vendor for the network device.

Cisco; Juniper

os.name

string

resource stableDisplay name: OS nameThe 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 stableDisplay name: SNMP system object IDOID 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 stableAn 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

stableDisplay name: Autodiscovery config labelThe label assigned to the Autodiscovery configuration that includes this device

Data Center ABC; On prem

autodiscovery.group_label

string

stableDisplay name: Autodiscovery group labelThe label assigned to the Autodiscovery group that includes this device

Core Routers; Edge Switches; Subnet 3A

autodiscovery.default_extension

string

stableDisplay name: Autodiscovery default extensionIndicates 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

stableDefines 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

stableDisplay name: IDA 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

deprecatedDisplay name: Classic IDThe 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

stableDisplay name: NameThe entity name.

localhost; easyTravel; product-catalog

type

string

stableDisplay name: TypeThe entity type. UPPER_SNAKE_CASE string that represents the type of the entity.

TYPE_A

tags

record

stableDisplay name: TagsA 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

stableDisplay name: LifetimeThe 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

stableDisplay name: ReferencesProvides 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 stableDisplay name: DT security contextThe 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

stableDisplay name: DescriptionA description of the network entity.

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

ip

ipAddress[]

experimentalA collection of IP addresses that may 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[]

experimentalA 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

experimentalDisplay name: Device chassis MACThe 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

experimentalDisplay name: Interface typeThe type of network interface. If possible, should use the standard types defined by IANA.

ethernetCsmacd; propVirtual; l2vlan; tunnel

alias

string

stableDisplay name: AliasAn alternative name for the interface; relates to the ifAlias SNMP field.

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

operational_status

string

stableDisplay name: Operational statusThe operational status of the interface

up; down; testing

admin_status

string

stableDisplay name: Admin statusThe admin status of the interface

up; down; testing

speed

string

experimentalDisplay name: SpeedThe speed of the interface in bits per second

1000000000; 10000000000

Network Interface relationships fields

TypeTarget typeKindDescription

belongs_to

EXT_NETWORK_DEVICE

static

stableThis 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

stableDefines 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.