Telemetry Semantic Conventions

• This package goal is to provide a flexible and easy way to allow semantic conventions to be used for telemetry purposes across all MapColonies services.
• It's based on OpenTelemetry semantic-conventions.
• Each Domain defines its JSON file that describes the semantic conventions of the domain. The submodule handles the validation of the file and generates TS files for use in code.
• Supports Javascript & Typescript.

USAGE

1. Install the package using the following command:

npm i @map-colonies/semantic-conventions
Copy

2. Import the package and then use the conventions as needed.

import { SCOTTISH_CONVENTIONS, SCOTTISH_FOLD } from '@map-colonies/semantic-conventions';

console.log(SCOTTISH_CONVENTIONS.scottish.straight.David)
console.log(SCOTTISH_FOLD) // This will be marked with strikethrough because it's marked as deprecated
Copy

Domain creation

Below is a short example creating of a new semantic attribute domain by creating the domain.json file and generating its attributes.

1. Create a new file in the semanticConventions directory (The file must be a JSON file).

{
    "domain": "scottish",
    "content": {
      "propertyName": "mapcolonies.scottish",
      "kind": "clan",
      "description": "name of the clan 😺",
      "deprecated": false,
      "subAttributes": {
        "straight": {
          "propertyName": "mapcolonies.scottish.straight",
          "kind": "straightAttributes",
          "description": "attributes related to straights 🙀",
          "deprecated": false,
          "subAttributes": {
            "Jimmy": {
              "propertyName": "mapcolonies.scottish.straight.jimmy",
              "deprecated": false,
              "description": "Jimmy the scottish straight cat 😾"
            },
            "David": {
              "propertyName": "mapcolonies.scottish.straight.david",
              "deprecated": false,
              "description": "David the scottish straight cat 😻"
            }
          }
        },
        "fold": {
          "propertyName": "mapcolonies.scottish.fold",
          "kind": "straightAttributes",
          "description": "attributes related to fold 😿",
          "deprecated": true
        }
      }
    }
  }
Copy

2. Run the validations to make sure the created file is valid.

pnpm run validate:attributes
Copy

3. Run attributes generation to create new ts modules for all defined domain.json files.

pnpm run generate:attributes
Copy

4. Check the created TypeScript files to make sure they are as you intended. They should look like this:

/* eslint-disable */
/**
 * This file was automatically generated by @mapcolonies/telemetry npm package.
 * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
 * and release new compiled package to regenerate this file.
 */

/**
* attributes related to fold 😿
* @constant
* @deprecated Change to new attribute if this one was replaced 

*/
export const SCOTTISH_FOLD = 'mapcolonies.scottish.fold';

/**
 * David the scottish straight cat 😻
 * @constant
 */
export const SCOTTISH_STRAIGHT_DAVID = 'mapcolonies.scottish.straight.david';

/**
 * Jimmy the scottish straight cat 😾
 * @constant
 */
export const SCOTTISH_STRAIGHT_JIMMY = 'mapcolonies.scottish.straight.jimmy';

/**
 * name of the clan 😺
 * @constant
 */
export const SCOTTISH_CONVENTIONS = {
  scottish: {
    /**
    * attributes related to fold 😿
    * @constant
    * @deprecated Change to new attribute if this one was replaced 
    */
    fold: 'mapcolonies.scottish.fold',
    straight: {
      /**
       * David the scottish straight cat 😻
       * @constant
       */
      David: 'mapcolonies.scottish.straight.david',
      /**
       * Jimmy the scottish straight cat 😾
       * @constant
       */
      Jimmy: 'mapcolonies.scottish.straight.jimmy',
    },
  },
} as const;
Copy

Development

The Schema used to validate the JSON files and to create the TypeScript types for the script usage is defined and managed inside the repo - schemas/attribute.schema.json.

The schema files have autocomplete support in VsCode. To change the schema and file associations check the .vscode/settings.json.

pnpm run generate:types
Copy

All the semantic convention scripts run before the build process of the package, as their only output is TypeScript files that are transpiled as part of the larger build process into javascript.