LogoDark mode logo
LogoDark mode logo
Contact SupportLoading Light/Dark Toggle

  • Custom Data Streams
  • Scripts
  • Types and Custom Types
  • Tags
  • Custom Correlations
  • Shapes
  • API
  • OAuth 2.0 configuration
  • SQL Analytics
Data sources

advanced featurescustom data streams

Custom Data Streams

What is a Data Stream?

How to add a custom Data Stream

Generic Schema Reference

Specific Entry Point Reference

What is a Data Stream?

Data streams standardize data from all the different shapes and formats your tools use into a straightforward tabular format.

While creating a tile you can tweak data streams by grouping or aggregating specific columns.

Depending on the kind of data, SquaredUp will automatically suggest how to visualize the result, for example as a table or line graph.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

What is a custom Data Stream?

A custom data stream is a data stream that you, as an advanced user, can write yourself.

Any data stream you create can be edited by clicking the edit button (pencil) next to it in the tile editor, and also from Settings > Advanced > Data Streams.

How to add a custom Data Stream

  1. In SquaredUp, browse to Settings > Advanced > Data Streams.
  2. Click Add custom data stream.
  3. Add your custom data stream by entering the following settings:
    1. Name:
      Enter a display name for your data stream.

      The display name is the name that you use to identify your data stream in SquaredUp. It has no technical impact and doesn't need to be referenced in the data stream's code.

    2. Data source:
      Choose the data source this data stream is for.
      After you've chosen the data source the Entry Point field displays.
    3. Entry Point:
      Specify the data stream entry point and enter the Code below.

      Each data stream uses an entry point, which can either be global (unscoped) or scoped, and this determines whether the data stream uses the tile scope.

      Data streams can be either global or scoped:

      • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
      • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

      To find out which entry point to select and get code examples for the Code field, see the help below.
  4. Click Save to save your data stream.

Generic schema reference

This section covers parameters that can be used in any entry point. For parameters that are specific to individual entry points see Specific Entry Point Reference

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

Metadata can also be defined on the Columns tab when configuring data tiles. See Columns.

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Shapes

Specific Entry Point Reference

Many of the data streams in these examples can now be created easily using configurable data streams. The reference information below can also be useful editing data streams, because any data stream created using configurable data streams can be edited from Settings > Data Streams.

Data Stream for Events

Which entry point do I have to select from the dropdown?

Events

Code example:

{
  "name": "customEvents",
  "dataSourceConfig": {
    "eventTypes": [
      "APP_SERVER_RESTART",
      "APPLICATION_DEPLOYMENT"
    ],
    "severities": [
      "INFO",
      "WARN"
    ]
  },
  "rowPath": [],
  "matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },
  "metadata": []
}

Parameters:

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

eventTypes
Optional
Enter the names of the event types you want to return. If you don't specify any event types, all event types will be returned.
You can find a list of all AppDynamics event types in their API documentation: https://docs.appdynamics.com/display/PRO40/Events+Reference
severities
Optional
You can filter the returned events by their severity. The possible values are:
  • INFO
  • WARN
  • ERROR
If you don't specify any severities, you'll get events of all severities.
matches
Optional

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

metadata

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

Data Stream for Metrics

Which entry point do I have to select from the dropdown?

Metrics

Code example:

{
    "name": "kpiDatabaseAvailability",
    "dataSourceConfig": {
        "metric": "KPI|DB Availability",
        "scaleFactor": 100
    },
    "rowPath": [],
    "matches": {
        "sourceName": { "type": "equals", 
        				"value": "AppDynamics" 
        				},
        "type": { "type": "equals", 
        			"value": "db" 
        		  }
    },
    "metadata": []
}

Parameters:

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

metric
Mandatory
You need to enter the correct string of the AppDynamics metric here. To find the correct, string, you need to log into your AppDynamics account and open the Metric Browser. Click on one of the metrics to see the full path of the metric. Which part of the metric you have to enter for metric depends on the object:
For applications, tiers, and nodes:
Enter only the bit after the last |
Example: For "Overall Application Performance|Calls per Minute" you need to enter "Calls per Minute".
For hosts, databases and EUM apps:
Enter the bits before and after the last |
Example: For "Databases|CS-Product Postgre Database|KPI|Calls per Minute" you need to enter "KPI|Calls per Minute"
scaleFactor
Optional
You can enter a number to scale the results. The results will be multiplied by the number you entered. This is useful when you want to convert results to percentages. For example, when the result is a number between 0 and 1, you can multiply the result by 100 to get a percentage.
matches
Optional

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Note: You should limit the Data Stream to the objects that have the metric you specified in the metric parameter.
metadata

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

Example for a JQL query

This Data Stream returns a list of issues based on the given JQL query.

Tip: When you are using the blocks visualization for a tile that uses this Data Stream, completed issues will be shown as green, all other issues will be gray.

Which entry point do I have to select from the dropdown?

JQL query

Code example:

{
                "name": "projectIssuesAll",
                "dataSourceConfig": {
                    "jql": "project={{key}}&updatedDate>='{{timeframe.startTime}}'"
                },
                "rowPath": [],
                "matches": {
                    "type.0": { "type": "equals", "value": "jira project" }
                },
                "metadata": [
    { "name": "key",                               "displayName": "Key",                         "shape": "string", "role": "id" },
                { "name": "fields.summary",                    "displayName": "Summary",                     "shape": "string" },
                { "name": "fields.issuetype.name",             "displayName": "Type",                        "shape": "string" },
                { "name": "fields.priority.name",              "displayName": "Priority",                    "shape": "string" },
                { "name": "fields.status.name",                "displayName": "Status",                      "shape": "string" },
                { "name": "fields.status.statusCategory.name", "displayName": "Status Category",             "shape": "string", "visible": false },
                { "name": "fields.resolution.name",            "displayName": "Resolution",                  "shape": "string" },
                { "name": "fields.project.name",               "displayName": "Project",                     "shape": "string" },
                { "name": "fields.issuetype.subtask",          "displayName": "Subtask",                     "shape": "boolean", "visible": false },
                { "name": "fields.creator.displayName",        "displayName": "Creator",                     "shape": "string", "visible": false },
                { "name": "fields.reporter.displayName",       "displayName": "Reporter",                    "shape": "string" },
                { "name": "fields.created",                    "displayName": "Created",                     "shape": "date" },
                { "name": "fields.updated",                    "displayName": "Updated",                     "shape": "date" },
                { "name": "fields.statuscategorychangedate",   "displayName": "Last Status Category Change", "shape": "date", "visible": false },
                { "name": "fields.resolutiondate",             "displayName": "Resolution Date",             "shape": "date" },
                { "name": "url",                               "displayName": "Link",                        "shape": "url" },
                { "name": "blockState",                        "displayName": "Block State",                 "shape": "state", "visible": false },
                { "name": "blockLabel",                        "displayName": "Block Label",                 "shape": "string", "role": "label", "visible": false }
]
            }

Parameters:

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

jql

Enter the JQL query you want to use here. The query will call the /rest/api/3/search endpoint, please refer to the Atlassian Jira API documentation for details about which queries you can use: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-get)

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

This custom Data Stream will enable you to get different granularity or metrics than the default Cost Data Stream for AWS.

Which entry point do I have to select from the dropdown?

Account Cost

Code example:

{
    "name": "account-cost",
    "dataSourceConfig": {
        "groupBy": [
            {
                "Type": "DIMENSION",
                "Key": "SERVICE"
            }
        ],
        "metrics": [
            "AmortizedCost"
        ],
        "granularity": "HOURLY",
        "filter": {
            "Dimensions": {
                "Key": "SERVICE",
                "Values": [
                    "AWS Cost Explorer"
                ]
            }
        },
        "rowPath": [
            "ResultsByTime",
            [
                "Groups"
            ]
        ],
        "matches": {
            "sourceType.0": {
                "type": "equals",
                "value": "AWS Account"
            }
        },
        "metadata": [
            {
                "name": "ResultsByTime.TimePeriod.Start",
                "displayName": "Date",
                "shape": "date"
            },
            {
                "name": "ResultsByTime.Groups.Keys.0",
                "displayName": "Service",
                "role": "label",
                "shape": "string"
            },
            {
                "name": "ResultsByTime.Groups.Metrics.AmortizedCost.Amount",
                "displayName": "Cost",
                "role": "value",
                "shape": "currency"
            },
            {
                "name": "ResultsByTime.Groups.Metrics.AmortizedCost.Unit",
                "displayName": "Currency",
                "shape": "string"
            },
            {
                "name": "ResultsByTime.Estimated",
                "displayName": "Estimated",
                "shape": "boolean"
            }
        ]
    }
}

Parameters

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

Note: You'll find a detailed description about what each parameter does and which values you can use in the AWS API docs: https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_GetCostAndUsage.html

metrics
Mandatory
The metrics you want to return, for example AmortizedCost. If you don't specify metrics, the default value is UnblendedCost.
granularity
Mandatory
The granularity of the data, for example HOURLY. If you don't specify granularity, the default value is DAILY.
groupBy
Optional
Use this if you want to group the data. For example, the default AWS Cost Data Stream groups the data by SERVICE, which returns the costs for each service in your account.
If you don't group by anything, you'll get the costs for your whole account.
filter
Optional
Use this if you want to filter AWS costs by different dimensions. For example, if you only want to return the costs of the Cost Explorer service, you can filter to that service here.
If you don't use any filter, all cost data for your account will be returned.

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

rowPath Parameter

Optional

SquaredUp expects data in table form, and here's where you define how the table with your return data will be structured.

The rowPath will tell SquaredUp which items you want to convert into rows.

Example:

Let's say your return data looks like this:

{
    "generalInfo": "some info",
    "results": [
        {
            "name": "object 1",
            "tags": [
                "tag 1",
                "tag 2",
                "tag 3"
            ]
        },
        {
            "name": "object 2",
            "tags": [
                "tag 1",
                "tag 4"
            ]
        }
    ]
}

Now it depends on what data you want to base your table on, do you want rows per object or per tag?

If you want to see which objects have which tags, your rowPath would be results, and your table would look like this:

name
tags
generalInfo
object 1
tag 1, tag 2, tag 3
some info
object 2
tag 1, tag 4
some info

If you want to turn each tag into a row and see to which objects they are applied, your rowPath would be results.tags, and your table would look like this:

tags
name
generalInfo
tag 1
object 1
some info
tag 1
object 2
some info
tag 2
object 1
some info
tag 3
object 1
some info
tag 4
object 2
some info

As you can see in the example, each parameter gets turned into a column and the items of the parameter you chose as the rowPath will be turned into rows.

You might also have noticed in the example that the parameter generalInfo was included in both cases. This is because after going through all parameters on the same level as your rowPath, SquaredUp will move through all levels above the rowPath and create columns from those parameters, too. Parameters on levels below the rowPath won't be included in the table.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Log Analytics Data Stream

Which entry point do I have to select from the dropdown?

Log Analytics Query

Code example:

{
  "name": "customLogAnalyticsQuery",
  "dataSourceConfig": {
    "query": "Heartbeat | where TimeGenerated > ago(1d)",
    "includeWorkspaceName": true
  },
  "rowPath": [],
  "matches": {
    "sourceType": {
      "type": "equals",
      "value": "microsoft.operationalinsights/workspaces"
    }
  },
  "metadata": []
}

Parameters

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

query
Mandatory

Insert your Kusto query here. The query must be written all in one line.

Note:

The Kusto query supports mustache parameters. Mustache parameters must refer to the property names of an Azure Application (e.g. name, resourceGroup).

This data stream supplies scoped objects individually for mustache parameters. When there are multiple objects in scope this data source will send the query multiple times, once for each object. The results are then displayed together, for example in a single table.

You can use properties of objects and write them in between curly braces e.g {{name}} to use them as mustache parameters. Whenever you use mustache parameters, you need to use a scope of objects that contain the property you're referencing.

For example, if objects of type "host" have a property called name, you can use {{name}}. This will resolve {{name}} to the value of the name property of the different "host" objects used in the scope.

includeWorkspaceName
Optional
If you set this to true an extra column will be added at the end of the output that contains the workspace name the results of this row refer to. This is useful when you are querying multiple workspaces.

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Custom Metrics Data Stream

Which entry point do I have to select from the dropdown?

Metric

Code example:

{
  "name": "customMetric",
  "dataSourceConfig": {
    "metricNames": "Network Out Total"
  },
  "rowPath": ["value", "timeseries", "data"],
  "matches": {
    "sourceType": {
      "type": "oneOf",
      "values": [
        "microsoft.compute/cloudservices",
        "microsoft.compute/cloudservices/roles",
        "microsoft.compute/virtualmachines",
        "microsoft.compute/virtualmachinescalesets",
        "microsoft.compute/virtualmachinescalesets/virtualmachines"
      ]
    }
  },
  "metadata": []

Parameters

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

metricNames
Mandatory
Enter the metric you want to return. You can get a list of all available metrics in the Azure documentation: https://docs.microsoft.com/en-us/azure/azure-monitor/essentials/metrics-supported
Make sure to use the correct metrics for the objects you're using. The Azure docs will tell you which metrics a re available for which objects. You should limit your Data Stream to those objects with the matches parameter.

rowPath Parameters

rowPath
The rowPath has to be ["value", "timeseries", "data"]

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Example for Custom Metrics

Which entry point do I have to select from the dropdown?

Metrics

Code example:

{
    "name": "cpuUser",
    "dataSourceConfig": {
        "metric": "system.cpu.user"
    },
    "rowPath": [],
    "matches": {
        "type": { 
        	"type": "equals", 
        	"value": "datadog host" 
        }
   	},
    "metadata": [
        { "name": "host",      "displayName": "Host",      "shape": "string" },
        { "name": "value",     "displayName": "Value",     "shape": "percent" },
        { "name": "timestamp", "displayName": "Timestamp", "shape": "date" }
    ]
}

Parameters

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

metric

Mandatory

To find out which metrics are available and their exact name, you can make an API GET request to the Datadog API. Please note that some of the metrics might not be compatible with the Datadog host object. Since this Data Stream is only for Datadog host objects, only metrics that are meant for host objects can be used.

Settings for the API request:

URL: https://API_URL/api/v1/metrics?from=0

API_URL depends on the URL of your Datadog instance and will be one of the following:

  • api.datadoghq.com
  • api.datadoghq.eu
  • api.ddog-gov.com

Headers:
DD-API-KEY: An API key you created in your Datadog instance

DD-APPLICATION-KEY: An application key you created in your Datadog instance

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

Datadog Data Streams only work with the object type host (datadog host).

rowPath Parameters

Can be left empty.

metadata Parameters

To make sure that all your data has the proper shape you should enter the metadata like shown in the example:

"metadata": [
        { "name": "host",      "displayName": "Host",      "shape": "string" },
        { "name": "value",     "displayName": "Value",     "shape": "percent/bytes/milliseconds/..." //depends on the metric// },
        { "name": "timestamp", "displayName": "Timestamp", "shape": "date" }
]

This ensures that the timestamp comes back as a date etc.

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

You can use mustache parameters in your data stream. You can use them in your query as well as anywhere else in the data stream code (for example, to call an API endpoint depending on an object's name).

A mustache parameter is a dynamic value, the actual value will be inserted to replace the field in curly braces. For example, {{timeframe.start}} will insert the start time based on the timeframe configured within the tile, or {{name}} will insert the name of the object(s) in scope.

This data stream supplies scoped objects individually for mustache parameters. When there are multiple objects in scope this data source will send the query multiple times, once for each object. The results are then displayed together, for example in a single table.

You can use properties of objects and write them in between curly braces e.g {{name}} to use them as mustache parameters. Whenever you use mustache parameters, you need to use a scope of objects that contain the property you're referencing.

For example, if objects of type "host" have a property called name, you can use {{name}}. This will resolve {{name}} to the value of the name property of the different "host" objects used in the scope.

Query Example:

{
  "name": "customQuery",
  "dataSourceConfig": {
    "queryBody": {
      "query": {
        "query_string": {
          "query": "managedEntityDisplayName:\"Microsoft Windows Server 2016 Datacenter\""
        }
      }
    },
    "queryParams": {}
  },
  "rowPath": [
    "hits",
    "hits"
  ],
  "matches": "all",
  "metadata": [
    {
      "name": "hits.hits._index",
      "displayName": "Index"
    },
    {
      "name": "hits.hits._source.managedEntityDisplayName",
      "displayName": "Entity Name"
    },
    {
      "name": "hits.hits._source.counter",
      "displayName": "Metric"
    },
    {
      "name": "hits.hits._source.value",
      "displayName": "Value"
    },
    {
      "name": "hits.hits._source.timestamp",
      "displayName": "Timestamp",
      "shape": "date"
    }
  ]
}

Parameters:

name
Mandatory

The internal name of the Data Stream. Can be used the refer to this Data Stream in a tile's JSON instead of using the Data Stream's internal ID.

queryBody
Mandatory
Insert your Query DSL here. Your query needs to replace lines 5 to 9 in the code example above.
rowPath
Mandatory
Depends on the data returned from your query. Enter the path to the row you want to use (the row path in the code example above is hits.hits).
metadata
Mandatory
Depends on the data returned from your query. Use the code example above as a template for the columns you want to return.
metadata Parameter:

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Lucene Query Example:

{
  "name": "luceneQuery",
  "dataSourceConfig": {
    "queryBody": {},
    "queryParams": {
      "q": "managedEntityDisplayName:\"Microsoft Windows Server 2016 Datacenter\""
    }
  },
  "rowPath": [
    "hits",
    "hits"
  ],
  "matches": "all",
  "metadata": [
    {
      "name": "hits.hits._index",
      "displayName": "Index"
    },
    {
      "name": "hits.hits._source.managedEntityDisplayName",
      "displayName": "Entity Name"
    },
    {
      "name": "hits.hits._source.counter",
      "displayName": "Metric"
    },
    {
      "name": "hits.hits._source.value",
      "displayName": "Value"
    },
    {
      "name": "hits.hits._source.timestamp",
      "displayName": "Timestamp",
      "shape": "date"
    }
  ]
}

Parameters:

name
Mandatory

The internal name of the Data Stream. Can be used the refer to this Data Stream in a tile's JSON instead of using the Data Stream's internal ID.

q
Mandatory
Insert your Lucene query here (line 6 in the code example above).
rowPath
Mandatory
Depends on the data returned from your query. Enter the path to the row you want to use (the row path in the code example above is hits.hits).
metadata
Mandatory
Depends on the data returned from your query. Use the code example above as a template for the columns you want to return.
metadata Parameter:

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Custom API Call Example:

{
  "name": "customApiCall",
  "dataSourceConfig": {
    "method": "POST",
    "endpoint": "{{name}}/_search",
    "headers": {},
    "params": {},
    "body": {
      "query": {
        "query_string": {
          "query": "managedEntityDisplayName:\"Microsoft Windows Server 2016 Datacenter\""
        }
      }
    }
  },
  "rowPath": [
    "hits",
    "hits"
  ],
  "matches": "all",
  "metadata": []
}

Parameters:

name
Mandatory

The internal name of the Data Stream. Can be used the refer to this Data Stream in a tile's JSON instead of using the Data Stream's internal ID.

method
Mandatory
Enter the method (POST or GET)
endpoint
Mandatory
Enter the API endpoint you want to call.
headers, params
Optional
Here you can add headers and parameters to your API call.
body
Mandatory or optional
Mandatory when you are using a POST method to insert your custom query.
Optional when you are using a GET method.
rowPath
Mandatory
Depends on the data returned from your query. Enter the path to the row you want to use (the row path in the code example above is hits.hits).
metadata
Mandatory
Depends on the data returned from your query.
metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Create BigQuery (Scoped) data stream

Code example:

{
  "name": "exampleScopedBigQuery",
  "dataSourceConfig": {
    "query": "SELECT project.name, service.description FROM `<project_id>.<data_set_name>.<table_name>` WHERE project.id in ('{{sourceId}}') GROUP BY 1,2 ORDER BY 1,2;"
  },
  "rowPath": [],
  "matches": {
    "sourceType.0": {
      "type": "oneOf",
      "values": [
        "GCP Project"
      ]
    }
  },
      "metadata": [
        { "name": "name", "displayName": "Project","shape": "string", "role": "label" },
        { "name": "description", "displayName": "Service", "shape": "string" },
      ]
}

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

useTimeFrame
Optional
You can add "useTimeFrame": true to the dataSourceConfig to use the dashboard timeframe, and inject @startDate and/or @endDate parameters into your query and these will be passed to the dashboard timeframe.
For example:
{
    "name": "exampleBigQuery",
    "dataSourceConfig": {
        "useTimeFrame": true,
        "query": "SELECT <column_1> FROM `<project_id>.<data_set_name>.<table_name>` WHERE <dateColumn> BETWEEN @startDate AND @endDate"
    },
    "rowPath": [],
    "matches": "none",
    "metadata": []
}

query
Mandatory
Insert your query here.
rowPath
Optional
Depends on the data returned from your query. Enter the path to the row you want to use.
matches
Matches should be populated appropriately to the type of objects in the scope, that you want this data stream to work for.

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

metadata

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

Example 1: Using a Prometheus query

Which entry point do I have to select from the dropdown?

Prometheus Query (Global)

Code example:

{
"name": "prometheus_global",
"matches": "none",
"dataSourceConfig": {
"ignoreTimeFrame": true,
"query": "sum by (instance) (rate(kubedns_probe_dnsmasq_latency_ms_sum[1m])) / sum by (instance) (rate(kubedns_probe_dnsmasq_latency_ms_count[1m]))"
},
"rowPath": [
"results"
],
"metadata": []
}

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

query
Mandatory
Note: You can't use mustache parameters in the query since it doesn't use the matches parameter.
ignoreTimeFrame
Optional

You can add the ignoreTimeFrame parameter and set it to true if you want the query to ignore the current dashboard timeframe of a dashboard.
If ignoreTimeFrame is left out or set to false, the query will use the current dashboard timeframe.

matches Parameters

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

rowPath Parameters

Mandatory

Depends on the data returned from your query. Enter the path to the row you want to use (the row path in the code example above is results).

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Example 2: Get CPU usage for a selected object from a GCP cluster

Note: This Data Stream requires a Google Cloud Platform data source which has to be configured to return information from a cluster.

Which entry point do I have to select from the dropdown?

PromQL

Code example:

{
  "name": "prometheuscpu",
  "matches": {
    "sourceType": {
      "type": "equals",
      "value": "compute#instance"
    }
  },
  "dataSourceConfig": {
    "query": "instance:node_cpu:rate:sum{instance=\"{{name}}\"}"
  },
  "rowPath": [
    "results"
  ],
  "metadata": [
  ]
}

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

query
Mandatory
ignoreTimeFrame

You can add the ignoreTimeFrame parameter and set it to true if you want the query to ignore the current dashboard timeframe of a dashboard.
If ignoreTimeFrame is left out or set to false, the query will use the current dashboard timeframe.

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

rowPath Parameters

Mandatory

Depends on the data returned from your query. Enter the path to the row you want to use (the row path in the code example above is results).

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Which entry point do I have to select from the dropdown?

SWQL

Code example:

Information about parameters in the script:

{
    "name": "my-custom-swql-datastream",
    "dataSourceConfig": {
        "swql": "SELECT something FROM somewhere WHERE something like something"
    },
    "rowPath": ["results"],
    "matches": {
        "sourceType": { 
        	"type": "equals",
        	"value": "SolarWinds Host" 
        	}
    },
    "metadata": []
}

Parameters

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

swql
Here you define which data to return, written in the format
SELECT something FROM somewhere WHERE something like something

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Example 1: Get Windows Event Log Entries for Given Hosts

This Data Stream uses Host objects which need to come from a different data source (for example, from the VMware vCenter data source), and performs a query to get Windows application log event messages.

Which entry point do I have to select from the dropdown?

Splunk Enterprise Query (Scoped)

Code example:

{
  "name": "SplunkAppEventsForHost",
  "dataSourceConfig": {
    "query": "search source=\"WinEventLog:Application\" | where host = \"{{name}}\" | fields host,Message"
  },
  "matches": {
    "type": {
      "type": "equals",
        "value": "host"
      }
   },
  "rowPath": [],
  "metadata": [
    { "name": "_indextime", "displayName": "Timestamp", "shape": "date",    "role": "timestamp" },
    { "name": "host",       "displayName": "Host",      "shape": "string" },
    { "name": "Message",    "displayName": "Message",   "shape": "string",  "role": "value" }
  ]
}

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

query
Mandatory
ignoreTimeFrame
Optional

You can add the ignoreTimeFrame parameter and set it to true if you want the query to ignore the current dashboard timeframe of a dashboard.
If ignoreTimeFrame is left out or set to false, the query will use the current dashboard timeframe.

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Example 2: Get Results for Saved Report

Note: This Data Stream uses the Splunk Enterprise organization object and doesn't rely on objects coming from other data sources.

Which entry point do I have to select from the dropdown?

Splunk Enterprise Query (Scoped)

Code example:

{
  "name": "SplunkRunMySavedReport",
  "dataSourceConfig": {
    "query": "| savedsearch mySavedReport | fields host,Message"
  },
  "matches": { 
    "sourceType": { "type": "equals", "value": "Splunk Enterprise Organization" } 
  },
  "rowPath": [],
  "metadata": [
    { "name": "_indextime", "displayName": "Timestamp", "shape": "date",    "role": "timestamp" },
    { "name": "host",       "displayName": "Host",      "shape": "string" },
    { "name": "Message",    "displayName": "Message",   "shape": "string",  "role": "value" }
  ]
}

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

query
Mandatory
ignoreTimeFrame
Optional

You can add the ignoreTimeFrame parameter and set it to true if you want the query to ignore the current dashboard timeframe of a dashboard.
If ignoreTimeFrame is left out or set to false, the query will use the current dashboard timeframe.

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Example 3: Get Time-Series Data for Metric

Note: This Data Stream uses the Splunk Enterprise organization object and doesn't rely on objects coming from other data sources.

Which entry point do I have to select from the dropdown?

Splunk Enterprise Query (Scoped)

Code example:

{
  "name": "SplunkMpoolUsedMetric",
  "dataSourceConfig": {
    "query": "| mstats avg(\"spl.mlog.mpool.used\") WHERE \"index\"=\"_metrics\" span=60s chart=true"
  },
  "matches": { 
    "sourceType": { "type": "equals", "value": "Splunk Enterprise Organization" } 
  },
  "rowPath": [],
  "metadata": [
    { "name": "_time",                    "displayName": "Timestamp", "shape": "date",    "role": "timestamp" },
    { "name": "avg(spl.mlog.mpool.used)", "displayName": "Value",     "shape": "number",  "role": "value" }
  ]
}

name

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

dataSourceConfig Parameters

query
Mandatory
ignoreTimeFrame
Optional

You can add the ignoreTimeFrame parameter and set it to true if you want the query to ignore the current dashboard timeframe of a dashboard.
If ignoreTimeFrame is left out or set to false, the query will use the current dashboard timeframe.

matches Parameters

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

metadata Parameter

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Creating a custom data stream allows you to created a scoped data stream, i.e. a data stream that makes use of objects in the scope.

Which entry point do I have to select from the dropdown?

HTTP Request (scoped)

Each data stream uses an entry point, which can either be global (unscoped) or scoped, and this determines whether the data stream uses the tile scope.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Code example:

{
	"name": "scope example",
	"matches": "all",
	"dataSourceConfig": {
		"endpointPath": "post",
		"httpMethod": "post",
		"idSeparator": "], [",
		"headers": [
			{
			"key": "header1",
			"value": "header1Val"
			},
			{
			"key": "sourceIds",
			"value": "[{{sourceIds}}]"
			}
		],
		"expandInnerObjects": true
	},
	"rowPath": []
}

You should set the matches statement so that your custom data stream appears when you select the appropriate object types in the tile editor. You can use additional mustache constructs when using the scoped entry point: targetNodes, sourceId, sourceIds in selected dataSourceConfig parameters as shown below. The separator inserted between sourceId values in the sourceIds replacement string can be changed by setting idSeparator in dataSourceConfig.

Parameters

Mandatory

The internal name of the data stream. Can be used the refer to this data stream in a tile's JSON instead of using the data stream's internal ID.

endpointPath
Mandatory
(string) - the endpoint path relative to the data source config's base URL to be queried (supports mustache parameters)
httpMethod
Mandatory
(string) - "get" or "post"
headers
Optional
(array of key, value pairs) - any additional headers for this request (supports mustache parameters in value only)
getArgs
Optional
(array of key, value pairs) - any additional query args (supports mustache parameters in value only)
postBody
Optional
(string) – only if httpMethod is "post", a JSON string defining the body (supports mustache parameters)
idSeparator
Optional
(string) - this controls how the replacement value "sourceIds" is generated
pathToData
Optional
(string) - where in the returned payload, the desired data is to be found
expandInnerObjects
Optional
(boolean) - whether to expand inner objects and arrays in the desired data

Note: Defining the matches parameter is mandatory.

With the matches parameter you define for which objects the data stream will be shown in SquaredUp. It works like this:
When you configure a tile, you have to choose its scope. If this scope contains objects you specified here in the matches parameter, the data stream will be shown in SquaredUp under Data Streams. If the scope doesn't contain objects specified here, the data stream will be hidden.
This keeps things clean and simple since you'll only see the data stream when it's relevant for the scope you chose. As a best practice you should limit the data stream to objects that make sense for the specific use case of this data stream.

Format for matches:

//If you want to specify only one value of an object property//
"matches": {
	"ObjectProperty": {
		"type": "equals",
		"value": "ValueOfTheObjectProperty"
	}
},
 
//If you want to specify multiple values for an object property//
"matches": {
	"ObjectProperty": {
 		"type": "oneOf",
		"values": ["ValueOfTheObjectProperty1", "ValueOfTheObjectProperty2", "ValueOfTheObjectProperty3"]
	}
},

Example for limiting a data stream to objects:

If you are using multiple values for the object property, you can decide if you want the data stream to be visible for objects that match all of the criteria or at least one of the criteria.

Lets say you have two values you want objects to have in order for the data stream to be visible for them:

  • a SourceName property with the value AppDynamics (meaning objects that come from the AppDynamics data source)
  • a type property with the value app (meaning application objects)

If you want the data stream to be visible only for objects that match both of the criteria, your code would look like this:

"matches": {
    "sourceName": {
      "type": "equals",
      "value": "AppDynamics"
    },
    "type": {
      "type": "equals",
      "value": "app"
    }
  },

If you want the data stream to be visible for objects that match at least one of the criteria, your code would look like this:

"matches": [
    {
        "sourceName": {
            "type": "equals",
            "value": "AppDynamics"
        }
    },
    {
        "type": {
            "type": "equals",
            "value": "app"
        }
    }
]

Note: If you run into errors when configuring the matches parameter, check if you're dealing with a global entry point.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

Global entry points can't use specific objects in the matches parameter. You can identify global entry points by their name, they have "Global", "No Scope" or "Unscoped" added to their name.

There are two possible options for the matches parameter for global entry points:

"matches": "none",
When creating a tile, the Data Stream will be shown as long as no scope is selected. As soon as a scope is selected, the Data Stream will be hidden.
"matches": "all",
When creating a tile, the Data Stream will be shown as soon as any scope is selected.

Optional

SquaredUp expects data in table form, and here's where you define how the table with your return data will be structured.

The rowpath (Path to data) will tell SquaredUp which items you want to convert into rows.

Example:

Let's say your return data looks like this:

{
    "generalInfo": "some info",
    "results": [
        {
            "name": "object 1",
            "tags": [
                "tag 1",
                "tag 2",
                "tag 3"
            ]
        },
        {
            "name": "object 2",
            "tags": [
                "tag 1",
                "tag 4"
            ]
        }
    ]
}

Now it depends on what data you want to base your table on, do you want rows per object or per tag?

If you want to see which objects have which tags, your rowpath would be results, and your table would look like this:

name
tags
object 1
tag 1, tag 2, tag 3
object 2
tag 1, tag 4

If you want to turn each tag into a row and see to which objects they are applied, your rowpath would be results.tags, and your table would look like this:

tags
name
tag 1
object 1
tag 1
object 2
tag 2
object 1
tag 3
object 1
tag 4
object 2

As you can see in the example, each parameter gets turned into a column and the items of the parameter you chose as the rowpath will be turned into rows.

Optional, but recommended

The metadata parameters are used to describe columns in order to tell SquaredUp what to do with them. You can do multiple things with the metadata parameters:

  • Specify how SquaredUp should interpret the columns you return and - to an extent - how their content displayed. You do this by giving each column a shape.

    The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

  • Filter out or just hide columns.
    Only the columns you define in metadata will be returned in the results. This helps you to filter out columns you don't need. If you need the content of a column but don't want to display it, you can use the visible parameter.
  • Give columns a nicely readable display name.
  • Assign a specific role to columns .

    The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

If you don't specify any metadata, all columns will be returned and SquaredUp will do its best to determine which columns should be used for which purpose. If you're returning pretty simple data, for example just a string and a number, this can work fine. But if you're returning two columns with numbers it gets trickier for SquaredUp to figure out which one is the value and which one is just an ID or some other number.

Parameters:

Before you start specifying metadata, leave them empty at first and get all the raw data with your new data stream once.

In order to do this, finish creating your custom data stream without metadata and create a tile with this data stream. The Table visualization will show you all raw data.

This will give you an overview about all columns and their content and help you decide which columns you need and what their shapes and roles should be. It's also essential for getting the correct column name to reference in the name parameter.

Use this information to go back to the data stream configuration and specifying the metadata.

name
Mandatory
Enter the name of the column you are referencing here.
To find the name of a column, get the data from this data stream once without any metadata. See the tip above for how to do that. You'll see the column name when you hover over the column in the Table.
displayName
Optional
Here you can give the column a user-friendly name
shape
Recommended

The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.

Note: Please refer to the list of shapes below this table to see available shapes.
role
Recommended

The role you assign to a column tells SquaredUp the purpose of the column. For example, if you have two different columns that contain numbers, you need to assign the role value to the column that contains the actual value you want to use in your visualization.

Note: Please refer to the list of roles below this table to see available roles.
visible
Optional
true or false
Use this if you need a columns content but don't need to display the column itself.
Example: Column A contains the full link to a ticket in your ticket system. Column B contains the ticket ID. You want to use the ticket ID as a label for the link, turning the long URL into a much nicer to read "Ticket 123". This is why you need the content of column B, to assign it as a label for column A. But since the URL is now displayed as the ticket ID, it would be redundant to still display column B. This is why you hide column B with false.

There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:

  • Basic types, like: boolean, date, number, string
  • Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like: currency (generic currency), eur, gbp, usd
  • Data types, like: bytes, kilobytes, megabytes
  • Time types, like: seconds, milliseconds, timespan
  • The status type : state
  • Utility types, like:
    customUniturl (will be displayed as a link)

Tip:

Some shapes can be configured.

If a shape is configurable, you can edit how the shape displays data in SquaredUp.

See Configurable shapes

id
Used by data streams feeding the aggregate health stream to identify their Id column
label
A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph.
link
A column containing a link that can be used as a drilldown in Status Blocks.
timestamp
A column containing a date to use on the X -axis of a Line Graph.
unitLabel
A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis.
value
A column containing the numeric value you want to use in your visualization.

Was this article helpful?


Have more questions or facing an issue?
Submit a ticket

On this page

  • What is a Data Stream?
  • What is a custom Data Stream?
  • How to add a custom Data Stream
  • Generic schema reference
  • Specific Entry Point Reference

Footer

Sites

  • SquaredUp
  • SQUAREDUP DS
  • DOWNLOAD
  • COMMUNITY ANSWERS

Quick Links

  • Contact Support
  • Events
  • Careers

Small Print

  • Privacy Policy
  • Terms and Conditions
YoutubeX (Twitter)LinkedInBlueSky

© SquaredUp 2025