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.

Attribute	Type	Description	Examples
`id`	smartscapeId	experimentalMode 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_components`	record[]	experimentalMode 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"}]`
`type`	string	experimentalMode 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.

Attribute	Type	Description	Examples
`dt.security_context`	string[]	resource stableSecurity 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.version`	long	experimentalProtocol version of the smartscape.events format. JSON key: `event.version`. Currently `1`.	`1`
`update_lifetime`	boolean	experimentalControls 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.	`true`; `false`

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

Attribute	Type	Description	Examples
`primary_tags`	record	experimentalPrimary 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

Attribute	Type	Description	Examples
`tags`	record	experimentalFlattened 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

Attribute	Type	Description	Examples
`dynamic_edges`	record	experimentalMap 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_edges`	record	experimentalMap 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

Restriction	Detail
Identity mode is exclusive	Each 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 cardinality	Each 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` format	Must match `[A-Z][A-Z0-9_]`, max 250 characters*. The value `CUSTOM_DEVICE` is forbidden.
Forward declarations	`id_components` may reference entities that do not yet exist. The pipeline creates them on first use.
`null` clears a field	Setting any entity field to `null` explicitly removes that field from the entity.
Entity field value types	Field 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` default	Absent is equivalent to `true`. Set to `false` to apply updates without advancing the entity's last-seen timestamp.
`primary_tags.*` limit	Maximum 20 `primary_tags.*` fields per event.
Reserved top-level keys	`id`, `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 rules	Entity 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:` prefix	Tag 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 name	Max 32 bytes (UTF-8).
Tag key length	1 – 256 bytes (UTF-8).
Tag value length	String: max 1 024 bytes (UTF-8). String array: each element max 1 024 bytes.
Edge type name format	Must match `[a-z][a-z0-9_]`, max 32 bytes* (ASCII only).
Max static edge types	Max 32 static edge types per event.
Edge target identity	Edge 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` array	An empty array for a given edge type deletes all edges of that type from the entity.
Empty `dynamic_edges` array	An empty array for a given edge type is ignored (no deletion).
`dt.security_context`	Accepts 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.

Property	Limit
Max total payload size	200 KB
Max nesting depth (object / array)	5
Max node type name length	250 characters
Max field name size	256 bytes (UTF-8)
Max field size (key + value)	128 KB
Max total field count per event	128 (includes tags and `name` / `dt.security_context`)
Max static edge types per event	32
Max edge type name size	32 bytes (ASCII)
Max edge targets section size (per type)	32 KB
Max tag context name	32 bytes (UTF-8)
Max tag key length	256 bytes (UTF-8)
Max tag value length	1 024 bytes (UTF-8)
Max `dt.security_context` elements	10

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:

A trusted source may write any field or tag context.
An untrusted source targeting an extended node type (EXT_* or CUSTOM_*) may also write any field or tag context.
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.*

Smartscape events

Latest Dynatrace
Reference

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

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.

Attribute	Type	Description	Examples
`id`	smartscapeId	experimentalMode 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_components`	record[]	experimentalMode 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"}]`
`type`	string	experimentalMode 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.

Attribute	Type	Description	Examples
`dt.security_context`	string[]	resource stableSecurity 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.version`	long	experimentalProtocol version of the smartscape.events format. JSON key: `event.version`. Currently `1`.	`1`
`update_lifetime`	boolean	experimentalControls 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.	`true`; `false`

Entity fields

Attribute	Type	Description	Examples
`primary_tags`	record	experimentalPrimary 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

Attribute	Type	Description	Examples
`tags`	record	experimentalFlattened 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

Attribute	Type	Description	Examples
`dynamic_edges`	record	experimentalMap 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_edges`	record	experimentalMap 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

Restriction	Detail
Identity mode is exclusive	Each 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 cardinality	Each 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` format	Must match `[A-Z][A-Z0-9_]`, max 250 characters*. The value `CUSTOM_DEVICE` is forbidden.
Forward declarations	`id_components` may reference entities that do not yet exist. The pipeline creates them on first use.
`null` clears a field	Setting any entity field to `null` explicitly removes that field from the entity.
Entity field value types	Field 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` default	Absent is equivalent to `true`. Set to `false` to apply updates without advancing the entity's last-seen timestamp.
`primary_tags.*` limit	Maximum 20 `primary_tags.*` fields per event.
Reserved top-level keys	`id`, `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 rules	Entity 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:` prefix	Tag 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 name	Max 32 bytes (UTF-8).
Tag key length	1 – 256 bytes (UTF-8).
Tag value length	String: max 1 024 bytes (UTF-8). String array: each element max 1 024 bytes.
Edge type name format	Must match `[a-z][a-z0-9_]`, max 32 bytes* (ASCII only).
Max static edge types	Max 32 static edge types per event.
Edge target identity	Edge 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` array	An empty array for a given edge type deletes all edges of that type from the entity.
Empty `dynamic_edges` array	An empty array for a given edge type is ignored (no deletion).
`dt.security_context`	Accepts 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.

Property	Limit
Max total payload size	200 KB
Max nesting depth (object / array)	5
Max node type name length	250 characters
Max field name size	256 bytes (UTF-8)
Max field size (key + value)	128 KB
Max total field count per event	128 (includes tags and `name` / `dt.security_context`)
Max static edge types per event	32
Max edge type name size	32 bytes (ASCII)
Max edge targets section size (per type)	32 KB
Max tag context name	32 bytes (UTF-8)
Max tag key length	256 bytes (UTF-8)
Max tag value length	1 024 bytes (UTF-8)
Max `dt.security_context` elements	10

Field protection & trust levels

Writability depends on the source trust level and node type:

A trusted source may write any field or tag context.
An untrusted source targeting an extended node type (EXT_* or CUSTOM_*) may also write any field or tag context.
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.*