Add telemetry during topology synchronization

StackState Self-hosted v5.1.x

Overview

Topology imported to StackState using a StackPack or other integration is described as synchronized topology. Synchronized topology data arriving in StackState from external systems is normalized using a template. The template defines how a topology element should be built in StackState, such as the layer it should belong to, the health checks that should be added and any telemetry streams that should be attached to it.

The StackPacks shipped with StackState already include templates with the relevant telemetry streams for each imported element type. If you create your own integrations or have additional telemetry streams that you would like to link with imported components, you can edit the template used during synchronization to automatically add these to imported topology.

Add telemetry streams to the synchronization template

If you want to add a telemetry stream to all topology elements imported by a specific integration, you can edit its template function to include the additional telemetry stream.

Edit a template function with the template editor

The StackState template editor allows you to customize how StackState builds topology elements from imported topology data. You can open the template editor from the StackState UI right panel details tab when detailed information is displayed about an element - Component details or Direct relation details depending on the element type that you selected.

Note that you are editing the template for the synchronization that imported the element, not the template for this specific element. Changes saved here will be applied to all future synchronizations for all elements built using this template.

Select an element to open detailed information about it in the right panel details tab - Component details or Direct relation details depending on the element type that you selected.
Click ... and select Edit template.
The template editor will open for the template that was used to create the selected element. Three sets of information are displayed:
- input parameters - the raw data imported for a specific element.
- template function - the template function used by the synchronization that imported the element. When an element is imported, the synchronization will run the template function with input parameters. This outputs a structured JSON string, which is used to build the component properties that you see in the StackState UI right panel details tab - Component details.
- Result - Click PREVIEW to see the output of the template function when it runs with the specified input parameters. You can choose to view the result either in JSON format or as it will appear in the StackState UI component Properties.
You can edit the template function to change how the topology element is built in StackState, for example to add a telemetry stream to every element imported with this template.

Add a telemetry stream to a template function

The telemetry streams attached to topology elements during synchronization are configured in the template function as streams: []. To add a telemetry stream to a component the fields described below are required. The most important part of the stream configuration is the query, this represents the conditions used to filter the stream:

Field Allowed values Description

Field	Allowed values	Description
`_type`	MetricStream EventStream	The type of Data Stream.
`name`		A name for the Data Stream. For metric streams, you can also specify a unit type here.
`query._type`	MetricTelemetryQuery EventTelemetryQuery	The type of the Query
`query.conditions`		A collection of `"key", "value"` attributes used to filter the stream. The keys are defined by the data source and the value can be any string, numeric or boolean.
`query.metricField`		Metric streams only. The metric to observe in the stream.
`query.aggregation`	MEAN PERCENTILE_25 PERCENTILE_50 PERCENTILE_75 PERCENTILE_90 PERCENTILE_95 PERCENTILE_98 PERCENTILE_99 MAX MIN SUM SUM_NO_ZEROS EVENT_COUNT_NO_ZEROS	Metric streams only. The function to apply to aggregate the data.
`datasource`		The data source where to connect to fetch the data.
`datatype`	METRICS EVENTS	The kind of data received on the stream.

_type

MetricStream EventStream

The type of Data Stream.

name

A name for the Data Stream. For metric streams, you can also specify a unit type here.

query._type

MetricTelemetryQuery EventTelemetryQuery

The type of the Query

query.conditions

A collection of "key", "value" attributes used to filter the stream. The keys are defined by the data source and the value can be any string, numeric or boolean.

query.metricField

Metric streams only. The metric to observe in the stream.

query.aggregation

MEAN PERCENTILE_25 PERCENTILE_50 PERCENTILE_75 PERCENTILE_90 PERCENTILE_95 PERCENTILE_98 PERCENTILE_99 MAX MIN SUM SUM_NO_ZEROS EVENT_COUNT_NO_ZEROS

Metric streams only. The function to apply to aggregate the data.

datasource

The data source where to connect to fetch the data.

datatype

METRICS EVENTS

The kind of data received on the stream.

For example, a CloudWatch metric stream:

{
    ...
    "streams": [
    {
      "_type": "MetricStream",
      "name": "Invocation Duration",
      "query": {
        "conditions": [
            {"key": "Namespace","value": "AWS/Lambda"},
            {"key": "Resource","value": "{{ element.data.FunctionName }}"},
            {"key": "Region","value": "{{ element.data.Location.AwsRegion }}"}
        ],
        "_type": "MetricTelemetryQuery",
        "metricField": "Duration",
        "id": -27,
        "aggregation": "MEAN"
      },
      "dataSource": {{ resolve "DataSource" "CloudWatchSource" }},
      "id": -13,
      "dataType": "METRICS"
    }
    ]
}

Overview

Add telemetry streams to the synchronization template

Edit a template function with the template editor

Add a telemetry stream to a template function

See also