LogoLogo
StackState.comDownloadSupportExplore playground
StackState v5.1
StackState v5.1
  • Welcome to the StackState docs!
  • StackState self-hosted v5.1 docs
  • Getting Started
  • 🚀Setup
    • Install StackState
      • Requirements
      • Kubernetes / OpenShift
        • Kubernetes install
        • OpenShift install
        • Required Permissions
        • Non-high availability setup
        • Override default configuration
        • Configure storage
        • Configure Ingress
        • Install from custom image registry
        • Migrate from Linux install
      • Linux
        • Before you install
        • Download
        • Install StackState
        • Install with production configuration
        • Install with development configuration
        • Install with POC configuration
        • Set up a reverse proxy
        • Set up TLS without reverse proxy
      • Initial run guide
      • Troubleshooting
    • Upgrade StackState
      • Steps to upgrade
      • Version specific upgrade instructions
      • StackPack versions
      • StackState release notes
    • StackState Agent
      • About StackState Agent V3
      • Docker
      • Kubernetes / OpenShift
      • Linux
      • Windows
      • Advanced Agent configuration
      • Use an HTTP/HTTPS proxy
      • Agent V1 (legacy)
      • Migrate Agent V1 to Agent V2
        • Linux
        • Docker
    • StackState CLI
      • CLI: sts
      • CLI: stac (deprecated)
      • Comparison between CLIs
    • Data management
      • Backup and Restore
        • Kubernetes backup
        • Linux backup
        • Configuration backup
      • Data retention
      • Clear stored data
  • 👤Use
    • Concepts
      • The 4T data model
      • Components
      • Relations
      • Health state
      • Layers, Domains and Environments
      • Perspectives
      • Anomaly detection
      • StackState architecture
    • StackState UI
      • Explore mode
      • Filters
      • Views
        • About views
        • Configure the view health
        • Create and edit views
        • Visualization settings
      • Perspectives
        • Topology Perspective
        • Events Perspective
        • Traces Perspective
        • Metrics Perspective
      • Timeline and time travel
      • Analytics
      • Keyboard shortcuts
    • Checks and monitors
      • Checks
      • Add a health check
      • Anomaly health checks
      • Monitors
      • Manage monitors
    • Problem analysis
      • About problems
      • Problem lifecycle
      • Investigate a problem
      • Problem notifications
    • Metrics
      • Telemetry streams
      • Golden signals
      • Top metrics
      • Add a telemetry stream
      • Browse telemetry
      • Set telemetry stream priority
    • Events
      • About events
      • Event notifications
      • Manage event handlers
    • Glossary
  • 🧩StackPacks
    • About StackPacks
    • Add-ons
      • Autonomous Anomaly Detector
      • Health Forecast
    • Integrations
      • About integrations
      • 💠StackState Agent V2
      • 💠AWS
        • AWS
        • AWS ECS
        • AWS X-ray
        • StackState/Agent IAM role: EC2
        • StackState/Agent IAM role: EKS
        • Policies for AWS
        • AWS (legacy)
        • Migrate AWS (legacy) to AWS
      • 💠Dynatrace
      • 💠Kubernetes
      • 💠OpenShift
      • 💠OpenTelemetry
        • About instrumentations
        • AWS NodeJS Instrumentation
        • Manual Instrumentation
          • Prerequisites
          • Tracer and span mappings
          • Relations between components
          • Span health state
          • Merging components
          • Code examples
      • 💠ServiceNow
      • 💠Slack
      • 💠Splunk
        • Splunk
        • Splunk Events
        • Splunk Health
        • Splunk Metrics
        • Splunk Topology
      • 💠VMWare vSphere
      • Apache Tomcat
      • Azure
      • Cloudera
      • Custom Synchronization
      • DotNet APM
      • Elasticsearch
      • Humio
      • Java APM
      • JMX
      • Logz.io
      • MySQL
      • Nagios
      • OpenMetrics
      • PostgreSQL
      • Prometheus
      • SAP
      • SCOM
      • SolarWinds
      • Static Health
      • Static Topology
      • Traefik
      • WMI
      • Zabbix
    • Develop your own StackPacks
  • 🔧Configure
    • Topology
      • Component actions
      • Identifiers
      • Topology naming guide
      • Topology sources
      • Create a topology manually
      • Configure topology synchronizations
      • Enable email event notifications
      • Send topology data over HTTP
      • Set the topology filtering limit
      • Use a proxy for event handlers
      • Use tags
      • Tune topology synchronization
      • Debug topology synchronization
    • Telemetry
      • Add telemetry during topology synchronization
      • Data sources
        • Elasticsearch
        • Prometheus mirror
      • Send events over HTTP
      • Send metrics data over HTTP
      • Set the default telemetry interval
      • Debug telemetry synchronization
    • Traces
      • Set up traces
      • Advanced configuration for traces
    • Health
      • Health synchronization
      • Send health data over HTTP
        • Send health data
        • Repeat Snapshots JSON
        • Repeat States JSON
        • Transactional Increments JSON
      • Debug health synchronization
    • Anomaly Detection
      • Export anomaly feedback
      • Scale the AAD up and down
      • The AAD status UI
    • Security
      • Authentication
        • Authentication options
        • File based
        • LDAP
        • Open ID Connect (OIDC)
        • KeyCloak
        • Service tokens
      • RBAC
        • Role-based Access Control
        • Permissions
        • Roles
        • Scopes
        • Subjects
      • Secrets management
      • Self-signed certificates
      • Set up a security backend for Linux
      • Set up a security backend for Windows
    • Logging
      • Kubernetes logs
      • Linux logs
      • Enable logging for functions
  • 📖Develop
    • Developer guides
      • Agent checks
        • About Agent checks
        • Agent check API
        • Agent check state
        • How to develop Agent checks
        • Connect an Agent check to StackState
      • Custom functions and scripts
        • StackState functions
        • Check functions
        • Component actions
        • Event handler functions
        • ID extractor functions
        • Mapping functions
        • Monitor functions
        • Propagation functions
        • Template functions
        • View health state configuration functions
      • Custom Synchronization StackPack
        • About the Custom Synchronization StackPack
        • How to customize elements created by the Custom Synchronization StackPack
        • How to configure a custom synchronization
      • Integrate external services
      • Mirroring Telemetry
      • Monitors
        • Create monitors
        • Monitor STJ file format
      • StackPack development
        • How to create a StackPack
        • Packaging
        • How to get a template file
        • How to make a multi-instance StackPack
        • Prepare a multi-instance provisioning script
        • Upload a StackPack file
        • Prepare a shared template
        • Customize a StackPack
        • Prepare instance template files
        • Prepare a StackPack provisioning script
        • Resources in a StackPack
        • StackState Common Layer
      • Synchronizations and templated files
    • Reference
      • StackState OpenAPI docs
      • StackState Template JSON (STJ)
        • Using STJ
        • Template functions
      • StackState Markup Language (STML)
        • Using STML
        • STML Tags
      • StackState Query Language (STQL)
      • StackState Scripting Language (STSL)
        • Scripting in StackState
        • Script result: Async
        • Script result: Streaming
        • Time in scripts
        • Script APIs
          • Async - script API
          • Component - script API
          • HTTP - script API
          • Prediction - script API
          • StackPack - script API
          • Telemetry - script API
          • Time - script API
          • Topology - script API
          • UI - script API
          • View - script API
    • Tutorials
      • Create a simple StackPack
      • Push data to StackState from an external system
      • Send events to StackState from an external system
      • Set up a mirror to pull telemetry data from an external system
Powered by GitBook
LogoLogo

Legal notices

  • Privacy
  • Cookies
  • Responsible disclosure
  • SOC 2/SOC 3
On this page
  • Overview
  • Propagation type
  • Auto propagation (default)
  • Transparent state
  • Propagation functions
  • Custom propagation functions
  • Create a custom propagation function
  • System parameters
  • User parameters
  • Execution
  • Script - properties and methods
  • Script - logging
  • Edit template
  • Specify a propagation function
  • Example templates
  • See also
  1. Develop
  2. Developer guides
  3. Custom functions and scripts

Propagation functions

StackState Self-hosted v5.1.x

PreviousMonitor functionsNextTemplate functions

Last updated 2 years ago

Overview

Propagation defines how a propagated state flows from one component to the next. Propagation always flows from dependencies to dependent components and relations. Note that this is the opposite direction of the relation arrows in the graph.

A propagated state is returned as one of the following health states:

  • CRITICAL

  • FLAPPING

  • DEVIATING

  • UNKNOWN

A component's propagated state is calculated using a propagation function, which is set during synchronization.

Propagation type

Auto propagation (default)

Assigns the transparent state as the propagated state of a component.

Transparent state

The transparent state is pre-calculated by StackState and used for the default propagation type (auto propagation). It's passed to each propagation function script at run time in the transparentState and autoState. The transparent state is calculated as the maximum of a component's own state and the propagated state of all the components that it depends upon. For example:

Dependency state
Component state
Transparent state

CRITICAL

DEVIATING

CRITICAL

CLEAR

CRITICAL

CRITICAL

DEVIATING

CLEAR

DEVIATING

Propagation functions

Custom propagation functions

Create a custom propagation function

A propagation function can take multiple parameters as input and produces a new propagated state as output. To calculate a propagated state, a propagation function has access to the element itself, the element's dependencies and the transparent state that has already been calculated for the element.

The simplest possible function that can be written is given below. This function will always return a DEVIATING propagated state:

    return DEVIATING

You can also use a propagation function to implement more complicated logic. For example, the script below will return a DEVIATING state in case a component isn't running:

Component
  .withId(componentId)
  .fullComponent()
  .then { component ->
    if (component.runState.runState != "RUNNING") {
      return DEVIATING
    } else {    
      return transparentState
    }
  }

This code works as follows:

Code
Description

.withId(componentId)

The componentId is passed as long and resolved

.fullComponent()

then { component -> ... }

An async lambda function where the main logic for the propagation function resides. component is the component variable, which has properties that can be accessed using .<property name>. For example, .type returns component type ID.

System parameters

System parameters are predefined parameters that are passed automatically to the propagation function script at run time.

System parameter
Description

transparentState

autoState

component

The ID of the current component.

User parameters

Execution

Two types of execution are available for propagation functions:

Asynchronous execution

Keep performance aspects in mind when developing functions with asynchronous execution The script APIs offer super-human levels of flexibility and even allow querying standalone services. Consider extreme cases where the function is executed on all components and properly assess system impact. StackState comes with a number of StackPacks that include tuned propagating functions. Changes to those functions are possible, but may impact the stability of the system.

Synchronous execution

Running a propagation function with synchronous execution places limitations on both the capability of what it can achieve, and the number of functions that can be run in parallel. Synchronous propagation functions do, however, have access to stateChangesRepository information that isn't available if the function runs with asynchronous execution.

stateChangesRepository can be used to return:

  • The propagating state of an element

  • The number of elements with a particular propagating state

  • The highest state of a given set of elements

Script - properties and methods

The properties and methods described below are available for use in a propagation function script.

Element properties and methods

  • element.name - Returns the name of the current element.

  • element.type - Returns type of the current element.

  • element.version - Returns the component version (optional).

  • element.runState() - Returns the run state of the current element.

  • element.isComponent() - Returns True if element is a component and False if element is a relation.

  • element.getDependencies().size() - Returns the number of dependencies.

  • element.getDependencies() - Returns a set of the outgoing relations (for components) or a set of components (for relations).

StateChangesRepository methods

The stateChangesRepository methods listed below are only available in synchronous propagation functions.

  • stateChangesRepository.getPropagatedHealthStateCount(<set_of_elements>, <health_state>) Returns the number of elements in the set that have a certain health state, for example CRITICAL.

  • stateChangesRepository.getHighestPropagatedHealthStateFromElements(<set_of_elements>) Returns the highest propagated health state based on the given set of elements.

  • stateChangesRepository.getState(element).getHealthState().intValue Returns the health state of the element.

  • stateChangesRepository.getState(element).getPropagatedHealthState().getIntValue() Returns the propagated health state of the element.

Script - logging

Edit template

Specify a propagation function

To manually specify a non-default propagation function, a "propagation" block should be added to the template used for topology synchronization. If the "propagation" block is omitted, the default Auto propagation will be used.

"propagation": {
  "_type": "Propagation",
  "function": <id-of-the-function-to-use>,
  "arguments": []
  },

The propagation block requires the following keys:

  • _type - specifies that the JSON block defines a Propagation.

  • function the node ID of the propagation function to use. This can be obtained using a get helper.

    • parameter - the node ID of the propagation function’s user parameter. This can be obtained using a get helper.

    • Any values required for the specified argument _type.

Example templates

Examples of adding a propagation function to a template can be found below:

Active/active failover propagation function

The example template below uses a get helper to obtain the ID of the Active/active failover propagation function with the identifier urn:stackpack:common:propagation-function:active-failover. No "arguments" are specified as the propagation function doesn't include any user parameters. Arguments for system parameters are automatically provided during run time and don't need to be specified.

...
"propagation": {
  "_type": "Propagation",
  "function": {{ get "urn:stackpack:common:propagation-function:active-failover" }},
  "arguments": [],
  },
...

Stop propagation for relation type

The template example below includes an argument that will be passed to the propagation function as a user parameter together with the standard system parameters. The "arguments" list has one argument that matches the user parameter relationType from the Stop propagation for relation type propagation function. Arguments for system parameters are automatically provided during run time and don't need to be specified.

...
"propagation": {
  "_type": "Propagation",
  "function": {{ get "urn:stackpack:common:propagation-function:stop-propagation-for-relation-type" }},
  "arguments": [{
    "_type": "ArgumentRelationTypeRef",
    "parameter": {{ get "urn:stackpack:common:propagation-function:stop-propagation-for-relation-type" "Type=Parameter;Name=relationType" }},
    "relationType": {{ get "urn:stackpack:common:relationtype:is-hosted-on" }}
    }],
  },
...

See also

Propagation functions can be defined and used to calculate the propagated state of a component. Some propagation functions are installed as part of a StackPack. For example, Quorum based cluster propagation, which will propagate a DEVIATING state when the cluster quorum agrees on deviating and a CRITICAL state when the cluster quorum is in danger. You can also write your own . A full list of the propagation functions available in your StackState instance can be found in the StackState UI, go to Settings > Functions > Propagation Functions

To specify a propagation function that should be used to calculate the propagated state a component, add the to the template used in topology synchronization.

You can write custom propagation functions to determine the new propagated state of an element (component or relation). The propagation function can then be used to synchronize topology.

Returns a JSON-style representation of the component. This is the same format as is obtained from the Show Json properties menu for a component, or by using a in analytics.

The precomputed .

The precomputed . This is the same as transparentState.

User parameters can optionally be defined and used in the propagation function script. The value must be provided as an argument when the function is .

(recommended)

Functions that run with asynchronous execution can make an HTTP request and use in the function body. This gives you access to parts of the topology/telemetry not available in the context of the propagation itself. You can also use the available .

See available .

- functions with either asynchronous or synchronous execution

- functions with synchronous execution only

The element properties and methods listed below can be used in propagation functions with either asynchronous or synchronous execution. Functions with synchronous execution also have access to .

You can add logging statements to a propagation function script for debug purposes, for example, with log.info("message"). Logs will appear in stackstate.log. Read how to .

The default propagation used in StackState is . If another type of propagation should be applied to a component, this must be specified in the template and applied during topology synchronization. In most cases this will be handled by the StackPack responsible for synchronization of the component.

arguments - a list of arguments to match any user parameters that the propagation function requires. Arguments for system parameters are automatically provided during run time and don't need to be specified here. For further details, see the of adding a propagation function to a template.

_type - the type of the argument. This must match the type specified for the user parameter in the .

Function with system parameters only:

Function with system and user parameters:

📖
enable logging for functions
StackState script APIs
Enable logging for functions
system parameters
custom propagation functions
propagation block
specified in the template
configured in the template
Asynchronous execution
Synchronous execution
StackState script APIs
element properties and methods
properties and methods
Element properties and methods
stateChangesRepository methods
stateChangesRepository methods
Auto propagation
examples
propagation function
Active/active failover
Stop propagation for relation type
topology query
transparent state
transparent state
Custom propagation function
Propagation function
Propagation function