NewRelic - Spotify for Backstage

NewRelic integration plugin for Soundcheck. It provides out-of-box integration with NewRelic by leveraging NewRelic’s NerdGraph API and implements collection of facts from NewRelic’s API’. The purpose of NewRelic Integration plugin is to provide NewRelic-specific fact collection (like entities, policies, SLAs). NewRelic’s integration plugin supports the collection of the following facts:

Entity
Entity Search
Policies Search

Prerequisites

Configure NewRelic integration in Backstage

Integrations are configured at the root level of app-config.yaml, here’s an example configuration for NewRelic:

soundcheck:
  collectors:
    newrelic:
      apiKey: apiKey

      # If you wish to override the api URL
      # baseUrl: https://api.newrelic.com

Follow the instructions for full details on configuration.

Add the NewRelicFactCollector to Soundcheck

First add the package:

yarn workspace backend add @spotify/backstage-plugin-soundcheck-backend-module-newrelic

Then add the following to your packages/backend/src/index.ts file:

packages/backend/src/index.ts

const backend = createBackend();

backend.add(import('@spotify/backstage-plugin-soundcheck-backend'));
backend.add(
  import('@spotify/backstage-plugin-soundcheck-backend-module-newrelic'),
);
// ...

backend.start();

Consult the Soundcheck Backend documentation for additional details on setting up the Soundcheck backend.

Plugin Configuration

Collection of facts is driven by config. To learn more about the config, see the Defining NewRelic Fact Collectors. NewRelic Fact Collector can be configured via YAML or No-Code UI. If you configure it via both YAML and No-Code UI, the configurations will be merged. It’s preferable to choose a single source for the Fact Collectors configuration (either No-Code UI or YAML) to avoid confusing merge results.

No-Code UI Configuration Option

Make sure the prerequisite Configure NewRelic integration in Backstage is completed and NewRelic instance details are configured.
To enable the NewRelic Integration, go to Soundcheck > Integrations > New Relic and click the Configure button. To learn more about the No-Code UI config, see the Configuring a fact collector (integration) via the no-code UI.

YAML Configuration Option

Create newrelic-facts-collectors.yaml in the root of your Backstage repository and fill in all your NewRelic fact collectors. A simple example NewRelic fact collector is listed below.

Note: this file will be loaded at runtime along with the rest of your Backstage configuration files, so make sure it’s available in deployed environments in the same way as your app-config.yaml files.

---
apiKey: dummy
collects:
  - type: entity
    filter:
      - spec.lifecycle: 'production'
        spec.type: 'website'
    cache: false

Add a soundcheck collectors field to app-config.yaml and reference the newly created newrelic-facts-collectors.yaml

# app-config.yaml
soundcheck:
  collectors:
    newrelic:
      $include: ./newrelic-facts-collectors.yaml

Rate Limiting (Optional)

This fact collector can be rate limited in Soundcheck using the following configuration:

soundcheck:
  job:
    workers:
      newrelic:
        limiter:
          max: 2000
          duration: 60000

In this example the fact collector is limited to 2000 executions per minute. This fact collector handles 429 rate limit errors from NewRelic. Soundcheck will automatically wait and retry requests that are rate limited.

Defining NewRelic Fact Collectors

This section describes the data shape and semantics of NewRelic Fact Collectors.

Overall Shape Of A NewRelic Fact Collector

The following is an example of a descriptor file for a NewRelic Fact Collector:

---
baseUrl: https://api.newrelic.com
apiKey: dummy
collects:
  - type: entity
    filter:
      - spec.lifecycle: 'production'
        spec.type: 'website'
    cache: false

See below for details about these fields.

`baseUrl` [optional]

The base URL of the NewRelic instance to use. If not provided, the plugin will attempt to use the default URL https://api.newrelic.com.

`apiKey` [optional]

The NewRelic apiKey to use for authentication.

`collects` [required]

An array describing which facts to collect and how to collect them. See below for details about the overall shape of a fact collector.

Overall Shape Of A Fact Collector

Each collector supports the fields described below.

`type` [required]

The type of the collector (e.g. entity, entity-search, policies-search).

`frequency` [optional]

The frequency at which the fact collection should be executed. Possible values are either a cron expression { cron: ... } or HumanDuration. If provided it overrides the default frequency provided at the top level. If not provided it defaults to the frequency provided at the top level. If neither collector’s frequency nor default frequency is provided the fact will only be collected on demand. Example:

frequency:
  minutes: 10

`initialDelay` [optional]

The amount of time that should pass before the first invocation happens. Possible values are either a cron expression { cron: ... } or HumanDuration. Example:

initialDelay:
  seconds: 30

`batchSize` [optional]

The number of entities to collect facts for at once. Optional, the default value is 1. Note: Fact collection for a batch of entities is still considered as one hit towards the rate limits by the Soundcheck Rate Limiting engine, while the actual number of hits will be equal to the batchSize. Example:

batchSize: 100

`filter` [optional]

A filter specifying which entities to collect the specified facts for. Matches the filter format used by the Catalog API. If provided it overrides the default filter provided at the top level. If not provided it defaults to the filter provided at the top level. If neither collector’s filter nor default filter is provided the fact will be collected for all entities. See filters for more details.

`exclude` [optional]

Entities matching this filter will be skipped during the fact collection process. Can be used in combination with filter. Matches the filter format used by the Catalog API.

filter:
  - kind: component
exclude:
  - spec.type: documentation

`cache` [optional]

If the collected facts should be cached, and if so for how long. Possible values are either true or false or a nested { duration: HumanDuration } field. If provided it overrides the default cache config provided at the top level. If not provided it defaults to the cache config provided at the top level. If neither collector’s cache nor default cache config is provided the fact will not be cached. Example:

cache:
  duration:
    hours: 24

Entity configuration

In your catalog-info.yaml add the following metadata annotation to allow the plugin to map an entity to an entity in NewRelic.

metadata:
  annotations:
  newrelic.com/tag: backstage:test-tag # Used in entity-search
  newrelic.com/account-id: '4338873' # Used in policies-search
  newrelic.com/entity-guid: NDMzODg3M3xFWFR8U0VSVklDRV9MRVZFTHw1Mjk2MjA # Used in entity

To lookup entity-guid on NewRelic go to All Entities, click on the entity, then click on Metadata and copy the guid.
To lookup account-id on NewRelic go to All Entities, click on the entity, then click on Metadata and copy the account id. Note that one organization can have multiple accounts and therefore multiple ids. Be sure copy the right one for the entity.
To tag an entity on NewRelic to All Entities, click on the entity, then click on Tags and add a tag. Note tags must be in key:value format, for example backstage:service-name.

Collecting Entity Fact

Entity fact contains information about entity from NewRelic NerdGraph Entity API. The query structure is shown below:

query ($guid: EntityGuid!) {
  actor {
    entity(guid: $guid) {
      name
      serviceLevel {
        indicators {
          id
          entityGuid
          name
          description
          objectives {
            name
            description
            target
            timeWindow {
              rolling {
                count
                unit
              }
            }
          }
        }
      }
      reporting
      alertSeverity
      domain
      entityType
      lastReportingChangeAt
      tags {
        key
        values
      }
      type
    }
  }
}

Shape of A Entity Fact Collector

The shape of a Entity Fact Collector matches the Overall Shape Of A NewRelic Fact Collector (restriction: type: entity). The following is an example of the Entity Fact Collector config:

collects:
  - type: entity
    cache: true
    frequency:
      cron: '0 * * * *'

Shape of A Entity Fact

The shape of a Entity Fact is based on the Fact Schema. For a description of the data collected regarding entities, refer to the NerdGraph query. The following is an example of the collected Entity Fact:

factRef: 'newrelic:default/entity'
entityRef: 'component:default/demo'
timestamp: '2024-02-08T18:36:13.712Z'
data:
  actor:
    entity:
      alertSeverity: NOT_ALERTING
      domain: EXT
      entityType: EXTERNAL_ENTITY
      lastReportingChangeAt: 1707247016423
      name: Test app - Latency
      reporting: true
      serviceLevel:
        indicators:
          - description: Proportion of requests that are served faster than a threshold.
            entityGuid: NDMzODg3M3xBUE18QVBQTElDQVRJT058NTUxMDcyNDUx
            id: '529620'
            name: Test app - Latency
            objectives:
              - description: null
                name: null
                target: 95
                timeWindow:
                  rolling:
                    count: 7
                    unit: DAY
      tags:
        - key: account
          values:
            - Account 4338873
        - key: accountId
          values:
            - '4338873'
        - key: category
          values:
            - latency
        - key: nr.associatedEntityGuid
          values:
            - NDMzODg3M3xBUE18QVBQTElDQVRJT058NTUxMDcyNDUx
        - key: nr.associatedEntityName
          values:
            - Test app
        - key: nr.associatedEntityType
          values:
            - APM_APPLICATION
        - key: nr.sliComplianceCategory
          values:
            - Compliant
        - key: nr.sloPeriod
          values:
            - 7d
        - key: nr.sloTarget
          values:
            - 95.0%
        - key: trustedAccountId
          values:
            - '4338873'
      type: SERVICE_LEVEL

Shape of A Entity Fact Check

The shape of an Entity Fact Check matches the Shape of a Fact Check. The following is an example of the Entity fact checks:

soundcheck:
  checks:
    - id: entity_is_reporting_to_newrelic
      description: Check if entity is reporting to NewRelic
      passedMessage: The check has passed!
      failedMessage: The check has failed!
      rule:
        factRef: newrelic:default/entity
        path: $.actor.entity.reporting
        operator: equal
        value: true

The following is an example of the Soundcheck track that utilizes these checks:

- id: demo
  name: Demo
  ownerEntityRef: group:default/owning_group
  description: Demonstration of Soundcheck Entity Fact Collector
  levels:
    - ordinal: 1
      name: First level
      description: Checks leveraging Soundcheck's NewRelic Entity Fact Collector
      checks:
        - id: entity_is_reporting_to_newrelic
          name: Checks if entity is reporting to NewRelic
          description: Checks if entity is reporting to NewRelic

The following is an example response from the Entity Fact collector.

{
  "actor": {
    "entity": {
      "alertSeverity": "NOT_CONFIGURED",
      "domain": "INFRA",
      "entityType": "INFRASTRUCTURE_HOST_ENTITY",
      "lastReportingChangeAt": 1710844262963,
      "name": "your-entity",
      "reporting": true,
      "serviceLevel": {
        "indicators": [
          {
            "id": "768657",
            "entityGuid": "your-enetity-guid",
            "name": "entity-name",
            "description": "your-decription",
            "objectives": {
              "name": "your-objective-name",
              "description": "your-decription",
              "target": "your-target",
              "timeWindow": {
                "rolling": {
                  "count": 1,
                  "unit": "DAY"
                }
              }
            }
          }
        ]
      },
      "tags": [
        { "key": "account", "values": ["Account your-ID"] },
        { "key": "accountId", "values": ["your-ID"] },
        { "key": "agentName", "values": ["Infrastructure"] },
        { "key": "agentVersion", "values": ["1.50.0"] },
        { "key": "your-tag-key", "values": [":your-tag-value"] },
        { "key": "coreCount", "values": ["8"] }
      ],
      "type": "HOST"
    }
  }
}

Collecting Entity Search Fact

An entity search fact contains information about entity search from NewRelic NerdGraph Entity Search API. The query structure is shown below:

query ($key: String!, $value: String!) {
  actor {
    entitySearch(queryBuilder: { tags: { key: $key, value: $value } }) {
      count
      query
      results {
        entities {
          alertSeverity
          name
          reporting
          entityType
          guid
        }
      }
    }
  }
}

Shape of A Entity Search Fact Collector

The shape of an Entity Search Fact Collector matches the Overall Shape Of A NewRelic Fact Collector (restriction: type: entity-search). The following is an example of the Entity Search Fact Collector config:

collects:
  - type: entity-search
    cache: true
    frequency:
      cron: '0 * * * *'

Shape of A Entity Search Fact

The shape of a Entity Search Fact is based on the Fact Schema. For a description of the data collected regarding entity search, refer to the NerdGraph query. The following is an example of the collected Entity Search Fact:

factRef: 'newrelic:default/entity-search'
entityRef: 'component:default/demo'
timestamp: '2024-02-08T18:36:13.712Z'
data:
  actor:
    entitySearch:
      count: 1
      query: tags.backstage = 'test-tag'
      results:
        entities:
          - alertSeverity: NOT_CONFIGURED
            entityType: APM_APPLICATION_ENTITY
            guid: NDMzODg3M3xBUE18QVBQTElDQVRJT058NTUxMDcyNDUx
            name: Test app
            reporting: true

Shape of A Entity Search Fact Check

The shape of a Entity Search Fact Check matches the Shape of a Fact Check. The following is an example of the Entity Search fact checks:

soundcheck:
  checks:
    - id: only_one_entity_with_tag_found
      description: Only one entity with tag should be found
      passedMessage: The check has passed!
      failedMessage: The check has failed!
      rule:
        factRef: newrelic:default/entity-search
        path: $.actor.entitySearch.count
        operator: equal
        value: 1
    - id: entity_is_reporting_to_newrelic
      description: Checks if entity is reporting to NewRelic
      passedMessage: The check has passed!
      failedMessage: The check has failed!
      rule:
        factRef: newrelic:default/entity-search
        path: $.actor.entitySearch.results.entities[0].reporting
        operator: equal
        value: true

The following is an example of the Soundcheck track that utilizes these checks:

- id: demo
  name: Demo
  ownerEntityRef: group:default/owning_group
  description: Demonstration of Soundcheck Entity Search Fact Collector
  levels:
    - ordinal: 1
      name: First level
      description: Checks leveraging Soundcheck's NewRelic Entity Search Fact Collector
      checks:
        - id: only_one_entity_with_tag_found
          name: Requires only one entity with the tag
          description: Requires only one entity with the tag
        - id: entity_is_reporting_to_newrelic
          name: Checks if entity is reporting to NewRelic
          description: Checks if entity is reporting to NewRelic

The following is an example response from the Entity Search Fact collector.

{
  "actor": {
    "entitySearch": {
      "count": 1,
      "query": "tags.`key` = ':value'",
      "results": {
        "entities": [
          {
            "alertSeverity": "NOT_CONFIGURED",
            "entityType": "INFRASTRUCTURE_HOST_ENTITY",
            "guid": "your-entity-guid",
            "name": "entity-name",
            "reporting": true
          }
        ]
      }
    }
  }
}

Collecting Policies Search Fact

A policies search fact contains information about policies search from NewRelic NerdGraph Policies Search API. The query structure is shown below:

query ($accountId: Int!) {
  actor {
    account(id: $accountId) {
      id
      alerts {
        policiesSearch {
          nextCursor
          policies {
            accountId
            id
            incidentPreference
            name
          }
          totalCount
        }
      }
    }
  }
}

Shape of A Policies Search Fact Collector

The shape of a Policies Search Fact Collector matches the Overall Shape Of A NewRelic Fact Collector (restriction: type: policies-search). The following is an example of the Policies Search Fact Collector config:

collects:
  - type: policies-search
    cache: true
    frequency:
      cron: '0 * * * *'

Shape of A Policies Search Fact

The shape of a Policies Search Fact is based on the Fact Schema. For a description of the data collected regarding policies search, refer to the NerdGraph query. The following is an example of the collected Policies Search Fact:

factRef: 'newrelic:default/policies-search'
entityRef: 'component:default/demo'
timestamp: '2024-02-08T18:17:59.048Z'
data:
  actor:
    account:
      alerts:
        policiesSearch:
          nextCursor: null
          policies:
            - accountId: 4338873
              id: '5079003'
              incidentPreference: PER_POLICY
              name: Test policy
            - accountId: 4338873
              id: '5081741'
              incidentPreference: PER_POLICY
              name: Service Levels default policy for account 4338873
          totalCount: 2
      id: 4338873

Shape of A Policies Search Fact Check

The shape of a Policies Search Fact Check matches the Shape of a Fact Check. The following is an example of the Policies Search fact checks:

soundcheck:
  checks:
    - id: requires_at_least_one_policy
      description: Requires at least one policy to exist
      passedMessage: The check has passed!
      failedMessage: The check has failed!
      rule:
        factRef: newrelic:default/policies-search
        path: $.actor.account.alerts.policiesSearch.totalCount
        operator: greaterThanInclusive
        value: 1

The following is an example of the Soundcheck track that utilizes these checks:

- id: demo
  name: Demo
  ownerEntityRef: group:default/owning_group
  description: Demonstration of Soundcheck Policies Search Fact Collector
  levels:
    - ordinal: 1
      name: First level
      description: Checks leveraging Soundcheck's NewRelic Policies Search Fact Collector
      checks:
        - id: requires_at_least_one_policy
          name: Requires at least one policy to be configured
          description: Requires at least one policy to be configured for the account id

The following is an example response from the Policies Search Fact collector.

{
  "actor": {
    "account": {
      "alerts": {
        "policiesSearch": {
          "nextCursor": null,
          "policies": [
            {
              "accountId": 2873416,
              "id": "17924371",
              "incidentPreference": "PER_POLICY",
              "name": "Initial policy"
            }
          ],
          "totalCount": 1
        }
      }
    },
    "id": 4393509
  }
}

Shape of A NewRelic Track

The following is an example of the Soundcheck track that utilizes these checks

soundcheck:
  tracks:
    - id: demo
      name: Demo
      ownerEntityRef: group:default/owning_group
      description: Demonstration of Soundcheck NewRelic Fact Collector
      levels:
        - ordinal: 1
          name: First level
          description: Checks leveraging SoundCheck's NewRelic Fact Collector
          checks:
            - id: requires_at_least_one_policy
              name: Requires at least one policy to be configured
              description: Requires at least one policy to be configured for the account id
            - id: only_one_entity_with_tag_found
              name: Requires only one entity with the tag
              description: Requires only one entity with the tag
            - id: entity_is_reporting_to_newrelic
              name: Checks if entity is reporting to NewRelic
              description: Checks if entity is reporting to NewRelic
            - id: entity_is_reporting_to_newrelic
              name: Checks if entity is reporting to NewRelic
              description: Checks if entity is reporting to NewRelic
      filter:
        catalog:
          metadata.tags: some-tag

​Prerequisites

​Configure NewRelic integration in Backstage

​Add the NewRelicFactCollector to Soundcheck

​Plugin Configuration

​No-Code UI Configuration Option

​YAML Configuration Option

​Rate Limiting (Optional)

​Defining NewRelic Fact Collectors

​Overall Shape Of A NewRelic Fact Collector

​baseUrl [optional]

​apiKey [optional]

​collects [required]

​Overall Shape Of A Fact Collector

​type [required]

​frequency [optional]

​initialDelay [optional]

​batchSize [optional]

​filter [optional]

​exclude [optional]

​cache [optional]

​Entity configuration

​Collecting Entity Fact

​Shape of A Entity Fact Collector

​Shape of A Entity Fact

​Shape of A Entity Fact Check

​Collecting Entity Search Fact

​Shape of A Entity Search Fact Collector

​Shape of A Entity Search Fact

​Shape of A Entity Search Fact Check

​Collecting Policies Search Fact

​Shape of A Policies Search Fact Collector

​Shape of A Policies Search Fact

​Shape of A Policies Search Fact Check

​Shape of A NewRelic Track

Prerequisites

Configure NewRelic integration in Backstage

Add the NewRelicFactCollector to Soundcheck

Plugin Configuration

No-Code UI Configuration Option

YAML Configuration Option

Rate Limiting (Optional)

Defining NewRelic Fact Collectors

Overall Shape Of A NewRelic Fact Collector

`baseUrl` [optional]

`apiKey` [optional]

`collects` [required]

Overall Shape Of A Fact Collector

`type` [required]

`frequency` [optional]

`initialDelay` [optional]

`batchSize` [optional]

`filter` [optional]

`exclude` [optional]

`cache` [optional]

Entity configuration

Collecting Entity Fact

Shape of A Entity Fact Collector

Shape of A Entity Fact

Shape of A Entity Fact Check

Collecting Entity Search Fact

Shape of A Entity Search Fact Collector

Shape of A Entity Search Fact

Shape of A Entity Search Fact Check

Collecting Policies Search Fact

Shape of A Policies Search Fact Collector

Shape of A Policies Search Fact

Shape of A Policies Search Fact Check

Shape of A NewRelic Track