Topology: Entities & Relationships

Why Topology?

Without topology, your extension produces raw metrics floating in space. With topology, Dynatrace creates entities — navigable objects with properties, relationships, and dedicated screens.

Without topology:                    With topology:
  metric: cpu_usage = 45%              Entity: SWITCH-01 (Cisco Catalyst)
  metric: if.speed = 1000                ├── CPU: 45%
  metric: temperature = 32               ├── Interface: Gi0/1 (1 Gbps)
  (just numbers, no context)             ├── Interface: Gi0/2 (1 Gbps)
                                         ├── PSU: Power Supply 1 (OK)
                                         └── Sensor: Temp Sensor 1 (32°C)

Entity Types

Define entity types in the topology: section:

topology:
  types:
    # Parent entity — the device itself
    - name: my_device:device
      displayName: My Network Device
      enabled: true
      rules:
        - idPattern: my_device_{device.address}
          instanceNamePattern: "{sys.name} ({device.address})"
          iconPattern: cisco
          sources:
            - sourceType: Metrics
              condition: $prefix(com.dynatrace.extension.my_device)
          requiredDimensions:
            - key: device.address
          attributes:
            - key: dt.ip_addresses
              pattern: "{device.address}"
            - key: dt.listen_ports
              pattern: "{device.port}"
            - key: devDescription
              displayName: Description
              pattern: "{sys.description}"
          role: default

Key fields:

• name — Entity type ID. Format: {prefix}:{type}. Must be unique.
• idPattern — Globally unique entity ID. Include {device.address} to ensure uniqueness.
• instanceNamePattern — Display name shown in Dynatrace UI.
• iconPattern — Icon from Dynatrace icon set (cisco, server, switch, etc.).
• sources — Links metrics to this entity type. $prefix() matches all metrics starting with that prefix.
• requiredDimensions — Dimensions that MUST exist for entity creation.
• attributes — Entity properties shown in the UI. dt.ip_addresses and dt.listen_ports are special (enable IP lookup).
• role: default — Only on the parent entity.

Child Entity Types

Interfaces, power supplies, sensors — anything that belongs to a device:

    # Child entity — interface
    - name: my_device:interface
      displayName: Network Interface
      enabled: true
      rules:
        - idPattern: my_device_if_{device.address}_{if.name}
          instanceNamePattern: "{if.name}"
          iconPattern: nic
          sources:
            - sourceType: Metrics
              condition: $prefix(com.dynatrace.extension.my_device.if)
          requiredDimensions:
            - key: device.address
            - key: if.name
          attributes:
            - key: interfaceAlias
              displayName: Alias
              pattern: "{if.alias}"

    # Child entity — power supply
    - name: my_device:power_supply
      displayName: Power Supply
      enabled: true
      rules:
        - idPattern: my_device_psu_{device.address}_{psu.descr}
          instanceNamePattern: "{psu.descr}"
          iconPattern: power-supply
          sources:
            - sourceType: Metrics
              condition: $prefix(com.dynatrace.extension.my_device.psu)
          requiredDimensions:
            - key: device.address
            - key: psu.descr

    # Child entity — temperature sensor
    - name: my_device:sensor
      displayName: Temperature Sensor
      enabled: true
      rules:
        - idPattern: my_device_sensor_{device.address}_{sensor.descr}
          instanceNamePattern: "{sensor.descr}"
          iconPattern: thermometer
          sources:
            - sourceType: Metrics
              condition: $prefix(com.dynatrace.extension.my_device.sensor)
          requiredDimensions:
            - key: device.address
            - key: sensor.descr

Critical rules for child entities:

• idPattern must include BOTH the parent identifier ({device.address}) AND the child identifier ({if.name})
• $prefix() condition must match only the child's metrics, not the parent's
• No role: default on children

Relationships

Connect children to parents with CHILD_OF:

  relationships:
    - fromType: my_device:interface
      toType: my_device:device
      typeOfRelation: CHILD_OF
      enabled: true
      sources:
        - sourceType: Metrics
          condition: $prefix(com.dynatrace.extension.my_device.if)

    - fromType: my_device:power_supply
      toType: my_device:device
      typeOfRelation: CHILD_OF
      enabled: true
      sources:
        - sourceType: Metrics
          condition: $prefix(com.dynatrace.extension.my_device.psu)

    - fromType: my_device:sensor
      toType: my_device:device
      typeOfRelation: CHILD_OF
      enabled: true
      sources:
        - sourceType: Metrics
          condition: $prefix(com.dynatrace.extension.my_device.sensor)

The topology engine matches incoming metrics against $prefix() conditions. When metrics arrive with the required dimensions, entities are automatically created and linked.

How Entity Creation Works

1. Extension uploaded → Dynatrace reads topology: section
2. Entity types auto-registered in Settings API
3. Relationships auto-registered
4. Metrics arrive with dimensions (device.address, if.name, etc.)
5. Topology engine matches metrics against $prefix() conditions
6. Entity instances created when required dimensions present
7. Relationships linked based on shared dimensions

You can verify entity creation via API:

curl "$BASE/api/v2/entities?entitySelector=type(my_device:device)&fields=+properties" \
  -H "Authorization: Api-Token $TOKEN"

Common Topology Mistakes

Mistake                                          Fix
───────────────────────────────────────────────  ──────────────────────────────
idPattern not globally unique                    Include device.address + child ID
$prefix() too broad (matches parent metrics)     Use specific prefix per child type
Missing requiredDimensions                       Add all dimensions used in idPattern
Forgot role: default on parent                   Add role: default to parent entity
Child idPattern missing parent identifier        Include {device.address} in child ID

What's Next

In Module 6, we'll build screens and dashboards — the UI that displays your entity data with charts, lists, and detail views.