Merge pull request #74 from newrelic/chore/spec

chore(spec): add spec docs for config, alerts, and dashboards

docs/alert-spec.md

@@ -0,0 +1,39 @@
+# Alert Config File Schema
+
+An alert config is written in YAML and adheres to the specifications outlined below.
+
+## Filename format
+
+Alert config files are placed under `packs/<pack_name>/alerts/`. There are 3 types of alerts we can configure:
+
+```bash
+packs/<pack_name>/alerts/baseline-alert.yml
+packs/<pack_name>/alerts/outlier-alert.yml
+packs/<pack_name>/alerts/static-alert.yml
+```
+
+## Schema definition
+
+```yaml
+####################################################################################
+# Metadata - these fields will be removed from the AlertsNrqlConditionInput 
+# definition
+####################################################################################
+
+# A short form description for this Alert condition
+details: string, optional
+
+# Type of alert condition
+type: enum, required # One of [ BASELINE, OUTLIER, STATIC ]
+
+
+####################################################################################
+# Alert Condition Definition - not validating this, as the type is not controlled 
+# by us and can change
+####################################################################################
+
+```
+
+## Schema Validator
+
+See [newrelic-observability-packs/utils/validate_packs.js](../utils/validate_packs.js).

docs/config-spec.md

@@ -0,0 +1,91 @@
+# Pack Config File Schema
+
+The top-level pack config is written in YAML and adheres to the specifications outlined below.
+
+## Filename format
+
+Pack config files are placed under `packs/<pack_name>/config.yml`.
+
+For example:
+
+`packs/apache/config.yml`
+
+## Schema definition
+
+```yaml
+#####################
+# Metadata
+#####################
+
+# TBD
+# Unique identifier for this observability pack
+# uuid: guid, required
+
+# Name acts as a unique identifier for this observability pack
+# Formatted as hyphenated lowercase
+# Example: apache, golden-signals-for-web-servers
+name: string, required
+
+# Displayed on the pack overview/details page formatted into rich text.
+# Standardized to a template for the New Relic packs.
+description: string, required
+
+# TBD
+# url slug for linking on public website
+# recommended format: make this a lowercase and hyphenated version
+# of the `name` field
+# slug: string, required
+
+# Level categorization of Observability Pack
+level: enum, required # One of [ New Relic, Verified, Community ]
+
+# List of contributors for this Observability Pack
+authors: list, required
+
+# Instrumentation Requirements - indicates what's needed in an account
+# for a given pack (and it's components) to work.
+#
+# It's important that we're able to verify whether or not the user's 
+# environment meets the requirements for the use of a given resource. 
+instrumentation: list(object), optional
+  - type: string, optional 
+    name: string, optional
+
+#####################
+# Content/Design
+#####################
+# The name of the pack displayed everywhere the pack is referenced
+title: string, optional
+
+# Displayed in search results and recommendations. Summarizes a packs functionality.
+# A short form description for this Observability Pack.
+summary: string, optional
+
+# Tags for filtering / searching criteria
+tags: list(string), optional
+
+# Displaying related child packs
+children: list(object), optional
+  - title: string, optional
+    description: string, optional
+    screenshots: string, optional
+
+# Contains avatar, GitHub username, and link to GitHub profile for each contributor
+contributors: list(object), optional
+  - github-username: string, required
+    profile-url: string, required
+    avatar-url: string, required
+
+# path to icon for this Observability Pack
+icon: string, optional
+
+# path to logo for this Observability Pack
+logo: string, optional
+
+# URL of website for this Observability Pack
+website: string, optional
+```
+
+## Schema Validator
+
+See [newrelic-observability-packs/utils/validate_packs.js](../utils/validate_packs.js).

docs/dashboard-spec.md

@@ -0,0 +1,24 @@
+# Dashboard Config File Schema
+
+A dashboard config is written in JSON and adheres to the specifications outlined below.
+
+## Filename format
+
+Dashboard config files are placed under `packs/<pack_name>/dashboards/`. Example:
+
+```bash
+packs/<pack_name>/dashboards/apache.json
+```
+
+## Schema definition
+
+The schema adheres to the `DashboardInput` used in the [dashboardCreate](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/dashboards-api-migration-insights-api-nerdgraph/#dashboard-create) mutation in NerdGraph.
+
+There are two other requirements:
+
+* The top level `description` cannot be null
+* The `permissions` field should be null, and will be set to `PUBLIC_READ_WRITE` for all dashboards created through the Observability Pack flow.
+
+## Schema Validator
+
+See [newrelic-observability-packs/utils/validate_packs.js](../utils/validate_packs.js).

docs/example-schemas/config.json

@@ -0,0 +1,37 @@
+{
+  "name": "Apache",
+  "description": "The template pack allows you to get visibilility into the performance and available of your example service and dependencies. Use this pack together with the mock up integrations.",
+  "level": "New Relic",
+  "authors": [
+    "New Relic"
+  ],
+  "instrumentation": [
+    {
+      "name": "apachi-ohi",
+      "type": "type"
+    }
+  ],
+  "title": "Title of Pack",
+  "short-description": "Short description of pack",
+  "full-description": "Full description of pack",
+  "tags": [
+    "filters",
+    "for",
+    "searching"
+  ],
+  "children": {
+    "title": "Title of Pack",
+    "description": "Description of child pack",
+    "screenshots": "Screenshots of child pack"
+  },
+  "contributors": [
+    {
+      "github-username": "username",
+      "profile-url": "profiles-url",
+      "avatar-url": "avatar-url"
+    }
+  ],
+  "icon": "icon.jpg",
+  "logo": "logo.png",
+  "website": "https://www.newrelic.com"
+}

docs/rulesets/config.yml

@@ -0,0 +1,93 @@
+# Schema: insert link to schema definition here
+version: 1
+rules:
+  ################
+  # metadata
+  ################
+  # Not implementing right now
+  # uuid:
+  #   type: guid
+  #   required: true
+  name:
+    type: text
+    limit: 100
+    required: true
+  # Not implementing right now
+  # slug:
+  #   type: text
+  #   required: true
+  level:
+    type: enum
+    values:
+      - New Relic
+      - Verified
+      - Community
+    required: true
+  authors:
+    type: list(string)
+    required: true
+  instrumentation:
+    type: list(object)
+    values:
+      name:
+        type: text
+      type:
+        type: text
+
+  ################
+  # Content
+  ################
+  title:
+    type: text
+    limit: 60
+  summary:
+    type: text
+    limit: 250
+  description:
+    type: text
+    limit: 2000
+  # Not sure if needed
+  # thumbnail:
+  #   type: image
+  #   format: { jpg|png }
+  #   size: 4 # MB
+  #   limit: 1
+  #   aspect: 1.5
+  #   width: 800
+  #   height: 1600
+  # screenshots:
+  #   type: image
+  #   format: { jpg|png }
+  #   size: 4 # MB
+  #   limit: 6
+  #   aspect: 1.5
+  #   width: 800
+  #   height: 1600
+  icon:
+    type: image
+    format: { jpg|png }
+    size: 4 # MB
+    limit: 1
+    aspect: 1.5
+    width: 800
+    height: 1600
+  logo:
+    type: image
+    format: { jpg|png|svg }
+    size: 4 # MB
+    limit: 1
+    aspect: 1.5
+    width: 800
+    height: 1600
+  children:
+    type: object
+    value:
+      title:
+      description:
+      screenshots:
+  contributors:
+    type: object
+    value:
+      github-username:
+      profile-link:
+      avatar-link:

utils/__tests__/validate_packs.test.js

@@ -27,6 +27,12 @@ const getTestFile = (schemaType) => {
       contents: [
         {
           name: 'fakedashboard',
+          description: 'fakeDescription',
+          pages: [{
+            name: "",
+            description: "",
+            widgets: [{}]
+          }]
         },
       ],
     },
@@ -42,7 +48,7 @@ const getTestFile = (schemaType) => {
       ],
     },
     synthetic: {
-      path: '/instrumentation/synthetics',
+      path: '/instrumentation/synthetics/',
       contents: [
         {
           name: 'fakesynthetic',
@@ -54,6 +60,9 @@ const getTestFile = (schemaType) => {
       contents: [
         {
           name: 'fakeobservabilitypack',
+          description: 'fakeDescription',
+          authors: ['fakeAuthor'],
+          level: 'New Relic'
         },
       ],
     },
@@ -252,7 +261,7 @@ describe('test validateFile', () => {
       ${'New Relic'}
       ${'Verified'}
       ${'Community'}
-    `('doesnt fail for a valid alert definition', ({ level }) => {
+    `('doesnt fail for a valid main config definition', ({ level }) => {
       const mainConfigTestFile = getTestFile('main_config');
       mainConfigTestFile.contents[0].level = level;
 
@@ -261,7 +270,7 @@ describe('test validateFile', () => {
       expect(errors).toEqual([]);
     });
 
-    test('doesnt fail for valid alert definition w/o non-required fields', () => {
+    test('doesnt fail for valid main config definition w/o non-required fields', () => {
       const mainConfigTestFile = getTestFile('main_config');
 
       const { errors } = validateFile(mainConfigTestFile);