New Relic allows you to group entities together in groupings called workloads. This enables better monitoring of the full stack used by a team or project.
Here we show you how to use our NerdGraph API to do some workloads-related tasks:
- Get the workloads of an account
- Get the list of entities in a workload
- Get the status of a workload
- Create a workload
- Modify a workload
- Set a static status for a workload
- Modify the automatic status rules for a workload
- Duplicate a workload
- Delete a workload
See also our post on how to customize the charts you see in your workload.
Important
You can also use the CLI and Terraform resource to automate these tasks.
Get the workloads of an account
To get all workloads of an account, use the following GraphQL query and pass the account ID via the id
field. In this example, we retrieve three basic fields:
guid
: the workload GUID.name
: the workload name.permalink
: the permanent URLs on the New Relic UI.
{ actor { entitySearch(query: "accountId = YOUR_ACCOUNT_ID and type = 'WORKLOAD'") { results { entities { guid name permalink } } } }}
The response includes this type of data for each workload:
{ "data": { "actor": { "entitySearch": { "results": { "entities": [ { "guid": "MTY...NTY", "name": "Acme Telco - Fulfillment Chain", "permalink": "https://one.newrelic.com/redirect/entity/MTY...NTY" }, ... ] } } } }, "extensions": { ... }}
Get the list of entities in a workload
You can get the entities that belong to a workload with the following query, just by passing the workload GUID (guid
) as an argument. In this example we also retrieve some workload metadata:
accountId
: the workload account.name
: the workload name.permalink
: the workload permanent URL on the New Relic UI.alertSeverity
: the status of the workload. This value can have up to 10 minutes of delay; if you want to force the calculation of the workload status in query time, please use the Get the status of a workload example.- The nested
collection
,members
andresults
objects, which contain the actual list of entities:- The
name
argument in thecollection
object takes the valueWORKLOAD
. count
: Number of entities in the workload.
- The
{ actor { entity(guid: "YOUR_WORKLOAD_GUID") { accountId name permalink ... on AlertableEntity { alertSeverity } ... on CollectionEntity { collection(name: "WORKLOAD") { members { count results { entities { accountId entityType name guid ... on AlertableEntityOutline { alertSeverity } } } } } } } }}
The query returns a list of entities that looks like this:
{ "data": { "actor": { "entity": { "accountId": 1606862, "name": "Acme Telco - Ecommerce", "permalink": "https://one.newrelic.com/redirect/entity/MTYwNjg2MnxOUjF8V09SS0xPQUR8MTIyMzQ", "alertSeverity": "CRITICAL", "collection": { "members": { "count": 201, "results": { "entities": [ { "accountId": 1606862, "alertSeverity": "CRITICAL", "entityType": "APM_APPLICATION_ENTITY", "guid": "MTYwNjg2MnxBUE18QVBQTElDQVRJT058NDMxOTIwNTg", "name": "Fulfillment Service" }, { "accountId": 1606862, "alertSeverity": "NOT_ALERTING", "entityType": "INFRASTRUCTURE_HOST_ENTITY", "guid": "MTYwNjg2MnxJTkZSQXxOQXw3MDQzMzA2NzIyMjk2NDg4Mzc", "name": "ip-172-31-16-222" }, { "accountId": 1606862, "alertSeverity": "NOT_ALERTING", "entityType": "INFRASTRUCTURE_AWS_LAMBDA_FUNCTION_ENTITY", "guid": "MTYwNjg2MnxJTkZSQXxOQXw1MjMyNzM2ODgzNjAwNjYyMjE1", "name": "TelcoDT-purchase-log-lambda" }, ... ] } } } } } }}
Get the status of a workload
If you want to force the calculation of the status of a workload, you can use the following query, passing the account id (id
) as the argument for the account
field, and the workload GUID (guid
) as the argument for the collection
field.
{ actor { entity(guid: "YOUR_WORKLOAD_GUID") { ... on WorkloadEntity { guid workloadStatus { statusValue } } } }}
And this is what you'll get in the response:
{ "data": { "actor": { "entity": { "guid": "MTYwNjg2MnxOUjF8V09SS0xPQUR8MTIyMzQ", "workloadStatus": { "statusValue": "OPERATIONAL" } } } }}
Note that the DISRUPTED
status value is a synonym for CRITICAL
status.
Create a workload
The following is an example NerdGraph call that creates a workload using the workloadCreate
mutation query:
mutation { workloadCreate( accountId: NEW_WORKLOAD_ACCOUNT_ID, workload: { name: "NAME_OF_WORKLOAD", entityGuids: ["ENTITY_GUID_1", "ENTITY_GUID_2", ...], entitySearchQueries: [ { query: "(type = 'SERVICE') and tags.label.environment = 'production'" }, ... ], scopeAccounts: { accountIds: [NEW_RELIC_ACCOUNT_ID_1, NEW_RELIC_ACCOUNT_ID_2, ...] } } ) { guid }}
Some details on parts of this query:
account
: The workload account ID. Workloads can't be moved between accounts, so it's not possible to change this value later.name
: A string with a user-friendly name for the workload.scopeAccounts
: Scope accounts are the accounts where the entity data is fetched from. Scope accounts must belong to a group under the same parent account or enterprise partnership as the workload account.To define the entities in the workload, you can use one or both of these options:
entitySearchQueries
: This allows you to dynamically generate an array of entities. A name for each query is not needed. Here's an example dynamic query:(domain = 'INFRA' and type = 'HOST') and tags.label.environment = 'production'entityGuids
: This is for choosing specific entity GUIDs for inclusion in the workload.
guid
: This returns the workloadguid
. Because NerdGraph provides schema stitching, you can get other details about the workload, like thepermalink
.
Modify a workload
To modify a workload, use the workloadUpdate
mutation. You must know the workload's guid
.
The workload account can't be changed.
For the fields you can modify, see Create workloads. These additional rules apply:
entitySearchQueries
: This field must contain all the queries as you expect them to be stored. If you want to add a new query, include it in thequery
field and don't provide any queryid
. If you want to modify an existing query, include it in thequery
field and provide its existingid
. If you want to delete an existing query, just don't add any query with thatid
anymore.
Here's an example of the workloadUpdate
query:
mutation { workloadUpdate( guid: "YOUR_WORKLOAD_GUID", workload: { name: "A new name for the workload", entityGuids: ["ENTITY_GUID_1", "ENTITY_GUID_2", ...], entitySearchQueries: [ { query: "(domain = 'INFRA' and type = 'HOST') and tags.label.environment = 'staging'" }, { id: AN_EXISTING_QUERY_ID, query: "(type = 'SERVICE') and tags.label.environment = 'staging'" }, ... ], scopeAccounts: { accountIds: [NEW_RELIC_ACCOUNT_ID_1, NEW_RELIC_ACCOUNT_ID_2, ...] } } ) { guid }}
Set a static status for a workload
You can set up a static status for a workload, which overrides any automatic status calculation.
To set a static status, you must know the workload's guid
and use the following fields:
enabled
: Remember to set this field totrue
to propagate the status value.status
: The status value you want to set for this workload. Supported values areOPERATIONAL
,DEGRADED
orDISRUPTED
.description
: A text field to provide additional details.
mutation { workloadUpdate( guid: "YOUR_WORKLOAD_GUID", workload: { statusConfig: { static: { enabled: true, status: DEGRADED, description: "Game day. Expect some turbulence today between 8 and 9am PST." } } } ) { guid updatedAt status { value } }}
Modify the automatic status rules for a workload
When you create a workload, you can use the statusConfig
object to define which automatic rules you want to use to calculate the status of the workload. If you leave the rules
array empty, no rules will be set up for your workload.
However, if you just don't use the statusConfig
object when you create a workload, the following rules will be added by default:
"statusConfig": { "automatic": { "enabled": true, "rules": [ { "entitySearchQueries": [{"query": "(domain = 'APM' and type = 'APPLICATION')"}], "rollup": { "strategy": "WORST_STATUS_WINS", "thresholdType": null, "thresholdValue": null } }, { "entitySearchQueries": [{"query": "(domain = 'MOBILE' and type = 'APPLICATION')"}], "rollup": { "strategy": "WORST_STATUS_WINS", "thresholdType": null, "thresholdValue": null } }, { "entitySearchQueries": [{"query": "(domain = 'BROWSER' and type = 'APPLICATION')"}], "rollup": { "strategy": "WORST_STATUS_WINS", "thresholdType": null, "thresholdValue": null } }, { "entitySearchQueries": [{"query": "(domain = 'SYNTH' and type = 'MONITOR')"}], "rollup": { "strategy": "WORST_STATUS_WINS", "thresholdType": null, "thresholdValue": null } } ], "remainingEntitiesRule": { "rollup": { "groupBy": "ENTITY_TYPE", "strategy": "BEST_STATUS_WINS", "thresholdType": null, "thresholdValue": null } } }}
This is how you read the configuration:
enabled
: The automatic status calculation is enabled when this field is set totrue
.rules
: An array of rules. In the default configuration, four rules are set for those entity types that are closer to the digital experience (that is, synthetic monitors, browser applications, mobile applications, and services). For each of these groups, the status of the unhealthiest rolls up.remainingEntitiesRule
: This is the rule that will apply to all entities that haven't been evaluated in any other rule. In the default configuration, the remaining entities are grouped by entity type, and we make the status of each group to match that of its healthiest entity.
If you want to modify these rules, you must use the workloadUpdate
mutation, and send the complete new statusConfig
object that you want to use.
You can disable the automatic status calculation while keeping the configuration, by setting the statucConfig.automatic.enabled
to false
.
Alternatively, you can delete all automatic regular rules by sending an empty array. And you can delete the rule for the remaining entities by just not adding the remainingEntitiesRule
object.
Duplicate a workload
To duplicate a workload you first need to know its guid
. In the workloadDuplicate
mutation, you must pass as parameters:
accountId
: The account where you want to create the new workload.sourceGuid
: theguid
of the workload you want to duplicate.workload.name
: Optional. You can specify a name for the new workload. If you don't specify one, the new workload will get the name of the original workload appended with- Copy
.
After duplicating a workload, you can modify it.
mutation { workloadDuplicate( accountId: NEW_WORKLOAD_ACCOUNT_ID, sourceGuid: "ORIGINAL_WORKLOAD_GUID", workload: { name: "New workload" } ) { guid }}
Delete a workload
To delete a workload, use the workloadDelete
mutation and specify the workload GUID.
When you delete a workload, all history and metadata is also deleted.