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.
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.
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.
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.
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
tonull
- Set your
accountId
to0
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:
$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:
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.
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.
Running the above query in Graphql will respond with the details of your alert condition that you can use to update your quickstart.
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 alertname: slow read response
# Description and detailsdetails: |+ This alert is triggered when read operation takes > 0.85.
# Type of alerttype: STATIC
# NRQL querynrql: 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 conditionterms:- 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.
Create your cache-hit-ratio.yml file based on the above response.
---# Name of the alertname: low cache hit ratio
# Description and detailsdetails: |+ 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 alerttype: STATIC
# NRQL querynrql: 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.thresholdvalueFunction: SINGLE_VALUE
# List of Critical and Warning thresholds for the conditionterms: - 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
# Designicon: icon.jpeglogo: 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.
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.
$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:
$git tag lab$git push
Once you've pushed your changes to GitHub, you can create a 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.