NerdGraph tutorial: View and manage workloads

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

重要

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 and results objects, which contain the actual list of entities:
- The name argument in the collection object takes the value WORKLOAD.
- count: Number of entities in the workload.

{
  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 workload guid. Because NerdGraph provides schema stitching, you can get other details about the workload, like the permalink.

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 the query field and don't provide any query id. If you want to modify an existing query, include it in the query field and provide its existing id. If you want to delete an existing query, just don't add any query with that id 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 to true to propagate the status value.
status: The status value you want to set for this workload. Supported values are OPERATIONAL, DEGRADED or DISRUPTED.
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 to true.
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: the guid 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.