Create a quickstart

Lab

This procedure is a part of lab that teaches you how to build quickstart. If you haven't already, checkout the lab introduction

As this procedure builds on top of the last ones in the lab, make sure you create a dashboard and alerts before proceeding with this one.

With quickstarts, you can quickly and easily observe and monitor your services since they include observability building blocks like dashboards and alerts. You've already created a useful dashboard and alert policy for your database. Now, you can package them into a quickstart and contribute it to New Relic I/O as a benefit to your users.

To get started, navigate to GitHub repository of New Relic quickstarts and fork it.

fork github quickstart repo

Now, clone your own repository to your local machine using git clone and open it in the IDE of your choice.

Notice the directory structure. The _template folder is of special importance since it contains the templates for observability building blocks in the quickstart.

quickstart template

The _template directory contains the folders for dashboards and alerts. Each of these folders contain templates that you can use to create entities for your quickstart.

Copy the _template directory and it's content to a new directory within the quickstarts folder. Name the directory as flashdb.

flashdb quickstart directory

Add your dashboard to the quickstart

In a previous procedure, you created a dashboard for monitoring FlashDB. Now, you add it to your quickstart so your users can use it too.

First, look up your dashboard in New Relic and copy its JSON. Then, save it as a JSON file in the dashboards directory.

copy flashdb dashboard

Here, you copied your dashboard's JSON to clipboard. Replace the content of existing JSON file in dashboards directory and rename it as flashDB.json. Your flashDB.json file should contain the following content:

{
  "name": "FlashDB",
  "description": null,
  "permissions": "PUBLIC_READ_WRITE",
  "pages": [
    {
      "name": "FlashDB",
      "description": null,
      "widgets": [
        {
          "visualization": {
            "id": "viz.pie"
          },
          "layout": {
            "column": 1,
            "row": 1,
            "height": 6,
            "width": 8
          },
          "title": "Database methods",
          "rawConfiguration": {
            "facet": {
              "showOtherSeries": true
            },
            "nrqlQueries": [
              {
                "accountId": 3248695,
                "query": "SELECT count(*) FROM fdb_method FACET method"
              }
            ]
          },
          "linkedEntityGuids": null
        },
        {
          "visualization": {
            "id": "viz.billboard"
          },
          "layout": {
            "column": 9,
            "row": 1,
            "height": 3,
            "width": 4
          },
          "title": "Database size",
          "rawConfiguration": {
            "dataFormatters": [],
            "nrqlQueries": [
              {
                "accountId": 3248695,
                "query": "SELECT latest(fdb_size) FROM Metric"
              }
            ],
            "thresholds": []
          },
          "linkedEntityGuids": null
        },
        {
          "visualization": {
            "id": "viz.line"
          },
          "layout": {
            "column": 9,
            "row": 4,
            "height": 3,
            "width": 4
          },
          "title": "Average Response Time",
          "rawConfiguration": {
            "legend": {
              "enabled": true
            },
            "nrqlQueries": [
              {
                "accountId": 3248695,
                "query": "SELECT average(fdb_create_responses), average(fdb_read_responses), average(fdb_update_responses), average(fdb_delete_responses) FROM Metric TIMESERIES"
              }
            ],
            "yAxisLeft": {
              "zero": true
            }
          },
          "linkedEntityGuids": null
        },
        {
          "visualization": {
            "id": "viz.line"
          },
          "layout": {
            "column": 1,
            "row": 7,
            "height": 3,
            "width": 4
          },
          "title": "Cache hits",
          "rawConfiguration": {
            "legend": {
              "enabled": true
            },
            "nrqlQueries": [
              {
                "accountId": 3248695,
                "query": "SELECT sum(fdb_cache_hits) FROM Metric TIMESERIES"
              }
            ],
            "yAxisLeft": {
              "zero": true
            }
          },
          "linkedEntityGuids": null
        },
        {
          "visualization": {
            "id": "viz.line"
          },
          "layout": {
            "column": 5,
            "row": 7,
            "height": 3,
            "width": 4
          },
          "title": "Errors",
          "rawConfiguration": {
            "legend": {
              "enabled": true
            },
            "nrqlQueries": [
              {
                "accountId": 3248695,
                "query": "SELECT sum(fdb_create_errors), sum(fdb_read_errors), sum(fdb_update_errors), sum(fdb_delete_errors) FROM Metric TIMESERIES"
              }
            ],
            "yAxisLeft": {
              "zero": true
            }
          },
          "linkedEntityGuids": null
        },
        {
          "visualization": {
            "id": "viz.line"
          },
          "layout": {
            "column": 9,
            "row": 7,
            "height": 3,
            "width": 4
          },
          "title": "FlashDB Keys",
          "rawConfiguration": {
            "legend": {
              "enabled": true
            },
            "nrqlQueries": [
              {
                "accountId": 3248695,
                "query": "SELECT count(fdb_keys) FROM Metric TIMESERIES"
              }
            ],
            "yAxisLeft": {
              "zero": true
            }
          },
          "linkedEntityGuids": null
        }
      ]
    }
  ]
}

When you add your dashboard to your quickstart, you need to remove sensitive data. For example:

Do not include permissions: PUBLIC_READ_WRITE
Set all linkedEntityGuids to null
Set your accountId to 0

We've created a script to automate this process for you.To remove sensitive and unnecessary data from your dashboard, run the sanitize-dashboard from newrelic-quickstarts/utils:

bash

$cd newrelic-quickstarts/utils
$yarn sanitize-dashboard flashdb

Next, create a screenshot of your dashboard and add it to dashboards directory. Give it the same name as your JSON file. Your dashboard directory should look similar to the following:

FlashDB dashboard

Add your alerts to the quickstart

Next, add the static alerts you created previously to the quickstart. The alerts directory contains the templates for static alerts. To help you populate your yaml files, you can use New Relic's NerdGraph API explorer to get a JSON representation of each alert condition.

Tip

NerdGraph is New Relic's GraphQL API.

Open the NerdGraph explorer and select your key from the dropdown menu.

graphiql interface

Building a query is simple in the explorer. Check the appropriate boxes to build a GraphQL query:

{
  actor {
    account(id: {_your account id_}) {
      alerts {
        nrqlCondition(id: "{_nrql conditions's id_}") {
          ... on AlertsNrqlStaticCondition {
            id
            name
            nrql {
              query
            }
          }
          terms {
            operator
            priority
            threshold
            thresholdDuration
            thresholdOccurrences
          }
        }
      }
    }
  }
}

Tip

Under your alert policy, click on the condition to get its ID.

find alert id

Running the above query in Graphql will respond with the details of your alert condition that you can use to update your quickstart.

slow read response graphql

For static condition, take the static-alert.yml file and start populating it using the information returned from above query. First, name the file as read-response.yml and populate it:

---
# Name of the alert
name: slow read response

# Description and details
details: |+
  This alert is triggered when read operation takes > 0.85.

# Type of alert
type: STATIC

# NRQL query
nrql:
  query: "SELECT average(fdb_read_responses) FROM Metric"

# Function used to aggregate the NRQL query value(s) for comparison to the terms.threshold (Default: SINGLE_VALUE)
valueFunction: SINGLE_VALUE

# List of Critical and Warning thresholds for the condition
terms:
- priority: CRITICAL
  # Operator used to compare against the threshold.
  operator: ABOVE
  # Value that triggers a violation
  threshold: 0.85
  # Time in seconds; 120 - 3600
  thresholdDuration: 300
  # How many data points must be in violation for the duration
  thresholdOccurrences: ALL

# Adding a Warning threshold is optional
- priority: WARNING
  operator: ABOVE
  threshold: 0.75
 thresholdDuration: 300
  thresholdOccurrences: ALL

# Duration after which a violation automatically closes
# Time in seconds; 300 - 2592000 (Default: 86400 [1 day])
violationTimeLimitSeconds: 259200

Here, you added the pre-existing slow read response alert to the quickstart. Follow the same procedure to add the low cache hit ratio alert. For your reference, here's the graphql response.

cache hit ratio in graphql

Create your cache-hit-ratio.yml file based on the above response.

---
# Name of the alert
name: low cache hit ratio

# Description and details
details: |+
  This alert is triggered whenever the cache hit ratio for database is < 0.85.
  The cache hit ratio can be measured simply by: # of cache hits/ # of total read responses.
  It represents the proportion of block requests satisfied by the cache without requiring a disk read.
  A low cache hit score means that the database is inefficient.

# Type of alert
type: STATIC

# NRQL query
nrql:
  query: 'SELECT sum(fdb_cache_hits)/sum(fdb_read_responses) FROM Metric'

# Function used to aggregate the NRQL query value(s) for comparison to the terms.threshold
valueFunction: SINGLE_VALUE

# List of Critical and Warning thresholds for the condition
terms:
  - priority: CRITICAL
    # Operator used to compare against the threshold.
    operator: BELOW
    # Value that triggers a violation
    threshold: 0.75
    # Time in seconds; 120 - 3600
    thresholdDuration: 300
    # How many data points must be in violation for the duration
    thresholdOccurrences: ALL

  # Adding a Warning threshold is optional
  - priority: WARNING
    operator: BELOW
    threshold: 0.85
    thresholdDuration: 300
    thresholdOccurrences: ALL

# Duration after which a violation automatically closes
# Time in seconds; 300 - 2592000 (Default: 86400 [1 day])
violationTimeLimitSeconds: 259200

Add a description

Your quickstart is almost ready to go live. But how will others know what your quickstart is for and what it can do?

To help others understand the purpose of your quickstart, add a description.

In the root directory of your pack, you can find a config.yml file. Open the file in your IDE and edit it as follow:

# Name of the pack (required)
name: flashdb

# Description of the pack (required)
description: |
  Flashdb is the fastest database in the space.
  The Flashdb quickstart allows you to get visibility into the performance of flashdb with the help of following features:

  Dashboards:
  - Database methods: Monitor the number of transactions for each database method
  - Database size: Monitor the size of database
  - Average response time: Monitor the average response time for each type of database transaction
  - Cache hits: Monitor the cache hits
  - Errors: Monitor the errors occured for each type of database transaction
  - Database keys: Monitor the keys for database

  Alerts:
  - Cache hit ratio: Alert is triggered when cache hit ratio falls below the set limit.
  - Read response: Alert is triggered when read responses are slow and exceeds a set limit

summary: |
  Flashdb is the fastest database in the space.
  This quickstart allows you to get visibility into the performance of flashdb.

# Support level: New Relic | Verified | Community (required)
level: Community

# Design
icon: icon.jpeg
logo: logo.png

# Authors of the pack (required)
authors:
  - { 'enter your name' }

# References to other packs (optional)
# References are grouped by the type: operating-system, database, webserver, queue, ..
# The reference under the type is a at least one system, so at least one operating-system, database, ..
references:
  - type: database
    name:
      - flashdb

Here's how your final flashdb quickstart folder should look like. flashdb quickstart directory

Contribute quickstart to GitHub

Your quickstart is now ready to be published. You're going to commit your changes back to GitHub where it will be reviewed by New Relic. Follow the conventional commit syntax for New Relic to commit your changes.

bash

$git add -A
$git commit -m "feat(flashdb): Added a quickstart for flashdb"

Important

We, at New Relic, are always happy to receive contributions from the community. However, we are expecting a number of contributions for flashdb following the same lab course. To help us manage your contributions efficiently, we encourage you to label your contribution following this particular lab as lab using git tag command.

Push your changes to GitHub:

bash

$git tag lab
$git push

Once you've pushed your changes to GitHub, you can create a pull request.

pull request

Submit and wait for the review. Thanks a lot for your submission!

Important

At this stage, your quickstart will be automatically validated in GitHub. If this were a real-life submission, it would then be approved and incorporated into New Relic I/O for your users to see. As this is a lab, we will not actually review this PR. Feel free to delete it after it validates your work.

Homework

If you haven't already, we encourage you to read through some related docs as:

The above docs give you a head start on your observability journey with New Relic. We always welcome contributions from community so feel free to get in touch.