		@@ -90,5 +90,19 @@ # atg-shared-utilities CONTRIBUTION DOCUMENTATION

		## Push main to GitHub
		### Push main to GitHub

		#### Using an SSH key

		Info on getting this setup: https://docs.github.com/en/authentication/connecting-to-github-with-ssh

		Add a remote for GitHub\
		git remote add github git@github.com:f5devcentral/f5-atg-shared-utilities.git

		Push the current branch to GitHub\
		git push github

		#### Using a personal access token

		Create a personal access token in your GitHub account. This should help with how to do this: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

		Add a remote for GitHub\
		git remote add github https://github.com/f5devcentral/f5-atg-shared-utilities
		@@ -95,0 +109,0 @@

index.js

		@@ -22,2 +22,3 @@ /**
		const secureVault = require('./src/secureVault');
		const tracer = require('./src/tracer');

		@@ -27,3 +28,4 @@ module.exports = {
		promiseUtils,
		secureVault
		secureVault,
		tracer
		};

package.json

		{
		"name": "@f5devcentral/atg-shared-utilities",
		"version": "0.2.2",
		"version": "0.2.3",
		"scripts": {
		@@ -47,6 +47,10 @@ "lint": "eslint .",
		"type": "git",
		"url": "git@gitswarm.f5net.com:automation-toolchain/atg-shared-utilities.git"
		"url": "git@github.com:f5devcentral/f5-atg-shared-utilities.git"
		},
		"author": "F5 Networks",
		"license": "Apache-2.0"
		"license": "Apache-2.0",
		"optionalDependencies": {
		"error": "7.2.1",
		"jaeger-client": "^3.18.1"
		}
		}

README.md

		@@ -57,2 +57,56 @@ # atg-shared-utilities

		## Tracer

		This lib contains classes and functions that facilitate performance tracing, with current implementation using `Jaeger`, which follows OpenTelemetry (see <https://opentelemetry.io/docs/concepts/data-sources/> for basics)

		Performance tracing is not intended for production use. But since tracing is integrated with the rest of the production code, a `Tracer` has to exist, and will then act as no-op if it's not enabled upon instantiation (default).

		### Builds

		#### jaeger-client

		The `jaeger-client` is listed as an optional dependency and will only be loaded/required at tracer initialization and only if tracing is enabled. This is so that we don't include the modules when creating a production build.

		It is recommended that projects use a separate script for creating a trace-enabled build. For example, a production build might be created using `npm run build` which uses `npm ci --only=production --no-optional`, while a perf build might be created using `npm run buildperf` which uses `npm ci --only=production`, which then allows the optional depenedencies to be included.

		#### error-package

		Jaeger throws an error for older node versions (specifically with dependency `thriftrw -> error`) wherein a read-only name property is being modified. Consequently we had to modify package-lock.json and pin it to 7.2.1., otherwise, `thriftw` uses its own subdirectory of node_modules with the older error version of 7.0.2.

		### Settings

		There are two ways to enable a tracer upon instantiation:

		- by passing through constructor options, or
		- by setting env variables
		- This is an option for quick dev debugging or for projects that might not have persisted settings yet.
		- App settings are generally loaded after app start is completed; env variables serve as backup to enable trace and get information early on while app is starting.
		- For projects using iControl REST Framework: restnoded is specific in how it's started and run file needs to be updated to include the env variables)

		Example variables:

		```
		export F5_PERF_TRACING_ENDPOINT=http://{jaegerHost}:{jaegerPort}/api/traces
		export F5_PERF_TRACING_DEBUG=true
		export F5_PERF_TRACING_ENABLED=true
		```

		### Usage

		Spans

		- A span is a basic unit of trace. A span can have other related spans, either at the same level, or as a child span. A child span denotes a subset of some operation(s) done within a parent span.
		- A span can have log (events) associated with it, as well as tags (key-value pair of attributes pertaining to the span).
		- Sample use given a typical REST endpoint with url `/shared/myProject/myResource/{myResourceId}` which allows POST to create a new resource
		- Using `tracer.startHttpSpan()` at the beginning of the endpoint handler when request is received will create:

		- A new span with the api path `/shared/myProject/myResource/{myResourceId}`.The `{myResourceId}` here is literal - we don't want spans for each resourceId.
		- The relevant http tags (e.g. `http.url:shared/myProject/myResource/resourceId123`, `http.method:POST`)

		- Using `tracer.startChildSpan()` in subsequent operations, (e.g. inside `validateResource()` then again in `createNewResource()`) and passing the previous http span as the parent arg will create those child spans with their own start and end time, tags and events. This allows for further drill down and inspection.

		Tracer.close()

		- It is important to explicitly call `tracer.close()` when tracer is no longer needed to flush out any pending operations and avoid memory leaks.

		## License
		@@ -59,0 +113,0 @@

@f5devcentral/atg-shared-utilities - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics