NerdGraph workloads API tutorials

BETA

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:

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, you can use the following GraphQL query​ and pass the account ID via the id field. In this example, we’re retrieving three basic fields:

  • guid: the workload GUID.
  • name: the workload name.
  • permalink: the permanent URLs on the New Relic One UI.
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      workload {
        collections {
          guid
          name
          permalink
        }
      }
    }
  }
}

The response includes data like the following for each workload:

{
  "data": {
    "actor": {
      "account": {
        "workload": {
          "collections": [
            ...,
              "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 need to follow a two-step procedure to get the workload entities: first you get the entity query associated with the workload, and then you use this query with the Entity Search service.

1. Get the entity query associated with the workload.

The workload entities are defined by a query. You can execute the following API call to get this 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 {
    account(id: YOUR_ACCOUNT_ID) {
      workload {
        collection(guid: "MTY...NTY") {
          guid
          entitySearchQuery
        }
      }
    }
  }
}

The entitySearchQuery field returns the query that provides the workload entity list. The query may include a combination of GUIDs for some entities that have been specifically added to the workload, as well as search expressions that are evaluated in query time. This last part is what makes the workload content dynamic.

The response will look like the following.

{
  {
    "data": {
      "actor": {
        "account": {
          "workload": {
            "collection": {
              "entitySearchQuery": "(accountId IN ('1606862',...)) AND (`tags.account` = 'Demotron V2' and `tags.Chain` = 'Fulfillment') OR (`tags.account` = 'Demotron V2' and `tags.label.Chain` = 'Fulfillment'))",
              "guid": "MTY...NTY"
            }
          }
        }
      }
    },
 "extensions": { ... }
}

Next you will send the query in entitySearchQuery to the Entity Search service to get the detailed workload contents, as explained in the following step.

2. Use the entity query in the Entity Search service

Now, use the content of the entitySearchQuery field with the entitySearch call. The following example asks for:

  • count: the total number of entities in the workload.
  • The unique identifier, type, and name for each resulting entity.
{
  actor {
    entitySearch(query: "(accountId IN ('YOUR_ACCOUNT_ID',...)) AND (`tags.account` = 'Demotron V2' and `tags.Chain` = 'Fulfillment') OR (`tags.account` = 'Demotron V2' and `tags.label.Chain` = 'Fulfillment'))") {
      count
      results {
        entities {
          guid
          entityType
          name
        }
      }
    }
  }
}

The call will return a list of entities that looks like this:

{
  "data": {
    "actor": {
      "entitySearch": {
        "count": 49,
        "results": {
          "entities": [
            ...,
            {
              "entityType": "INFRASTRUCTURE_HOST_ENTITY",
              "guid": "ABC...BCd",
              "name": "host-proxy-west-5"
            },
            {
              "entityType": "APM_APPLICATION_ENTITY",
              "guid": "ABD...ACd",
              "name": "WebPortal"
            },
            {
              "entityType": "BROWSER_APPLICATION_ENTITY",
              "guid": "ABB...ACe",
              "name": "WebPortal"
            },
            {
              "entityType": "GENERIC_INFRASTRUCTURE_ENTITY",
              "guid": "ABC...1Ce",
              "name": "webportal.dt.nrdemo-staging.com."
            },
            ...
          ]
        }
      }
    }
  },
  "extensions": { ... }
}

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: Accounts where the entity data will be fetched from.
  • 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
  }
}

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.

Recommendations for learning more: