Try it free

Smartscape events

  • Latest Dynatrace
  • Reference

The Smartscape events model defines the public ingest format for creating and updating Smartscape topology entities in Grail. It provides a unified, documented protocol for configuring smartscape.event pipelines so that all events share a consistent structure.

Query

Query all custom Smartscape entities created via smartscape.events ingest.

smartscapeNodes "CUSTOM_*"
| fields id, name, type, lifetime

Count all custom Smartscape entities by their entity type.

smartscapeNodes "CUSTOM_*"
| summarize count(), by: type

Query all edges originating from custom service entities ingested via smartscape.events.

smartscapeEdges "*"
| filter source_type == "CUSTOM_SERVICE"
| fields source_id, type, target_id, target_type

Smartscape events

The Smartscape events model is the public ingest format for creating and updating Smartscape topology entities in Grail. Each event uses exactly one of two identity modes and may carry field updates, tag updates, and relationship declarations. For a full overview, see Smartscape on Grail.

Identity Modes (mutually exclusive per event):

  • Mode 1—Assembled ID: the caller supplies a pre-assembled Dynatrace entity ID via the id field.
  • Mode 2—Key-based ID: the caller supplies type and id_components; the pipeline derives the entity ID from them.

Mixing both modes in a single event is a contract violation.

Query

Query all custom Smartscape entities created via smartscape.events ingest.

smartscapeNodes "CUSTOM_*"
| fields id, name, type, lifetime

Count all custom Smartscape entities by their entity type.

smartscapeNodes "CUSTOM_*"
| summarize count(), by: type

Query all edges originating from custom service entities ingested via smartscape.events.

smartscapeEdges "*"
| filter source_type == "CUSTOM_SERVICE"
| fields source_id, type, target_id, target_type

Identity fields

Exactly one identity mode must be used per event. id (Mode 1) and the pair type + id_components (Mode 2) are mutually exclusive.

AttributeTypeDescriptionExamples
idsmartscapeIdexperimental
Mode 1 (Assembled ID): the pre-assembled Dynatrace entity ID of the entity to create or update. JSON key: id. When present, type and id_components must be absent.		HOST-00AB12CD; CUSTOM_SERVICE-ABC123
id_componentsrecord[]experimental
Mode 2 (Key-based ID): an ordered array of single-key objects whose values are combined to derive the entity ID hash. JSON key: id_components. Each element must contain exactly one key-value pair—more than one key per element is a contract violation. Order is significant: [{"k1": "v1"}, {"k2": "v2"}] and [{"k2": "v2"}, {"k1": "v1"}] produce different entity IDs. Forward declarations (referencing not-yet-existing entities) are supported. When present, id must be absent and type is required.		[{"hostname": "myhost.example.com"}]; [{"aws.account.id": "123456789012"}, {"aws.resource.id": "i-0abc1234567890def"}]; [{"name": "checkout-service"}, {"service.namespace": "payments"}]
typestringexperimental
Mode 2 (Key-based ID): the entity type used together with id_components to derive the entity ID. JSON key: type. Must match [A-Z][A-Z0-9_]*, max 250 characters. The value CUSTOM_DEVICE is forbidden. Other than following the preceding rules, this is free-form; it's not validated against a known entity type set. When present, id must be absent and id_components is required.		HOST; CUSTOM_SERVICE; K8S_CLUSTER; AWS_EC2_INSTANCE

Protocol metadata fields

Fixed top-level fields that control event routing, security, and lifetime behavior.

AttributeTypeDescriptionExamples
dt.security_contextstring[]resource stable
Display name: DT security context
Security context(s) associated with the entity. Controls access visibility for the resulting entity. Accepts a single string, an array of strings (max 10 elements), or null to clear the security context.
Tags: permission		['pci-scope', 'prod-infra']; ['prod-infra']
event.versionlongexperimental
Protocol version of the smartscape.events format. JSON key: event.version. Currently 1.		1
update_lifetimeanyexperimental
Controls whether this event advances the entity's last-seen timestamp (end of lifetime). JSON key: update_lifetime. true or absent (default): applies field updates and extends the entity's lifetime end to the event timestamp. false: applies field and tag updates without touching the last-seen timestamp. Use for housekeeping updates that should not keep an entity alive. string: ISO 8601 duration string (for example "PT2H30M") — defines how long the entity should stay alive, setting the lifetime end to the event timestamp plus the given duration. Must be between 1 and 24 hours; other values are rejected.		true; false; PT2H30M

Entity fields

Any top-level key that is not a reserved protocol field and does not have the tags: prefix is treated as an entity field update. Field values may be a scalar (string, number, or boolean), null to clear the field, or a flat string:string object (all keys and values must be strings; numbers, booleans, arrays, and nested objects inside an embedded object are rejected).

AttributeTypeDescriptionExamples
primary_tagsrecordexperimental
Primary tag dimensions exposed at the top level of the entity. JSON key: primary_tags.<dimension> (for example, primary_tags.region). Maximum of 20 primary_tags.* fields per event.		{"region": "useast", "env": "production"}

Tag fields

AttributeTypeDescriptionExamples
tagsrecordexperimental
Flattened tag updates. JSON key: tags:<source>. In the event payload, each tag source is written as a top-level key with a tags: prefix (for example, "tags:custom.infra": {"tier": "core"}). After ingest, tags are queryable via tags:source in DQL.		{"tags:custom.infra": {"tier": "core"}, "tags:ext.source": {"env": "production"}}

Relationship fields

AttributeTypeDescriptionExamples
dynamic_edgesrecordexperimental
Map of edge type to array of target entity references for dynamic (short-lived) relationships. JSON key: dynamic_edges. Dynamic edges are subject to lifetime decay—they expire when the source or target entity's lifetime ends. An empty array for a given edge type is ignored (no deletion). Value is an array of target identity objects (Mode 1 id or Mode 2 type + id_components).		{"runs_on": [{"id": "PROCESS_GROUP_INSTANCE-0000000000000001"}]}
static_edgesrecordexperimental
Map of edge type to array of target entity references for static (long-lived) relationships. JSON key: static_edges. Static edges persist until explicitly removed or the source entity is deleted. Max 32 static edge types per event. An empty array for a given edge type deletes all edges of that type from the entity. Value is an array of target identity objects (Mode 1 id or Mode 2 type + id_components).		{"belongs_to": [{"type": "HOST_GROUP", "id_components": [{"group": "grp-1"}]}]}

Protocol format

The payload is a JSON array of event objects. Each event must use exactly one identity mode.

[
  {
    "event.version": 1,
    "type": "HOST",
    "id_components": [{ "hostname": "myhost.example.com" }],
    "dt.security_context": "my-security-context",
    "update_lifetime": true,
    "name": "my-host",
    "ext.custom.region": "eu-west-1",
    "ext.entity.annotations": {
      "backstage.io/owner": "team-foo",
      "backstage.io/managed-by-location": "url:https://bitbucket.lab.dynatrace.org/..."
    },
    "primary_tags.env": "production",
    "tags:custom.infra": { "tier": "core" },
    "tags:ext.source": { "env": "production" },
    "static_edges": {
      "belongs_to": [
        { "type": "HOST_GROUP", "id_components": [{ "group": "grp-1" }] }
      ]
    },
    "dynamic_edges": {
      "runs_on": [
        { "id": "PROCESS_GROUP_INSTANCE-0000000000000001" }
      ]
    }
  }
]

Mode 1—Assembled ID

Use when the Dynatrace entity ID is already known. Only id is required; type and id_components must be absent.

[
  {
    "id": "HOST-00AB12CD",
    "name": "prod-host-01",
    "tags:custom": { "team": "platform-engineering" }
  }
]

Mode 2—Key-based ID

Use when declaring a new entity or syncing from an external system. type and id_components are required; id must be absent.

[
  {
    "type": "CUSTOM_SERVICE",
    "id_components": [{ "name": "checkout-service" }, { "service.namespace": "payments" }],
    "dt.security_context": ["pci-scope", "prod-infra"],
    "service.version": "3.1.2",
    "static_edges": {
      "calls": [
        { "type": "CUSTOM_DATABASE", "id_components": [{ "name": "orders-db-primary" }] }
      ]
    }
  }
]

Restrictions

RestrictionDetail
Identity mode is exclusiveEach event must use exactly one identity mode. id (Mode 1) and type + id_components (Mode 2) are mutually exclusive. Providing both is a contract violation.
id_components element cardinalityEach object in the id_components array must contain exactly one key-value pair. More than one key per element is a contract violation.
id_components order is significant[{"k1": "v1"}, {"k2": "v2"}] and [{"k2": "v2"}, {"k1": "v1"}] produce different entity IDs.
type formatMust match [A-Z][A-Z0-9_]*, max 250 characters. The value CUSTOM_DEVICE is forbidden.
Forward declarationsid_components may reference entities that do not yet exist. The pipeline creates them on first use.
null clears a fieldSetting any entity field to null explicitly removes that field from the entity.
Entity field value typesField values may be a scalar (string, number, or boolean), null, or a flat string:string object where all keys and values are strings. Numbers, booleans, arrays, and nested objects inside an embedded object are rejected with FLAWED_INVALID_FIELD_VALUE_SHAPE.
update_lifetime defaultAbsent is equivalent to true. Set to false to apply updates without advancing the entity's last-seen timestamp.
primary_tags.* limitMaximum 20 primary_tags.* fields per event.
Reserved top-level keysid, type, id_components, event.version, dt.security_context, update_lifetime, static_edges, dynamic_edges are reserved. All other top-level keys (not starting with tags:) are treated as entity field updates.
Field-name rulesEntity field names (including primary_tags.*) must not start with . _ : (space) / \; must not be any of tags, name, dt.security_context, references, lifetime; must not start with dt.system.; max 256 bytes (UTF-8).
tags: prefixTag updates must use the tags:<context> top-level key format. The value must be a JSON object of tag key → string or string array.
Tag context nameMax 32 bytes (UTF-8).
Tag key length1 – 256 bytes (UTF-8).
Tag value lengthString: max 1 024 bytes (UTF-8). String array: each element max 1 024 bytes.
Edge type name formatMust match [a-z][a-z0-9_]*, max 32 bytes (ASCII only).
Max static edge typesMax 32 static edge types per event.
Edge target identityEdge targets inside static_edges and dynamic_edges use the same identity modes: id only (Mode 1) or type + id_components (Mode 2).
Empty static_edges arrayAn empty array for a given edge type deletes all edges of that type from the entity.
Empty dynamic_edges arrayAn empty array for a given edge type is ignored (no deletion).
dt.security_contextAccepts a string, a string array (max 10 elements), or null to clear the security context.

Validation & limits

All limits are enforced before any upsert call — a violation produces a FLAWED result and prevents partial writes.

PropertyLimit
Max total payload size200 KB
Max nesting depth (object / array)5
Max node type name length250 characters
Max field name size256 bytes (UTF-8)
Max field size (key + value)128 KB
Max total field count per event128 (includes tags and name / dt.security_context)
Max static edge types per event32
Max edge type name size32 bytes (ASCII)
Max edge targets section size (per type)32 KB
Max tag context name32 bytes (UTF-8)
Max tag key length256 bytes (UTF-8)
Max tag value length1 024 bytes (UTF-8)
Max dt.security_context elements10

Field protection & trust levels

These rules apply only to arbitrary node fields and tag contexts (all top-level keys not listed in the reserved key set). They do not restrict structural keys (id, type, id_components, name, dt.security_context, edges).

Writability depends on the source trust level and node type:

  1. A trusted source may write any field or tag context.
  2. An untrusted source targeting an extended node type (EXT_* or CUSTOM_*) may also write any field or tag context.
  3. An untrusted source targeting a core node type is limited to:
    • Fields: process.metadata[COMMAND_LINE_ARGS], ext.*, custom.*
    • Tag contexts: tags:ext.*, tags:custom.*