• /
  • Log in
  • Free account

NerdGraph tutorial: Configure anomaly detection

Automated anomaly detection at New Relic starts with an anomaly detector: a way to systematically observe and record anomalies in a specific dataset. To name and configure the dataset, you'll need to create an anomaly detector configuration, which is a set of fields that tells us the signals you're interested in watching and where to store anomalous data.

BETA FEATURE

This feature is still in development, but we encourage you to try it out!

There are three different types of configurations that correspond to different ways of creating a dataset to watch. A workload configuration creates a detector using all the entities contained in the workload as the dataset. An entity type configuration uses all the entities of a single entity type (for example, mobile apps) in one or more accounts as the dataset. A NRQL configuration uses the results from one or more NRQL queries as the dataset.

You can manage your anomaly detector configuration with our NerdGraph API, which includes use of our GraphiQL interface at api.newrelic.com/graphiql.

Here are a few examples to get you started:

Create a configuration

The following is an example NerdGraph mutation that creates a configuration using an existing workload:

mutation {
  anomalyDetectorConfigurationsWorkloadAnomalyDetectorCreate(
    workloadGuid: "WORKLOAD_GUID",
    anomalyDetector: {
      name: "NAME_OF_CONFIGURATION",
      excludedEntityGuids: ["ENTITY_GUID_1", "ENTITY_GUID_2", ...]
    }
  )
  {
    anomalyDetectorId
  }
}

Some details about this mutation:

  • workloadGuid: The workload guid used to define the dataset. Anomalies will be detected based on golden signals from all entities (unless specified in excludedEntityGuids) within this workload. Anomalous data will be stored in the account associated with this workload. The workload is not editable later.
  • anomalyDetector.name: A string with a user-friendly name to describe the configuration.
  • anomalyDetector.excludedEntityGuids: Optional. This field allows you to exclude some entities from the dataset without removing them from the workload. This is useful if you have an existing workload that you want to use for anomaly detection.

The following is an example mutation that creates a configuration using an entity type:

mutation {
  anomalyDetectorConfigurationsEntityTypeAnomalyDetectorCreate(
    accountId: ACCOUNT_ID,
    anomalyDetector: {
      name: "NAME_OF_CONFIGURATION",
      domainType: {
        domain: "ENTITY_DOMAIN",
        type: "ENTITY_TYPE"
      },
      includedEntityGuids: ["ENTITY_GUID_1", "ENTITY_GUID_2", ...],
      additionalSourceAccountIds: [ADDITIONAL_SOURCE_ACCOUNT_ID_1, ADDITIONAL_SOURCE_ACCOUNT_ID_2, ...]
    }
  )
  {
    anomalyDetectorId
  }
}

Some details about this mutation:

  • accountId: The accountId used to store anomalous data and to determine entities for the dataset. This account is not editable later.
  • anomalyDetector.name: A string with a user-friendly name to describe the configuration.
  • anomalyDetector.domainType:
  • domain: A string representing an entity domain.
  • type: A string representing an entity type.
  • anomalyDetector.includedEntityGuids: Optional. This field allows you to include some entities in the dataset without adding all of them from the account(s). This is useful if you have only a few entities of the same type you want to use for anomaly detection, or you would like a static dataset. The default is to use all entities within the entity type, which may change over time.
  • anomalyDetector.additionalSourceAccountIds: Optional. This field allows you to include entities from more than one account in the dataset. These accounts are editable later.

The following is an example mutation that creates a configuration using the results of a NRQL query:

NRQL Validation

Not all NRQL features are supported by anomaly detection. To avoid invalid nrql errors, run your signal's NRQL through the validation mutation first.

mutation {
  anomalyDetectorConfigurationsNrqlAnomalyDetectorCreate(
    accountId: ACCOUNT_ID,
    anomalyDetector: {
      name: "NAME_OF_CONFIGURATION",
      nrqlSignals: [
        {
          accountId: NRQL_QUERY_ACCOUNT_ID,
          name: "NAME_OF_NRQL_SIGNAL",
          nrql: "NRQL_QUERY",
          mutedFacetValues: ["FACET_VALUE_1", "FACET_VALUE_2", ...]
        }
      ]
    }
  )
  {
    anomalyDetectorId
  }
}

Some details about this mutation:

  • accountId: The accountId used to store anomalous data. This account is editable later.
  • anomalyDetector.name: A string with a user-friendly name to describe the configuration.
  • anomalyDetector.nrqlSignals: A list of signals defined by custom NRQL queries.
  • accountId: The accountId being queried.
  • name: A string with a user-friendly name to describe the signal. For example: "Throughput", "ErrorRate", etc.
  • nrql: A NRQL query. Anomaly detection does not currently support all NRQL features. You can use our validation mutation to verify your NRQL query is fully supported before creating a configuration.
  • mutedFacetValues: Optional. This field allows you to exclude some facet values from resulting dataset.

Update a configuration

The following is an example mutation that updates a workload configuration:

mutation {
  anomalyDetectorConfigurationsWorkloadAnomalyDetectorUpdate(
    anomalyDetectorId: DETECTOR_ID,
    anomalyDetector: {
      name: "UPDATED_DETECTOR_NAME",
      status: DETECTOR_STATUS,
      deviationSensitivity: DEVIATION_SENSITIVITY,
      excludedEntityGuids: ["ENTITY_GUID_1", "ENTITY_GUID_2", ...],
      thresholds: [THRESHOLD_SIGNAL_1, THRESHOLD_SIGNAL_2, ...]
    }
  ) {
    anomalyDetectorId
  }
}

Some details about this mutation:

  • anomalyDetectorId: The detector's unique identifier.
  • anomalyDetector.name: Optional. A string with a user-friendly name to describe the configuration.
  • anomalyDetector.status: Optional. The status defaults to ACTIVE. If you do not want the detector to produce anomalies, you can set this field to INACTIVE.
  • anomalyDetector.deviationSensitivity: Optional. The sensitivity level for determining what data is anomalous. This field defaults to LOW, recording only the most significant anomalies. If you would like more sensitivity you can set this field to MEDIUM or HIGH.
  • anomalyDetector.excludedEntityGuids: Optional. This field allows you to exclude some entities from the dataset without removing them from the workload. This is useful if you have an existing workload that you want to use for anomaly detection. If you would like to clear any existing excludedEntityGuids, pass an empty array [].
  • anomalyDetector.thresholds: Optional. See the section on thresholds for more information.

The following is an example mutation that updates an entity type configuration:

mutation {
  anomalyDetectorConfigurationsEntityTypeAnomalyDetectorUpdate(
    anomalyDetectorId: DETECTOR_ID,
    anomalyDetector: {
      name: "UPDATED_DETECTOR_NAME",
      status: DETECTOR_STATUS,
      deviationSensitivity: DEVIATION_SENSITIVITY,
      includedEntityGuids: ["ENTITY_GUID_1", "ENTITY_GUID_2", ...],
      additionalSourceAccountIds: [ADDITIONAL_SOURCE_ACCOUNT_ID_1, ADDITIONAL_SOURCE_ACCOUNT_ID_2, ...],
      thresholds: [THRESHOLD_SIGNAL_1, THRESHOLD_SIGNAL_2, ...]
    }
  )
  {
    anomalyDetectorId
  }
}

Some details about this mutation:

  • anomalyDetectorId: The detector's unique identifier.
  • anomalyDetector.name: Optional. A string with a user-friendly name to describe the configuration.
  • anomalyDetector.status: Optional. The status defaults to ACTIVE. If you do not want the detector to produce anomalies, you can set this field to INACTIVE.
  • anomalyDetector.deviationSensitivity: Optional. The sensitivity level for determining what data is anomalous. This field defaults to LOW, recording only the most significant anomalies. If you would like more sensitivity you can set this field to MEDIUM or HIGH.
  • anomalyDetector.includedEntityGuids: Optional. This field allows you to include some entities from the entity type instead of all adding all of them from the account(s). This is useful if you have only a few entities of the same type you want to use for anomaly detection. If you would like to use all entities within the type, pass an empty array [].
  • anomalyDetector.additionalSourceAccountIds: Optional. This field allows you to include entities from more than one account in the dataset.
  • anomalyDetector.thresholds: Optional. See the section on thresholds for more information.

The following is an example mutation that updates a NRQL configuration:

mutation {
  anomalyDetectorConfigurationsNrqlAnomalyDetectorUpdate(
    anomalyDetectorId: DETECTOR_ID,
    accountId: ACCOUNT_ID,
    anomalyDetector: {
      name: "UPDATED_CONFIGURATION_NAME",
      status: DETECTOR_STATUS,
      deviationSensitivity: DEVIATION_SENSITIVITY,
      newSignals: [
        {
          accountId: NRQL_QUERY_ACCOUNT_ID,
          name: "NAME_OF_NRQL_SIGNAL",
          nrql: "NRQL_QUERY",
          mutedFacetValues: ["FACET_VALUE_1", "FACET_VALUE_2", ...]
        }
      ],
      updatedSignals: [
        {
          queryId: QUERY_ID,
          name: "UPDATED_NAME_OF_NRQL_SIGNAL",
          mutedFacetValues: ["FACET_VALUE_1", "FACET_VALUE_2", ...],
          threshold: THRESHOLD
        }
      ],
      deletedQueries: [QUERY_ID_1, QUERY_ID_2]
    }
  )
  {
    anomalyDetectorId
  }
}

Some details about this mutation:

  • anomalyDetectorId: The detector's unique identifier.
  • accountId: Optional. The accountId used to store anomalous data.
  • anomalyDetector.name: Optional. A string with a user-friendly name to describe the configuration.
  • anomalyDetector.status: Optional. The status defaults to ACTIVE. If you do not want the detector to produce anomalies, you can set this field to INACTIVE.
  • anomalyDetector.deviationSensitivity: Optional. The sensitivity level for determining what data is anomalous. This field defaults to LOW, recording only the most significant anomalies. If you would like more sensitivity you can set this field to MEDIUM or HIGH.
  • anomalyDetector.newSignals: Optional. A list of signals to add to the detector.
  • accountId: The accountId being queried.
  • name: A string with a user-friendly name to describe the signal. For example: "Throughput", "ErrorRate", etc.
  • nrql: A NRQL query. Anomaly detection does not currently support all NRQL features. You can use our validation mutation to verify your NRQL query is fully supported before creating a configuration.
  • mutedFacetValues: Optional. This field allows you to exclude some facet values from resulting dataset.
  • anomalyDetector.updatedSignals: Optional. A list of signals with changes.
  • queryId: An unique signal query identifier.
  • name: Optional. A string with a user-friendly name to describe the signal. For example: "Throughput", "ErrorRate", etc.
  • mutedFacetValues: Optional. This field allows you to exclude some facet values from resulting dataset.
  • threshold: Optional. See the section on thresholds for more information.
  • anomalyDetector.deletedQueries: Optional. A list of unique signal query identifiers to remove from the detector.

Delete a configuration

The following is an example mutation that deletes any kind of configuration:

mutation {
  anomalyDetectorConfigurationsAnomalyDetectorDelete(
    anomalyDetectorId: DETECTOR_ID
  )
  {
    success
  }
}

Some details about this mutation:

  • anomalyDetectorId: The detector's unique identifier.

Query your anomaly detector configurations

The following is an example mutation that returns all configurations you have access to:

{
actor {
anomalyDetectorConfigurations {
anomalyDetectors {
id
name
... on AnomalyDetectorConfigurationsWorkloadAnomalyDetector {
workloadGuid {
guid
}
}
... on AnomalyDetectorConfigurationsEntityTypeAnomalyDetector {
domainType {
domain
type
}
}
... on AnomalyDetectorConfigurationsNrqlAnomalyDetector {
nrqlSignals {
name
}
}
}
}
}
}

A simplified query can be used when you're interested in fields accessible on all types of configurations:

{
actor {
anomalyDetectorConfigurations {
anomalyDetectors {
id
name
}
}
}
}

If you would like to retrieve one or more specific configurations, pass a filter containing unique identifiers to the previous query like so:

{
  actor {
    anomalyDetectorConfigurations {
      anomalyDetectors(filters: {anomalyDetectorIds: [ANOMALY_DETECTOR_ID_1, ANOMALY_DETECTOR_ID_2, ...]}) {
        id
        name
      }
    }
  }
}

Some details on parts of this query:

  • filters: Optional.
  • filters.anomalyDetectorIds: Optional. A list of unique anomaly detector identifiers.

Visit the QraphiQL explorer to see more queryable fields.

Query default thresholds

The following is an example query that returns the current default thresholds:

{
actor {
anomalyDetectorConfigurations {
anomalyDetectorThresholds {
signalName
domainType {
domain
type
}
deviationSensitivity
upperLimit {
active
value
}
upperRelativePercent {
active
value
}
significantDeviationDirection
lowerRelativePercent {
value
active
}
lowerLimit {
active
value
}
}
}
}
}

Some details about this query:

  • signalName: A string representing either a global threshold, named globalDefault, or a signal threshold (for example, "throughput," "errorRate," etc)
  • domainType: The global threshold does not have a domain type.

If you would like to filter the threshold values to one or more domainTypes, pass a filter to the previous query like so:

{
  actor {
    anomalyDetectorConfigurations {
      anomalyDetectorThresholds(filters: {
        domainTypes: [
          {
            domain: "ENTITY_DOMAIN",
            type: "ENTITY_TYPE"
          }
        ]
      }
      )
      {
        signalName
      }
    }
  }
}

Some details on parts of this query:

  • domainType.domain: A string representing an entity domain.
  • domainType.type: A string representing an entity type.

Validate a custom NRQL signal

This is useful only when creating a NRQL based anomaly detector. Anomaly detection does not support all NRQL features. To avoid errors on creation, you can first validate the NRQL queries you plan to use. If your query is not valid, we will provide a list of reasons why. An empty list indicates your query is valid.

The following is an example mutation that validates a NRQL query is fully supported by anomaly detection:

mutation {
  anomalyDetectorConfigurationsValidateNrqlSignal(
    accountId: ACCOUNT_ID,
    nrql: "NRQL"
  ) {
    invalidNrqlReasons
  }
}

Some details about this mutation:

  • accountId: The accountId being queried.
  • nrql: A NRQL query.

Reasons your query may be invalid:

  • CASES_NOT_SUPPORTED - Cases are not supported.
  • COMPARE_WITH_NOT_SUPPORTED - The COMPARE WITH clause is not supported.
  • COULDNT_COMPLETE_QUERY - The query returned too much data for anomaly detection to support.
  • DAQS_NOT_ALLOWED - The query is not supported by DAQS.
  • INVALID_NRQL - The query is invalid.
  • LIMIT_NOT_SUPPORTED - The LIMIT clause is not supported.
  • MISSING_FACET - The query is missing a facet value.
  • MULTIPLE_FACET_NOT_SUPPORTED - Multiple facet attributes per query is not supported.
  • MULTISELECT_NOT_SUPPORTED - Multiple SELECT clauses are not supported.
  • NON_NUMERIC_AGGREGATE_NOT_SUPPORTED - Queries that return non numeric values are not supported.
  • NOT_AUTHORIZED - The user does not have access the provided account.
  • SINCE_NOT_SUPPORTED - The SINCE clause is not supported.
  • TIMESERIES_NOT_SUPPORTED - The TIMESERIES clause is not supported.
  • TOO_MANY_FACET_VALUES - The query has surpassed the anomaly detection facet limit.
  • UNTIL_NOT_SUPPORTED - The UNTIL clause is not supported.

Anomaly detector thresholds

A threshold is a group of settings representing the upper &/or lower boundaries that indicate when a signal is considered anomalous. When anomaly detector configurations are created, they start using the default settings suitable for most detectors.

Querying thresholds

There are two types of default values, a single global threshold and signal thresholds. When querying thresholds associated with an anomaly detector, a null value within a WorkloadAnomalyDetector or EntityTypeAnomalyDetector indicates a signal default value is being used.

A null value within a NrqlAnomalyDetector indicates the global default value is being used. These default values are subject to change over time - use our thresholds query to get the most recent default values.

Updating thresholds

You may make changes to thresholds in any configuration edit mutation. Workload and entity type configurations have a list of thresholds, one per golden signal per entity type (workloads can contain multiple entity types).

NRQL configurations have a single threshold per custom signal. The following is an example THRESHOLD object used for updating threshold values in any update mutation.

{
  signalName: "SIGNAL_NAME",
  domainType: {
    domain: "ENTITY_DOMAIN",
    type: "ENTITY_TYPE"
  },
  deviationSensitivity: DEVIATION_SENSITIVITY,
  significantDeviationDirection: SIGNIFICANT_DEVIATION_DIRECTION,
  upperLimit: {
    value: LIMIT_VALUE,
    active: STATUS
  },
  upperRelativePercent: {
    value: PERCENT_VALUE,
    active: STATUS
  },
  lowerLimit: {
    value: LIMIT_VALUE,
    active: STATUS
  },
  lowerRelativePercent: {
    value: PERCENT_VALUE,
    active: STATUS
  }
}

Some details on this type:

  • signalName: The signal name. For nrql configurations, this name must match nrqlSignal.name.
  • domainType: This will be null for custom NRQL signals.
  • domain: A string representing an entity domain.
  • type: A string representing an entity type.
  • deviationSensitivity: Optional. The sensitivity level for determining what data is anomalous. The value options are:
  • NONE - No anomalies.
  • LOW - Fewer anomalies. For example, you may decide the cpu usage for your host is producing too many anomalies and you would like less.
  • MEDIUM - Some anomalies.
  • HIGH - More anomalies. For example, you may decide the error rate for your service is producing too few anomalies and you would like more.
  • significantDeviationDirection: Optional. The significant direction for determining which direction of change is relevant to a signal. The value options are:
  • HIGHER - Anomalous when relative change is higher. For example, you may decide that an error rate for your service is only anomalous when it goes up.
  • HIGHER_LOWER - Anomalous when relative change is higher OR lower.
  • LOWER - Anomalous when relative change is lower. For example, you may decide that throughput for your service is only anomalous when it goes down.
  • upperLimit: Optional. A static upper limit. Any value above this limit value will be considered anomalous when the significant deviation direction is HIGHER or HIGHER_LOWER.
  • value: Optional. A numeric value.
  • active: Optional. True or false.
  • upperRelativePercent: Optional. Any relative percent change higher than this percent value will be considered anomalous when the significant deviation direction is HIGHER or HIGHER_LOWER.
  • value: Optional. A numeric value.
  • active: Optional. True or false.
  • lowerLimit: Optional. A static lower limit. Any value below this limit value will be considered anomalous when the significant deviation direction is LOWER or HIGHER_LOWER.
  • value: Optional. A numeric value.
  • active: Optional. True or false.
  • lowerRelativePercent: Optional. Any relative percent change lower than this percent value will be considered anomalous when the significant deviation direction is LOWER or HIGHER_LOWER.
  • value: Optional. A numeric value.
  • active: Optional. True or false.
Create issueEdit page
Copyright © 2022 New Relic Inc.