README.md

Telemetry Semantic Conventions

• This submodule's 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.

Important

If OpenTelemetry already defines a value as part of their semantic conventions, use that and do not define a new one.

Important

Attributes should follow the Open Telemetry semantic-convention naming concept

USAGE

1. Install the package using the following command:

npm i @map-colonies/telemetry

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

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

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

Important

If you get any errors of missing type definitions while using the package, or you are unable to import the submodule conventions, you should make sure both the module and moduleResolution options of your tsconfig / jsconfig are set to NodeNext. For more information.

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
        }
      }
    }
  }

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

npm run validate:attributes

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

npm run generate:attributes

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;

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.

Important

After making any changes to a schema, you MUST re-generate its types using the following command:

npm run generate:types

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.