--- title: NerdGraph tutorial: View and manage workloads source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-workloads-api-tutorials --- New Relic allows you to group entities together in groupings called [workloads]((/docs/new-relic-solutions/new-relic-one/workloads/workloads-isolate-resolve-alert-events-faster)). This enables better monitoring of the full stack used by a team or project. Here we show you how to use our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph) to do some workloads-related tasks: - [Get the workloads of an account](#get_workloads) - [Get the list of entities in a workload](#get_entities_list) - [Get the status of a workload](#get_status) - [Create a workload](#create-workload) - [Modify a workload](#modify) - [Set a static status for a workload](#static) - [Modify the automatic status rules for a workload](#automatic) - [Duplicate a workload](#duplicate) - [Delete a workload](#delete) See also [our post on how to customize the charts you see in your workload](https://support.newrelic.com/s/hubtopic/aAX8W0000008c8P/how-to-customize-the-charts-you-see-on-a-workload). > #### ⚠️ IMPORTANT > > You can also use the [CLI](http://developer.newrelic.com/build-tools/new-relic-one-applications/cli) and [Terraform resource](https://www.terraform.io/docs/providers/newrelic/r/workload) to automate these tasks. ## Get the workloads of an account [#get_workloads] To get all workloads of an account, use the following [GraphQL query](https://api.newrelic.com/graphiql) 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. ```graphql { 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: ```json { "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 [#get_entities_list] 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](#get_status) 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. ```graphql { 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: ```json { "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 [#get_status] 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. ```graphql { actor { entity(guid: "YOUR_WORKLOAD_GUID") { ... on WorkloadEntity { guid workloadStatus { statusValue } } } } } ``` And this is what you'll get in the response: ```json { "data": { "actor": { "entity": { "guid": "MTYwNjg2MnxOUjF8V09SS0xPQUR8MTIyMzQ", "workloadStatus": { "statusValue": "OPERATIONAL" } } } } } ``` Note that the `DISRUPTED` status value is a synonym for `CRITICAL` status. ## Create a workload [#create-workload] The following is an example NerdGraph call that creates a workload using the `workloadCreate` [mutation](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph#terminology) query: ```graphql 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]((/docs/new-relic-solutions/new-relic-one/workloads/workloads-isolate-resolve-alert-events-faster)#workload-account). 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]((/docs/new-relic-solutions/new-relic-one/workloads/workloads-isolate-resolve-alert-events-faster)#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]((/docs/new-relic-solutions/new-relic-one/workloads/workloads-isolate-resolve-alert-events-faster)#dynamic). 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 [#modify] 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](#create-workload-fields). 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: ```graphql 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 [#static] 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. ```graphql 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 [#automatic] 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: ```json { "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 [#duplicate] 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](#modify). ```graphql mutation { workloadDuplicate( accountId: NEW_WORKLOAD_ACCOUNT_ID, sourceGuid: "ORIGINAL_WORKLOAD_GUID", workload: { name: "New workload" } ) { guid } } ``` ## Delete a workload [#delete] 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.