@ms-cloudpack/telemetry 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @ms-cloudpack/telemetry
+
+A library for telemetry that gets reported to Application Insights by using Open Telemetry standards.
+
+Currently, this library only supports [Tracing](https://opentelemetry.io/docs/concepts/signals/traces/). Metrics and Logs can be added later when needed.
+
+## Example usage
+
+1. Create a client:
+
+```ts
+const telemetryClient = new TelemetryClient({
+  serviceNamespace: 'cloudpack',
+  serviceName: 'cli',
+  productVersion: '1.2.3',
+  instrumentationKey: '<Application insights Instrumentation Key>',
+  logLevel: 'verbose',
+});
+```
+
+2. Add shared attributes
+
+```ts
+telemetryClient.setSharedSpanAttribute('sessionId', 'my-session-id');
+```
+
+These attributes will get added to all spans.
+
+3. Get the tracer
+
+```ts
+const tracer = telemetryClient.getTracer();
+```
+
+4. Create a span / add events / end the span
+
+```ts
+const span = tracer.createSpan('my-unit-of-work');
+// do work
+span.addEvent('my-event', { myCustomAttribute: 'my-custom-value' });
+
+try {
+  // do more work
+} catch (err) {
+  span.recordException(err);
+}
+
+// end the span when the unit-of-work completed.
+span.end();
+```
+
+[Lear more about spans](https://opentelemetry.io/docs/instrumentation/js/instrumentation/#create-spans)
+
+5. Shutdown TelemetryClient before application exists
+
+```ts
+telemetryClient.shutdown();
+```
+
+- This will force flush all the remaining data to remote servers and prevent more data to be collected.
+- Make sure that all spans have been ended before shuting down the telemetry client

package/lib/SpanEnrichingProcessor.d.ts

@@ -0,0 +1,12 @@
+import type { ReadableSpan, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+/**
+ * Span processor that adds shared attributes to all spans.
+ */
+export declare class SpanEnrichingProcessor implements SpanProcessor {
+    private getSharedSpanAttributes;
+    constructor(getSharedSpanAttributes: () => Record<string, string>);
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    onStart(): void;
+    onEnd(span: ReadableSpan): void;
+}

package/lib/SpanEnrichingProcessor.js

@@ -0,0 +1,23 @@
+/**
+ * Span processor that adds shared attributes to all spans.
+ */
+export class SpanEnrichingProcessor {
+    constructor(getSharedSpanAttributes) {
+        this.getSharedSpanAttributes = getSharedSpanAttributes;
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+    onStart() {
+        // noop
+    }
+    onEnd(span) {
+        for (const [key, value] of Object.entries(this.getSharedSpanAttributes())) {
+            span.attributes[key] = value;
+        }
+    }
+}
+//# sourceMappingURL=SpanEnrichingProcessor.js.map

package/lib/SpanEnrichingProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpanEnrichingProcessor.js","sourceRoot":"","sources":["../src/SpanEnrichingProcessor.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,sBAAsB;IACjC,YAAoB,uBAAqD;QAArD,4BAAuB,GAAvB,uBAAuB,CAA8B;IAAG,CAAC;IAE7E,UAAU;QACR,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,QAAQ;QACN,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO;QACL,OAAO;IACT,CAAC;IAED,KAAK,CAAC,IAAkB;QACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,uBAAuB,EAAE,CAAC,EAAE;YACzE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;SAC9B;IACH,CAAC;CACF"}

package/lib/TelemetryClient.d.ts

@@ -0,0 +1,22 @@
+import type { Tracer } from '@opentelemetry/api';
+import type { TelemetryOptions } from './types.js';
+export declare class TelemetryClient {
+    private readonly appInsightsClient;
+    private readonly sharedSpanAttributes;
+    constructor(options: TelemetryOptions);
+    /**
+     * Sets a shared attribute that will be added to all spans.
+     * @param key - key of the attribute
+     * @param value - value of the attribute
+     */
+    setSharedSpanAttribute(key: string, value: string): void;
+    /**
+     * Flushes all telemetry and shuts down the telemetry client.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Gets the OpenTelemetry tracer.
+     * @returns the OpenTelemetry tracer
+     */
+    getTracer(): Tracer;
+}

package/lib/TelemetryClient.js

@@ -0,0 +1,41 @@
+import { ApplicationInsightsClient } from 'applicationinsights';
+import { convertLogLevel } from './convertLogLevel.js';
+import { getAppInsightsConfig } from './getAppInsightsConfig.js';
+import { SpanEnrichingProcessor } from './SpanEnrichingProcessor.js';
+export class TelemetryClient {
+    constructor(options) {
+        this.sharedSpanAttributes = {};
+        const config = getAppInsightsConfig(options);
+        this.appInsightsClient = new ApplicationInsightsClient(config);
+        this.appInsightsClient.getLogger().updateLogLevel(convertLogLevel(options.logLevel));
+        // Set shared attributes
+        this.setSharedSpanAttribute('version', options.productVersion);
+        // Set SpanEnrichingProcessor to add shared attributes to all spans
+        const nodeTraceProvider = this.appInsightsClient.getTraceHandler().getTracerProvider();
+        nodeTraceProvider.addSpanProcessor(new SpanEnrichingProcessor(() => this.sharedSpanAttributes));
+        this.appInsightsClient.start();
+    }
+    /**
+     * Sets a shared attribute that will be added to all spans.
+     * @param key - key of the attribute
+     * @param value - value of the attribute
+     */
+    setSharedSpanAttribute(key, value) {
+        this.sharedSpanAttributes[key] = value;
+    }
+    /**
+     * Flushes all telemetry and shuts down the telemetry client.
+     */
+    async shutdown() {
+        await this.appInsightsClient?.flush();
+        await this.appInsightsClient?.shutdown();
+    }
+    /**
+     * Gets the OpenTelemetry tracer.
+     * @returns the OpenTelemetry tracer
+     */
+    getTracer() {
+        return this.appInsightsClient?.getTraceHandler().getTracer();
+    }
+}
+//# sourceMappingURL=TelemetryClient.js.map

package/lib/TelemetryClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryClient.js","sourceRoot":"","sources":["../src/TelemetryClient.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,MAAM,OAAO,eAAe;IAI1B,YAAY,OAAyB;QAFpB,yBAAoB,GAA2B,EAAE,CAAC;QAGjE,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE7C,IAAI,CAAC,iBAAiB,GAAG,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC;QAE/D,IAAI,CAAC,iBAAiB,CAAC,SAAS,EAAE,CAAC,cAAc,CAAC,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QAErF,wBAAwB;QACxB,IAAI,CAAC,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;QAE/D,mEAAmE;QACnE,MAAM,iBAAiB,GAAuB,IAAI,CAAC,iBAAiB,CAAC,eAAe,EAAE,CAAC,iBAAiB,EAAE,CAAC;QAC3G,iBAAiB,CAAC,gBAAgB,CAAC,IAAI,sBAAsB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;QAEhG,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,sBAAsB,CAAC,GAAW,EAAE,KAAa;QACtD,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACzC,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,QAAQ;QACnB,MAAM,IAAI,CAAC,iBAAiB,EAAE,KAAK,EAAE,CAAC;QACtC,MAAM,IAAI,CAAC,iBAAiB,EAAE,QAAQ,EAAE,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACI,SAAS;QACd,OAAO,IAAI,CAAC,iBAAiB,EAAE,eAAe,EAAE,CAAC,SAAS,EAAE,CAAC;IAC/D,CAAC;CACF"}

package/lib/convertLogLevel.d.ts

@@ -0,0 +1,3 @@
+import { DiagLogLevel } from '@opentelemetry/api';
+import type { LogLevel } from './types.js';
+export declare function convertLogLevel(logLevel?: LogLevel): DiagLogLevel;

package/lib/convertLogLevel.js

@@ -0,0 +1,12 @@
+import { DiagLogLevel } from '@opentelemetry/api';
+export function convertLogLevel(logLevel) {
+    switch (logLevel) {
+        case 'debug':
+            return DiagLogLevel.DEBUG;
+        case 'verbose':
+            return DiagLogLevel.VERBOSE;
+        default:
+            return DiagLogLevel.WARN;
+    }
+}
+//# sourceMappingURL=convertLogLevel.js.map

package/lib/convertLogLevel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertLogLevel.js","sourceRoot":"","sources":["../src/convertLogLevel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,MAAM,UAAU,eAAe,CAAC,QAAmB;IACjD,QAAQ,QAAQ,EAAE;QAChB,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,KAAK,CAAC;QAC5B,KAAK,SAAS;YACZ,OAAO,YAAY,CAAC,OAAO,CAAC;QAC9B;YACE,OAAO,YAAY,CAAC,IAAI,CAAC;KAC5B;AACH,CAAC"}

package/lib/getAppInsightsConfig.d.ts

@@ -0,0 +1,3 @@
+import { ApplicationInsightsConfig } from 'applicationinsights';
+import type { TelemetryOptions } from './types.js';
+export declare function getAppInsightsConfig(options: TelemetryOptions): ApplicationInsightsConfig;

package/lib/getAppInsightsConfig.js

@@ -0,0 +1,43 @@
+import { Resource } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import { ApplicationInsightsConfig } from 'applicationinsights';
+import { createHash } from 'crypto';
+import { getComputerName } from './getComputerName.js';
+function sha256(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+export function getAppInsightsConfig(options) {
+    const config = new ApplicationInsightsConfig();
+    config.connectionString = `InstrumentationKey=${options.instrumentationKey}`;
+    config.enableAutoCollectExceptions = false;
+    config.enableAutoCollectHeartbeat = false;
+    config.enableAutoCollectPerformance = false;
+    config.enableAutoCollectStandardMetrics = false;
+    config.instrumentations = {
+        http: {
+            enabled: false,
+        },
+        azureSdk: {
+            enabled: false,
+        },
+    };
+    config.logInstrumentations = {
+        bunyan: {
+            enabled: false,
+        },
+        console: {
+            enabled: false,
+        },
+        winston: {
+            enabled: false,
+        },
+    };
+    config.resource = new Resource({
+        // Use a hash of the computer name to avoid PII
+        [SemanticResourceAttributes.SERVICE_INSTANCE_ID]: sha256(getComputerName()),
+        [SemanticResourceAttributes.SERVICE_NAME]: options.serviceName,
+        [SemanticResourceAttributes.SERVICE_NAMESPACE]: options.serviceNamespace,
+    });
+    return config;
+}
+//# sourceMappingURL=getAppInsightsConfig.js.map

package/lib/getAppInsightsConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAppInsightsConfig.js","sourceRoot":"","sources":["../src/getAppInsightsConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAyB;IAC5D,MAAM,MAAM,GAAG,IAAI,yBAAyB,EAAE,CAAC;IAC/C,MAAM,CAAC,gBAAgB,GAAG,sBAAsB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAC7E,MAAM,CAAC,2BAA2B,GAAG,KAAK,CAAC;IAC3C,MAAM,CAAC,0BAA0B,GAAG,KAAK,CAAC;IAC1C,MAAM,CAAC,4BAA4B,GAAG,KAAK,CAAC;IAC5C,MAAM,CAAC,gCAAgC,GAAG,KAAK,CAAC;IAChD,MAAM,CAAC,gBAAgB,GAAG;QACxB,IAAI,EAAE;YACJ,OAAO,EAAE,KAAK;SACf;QACD,QAAQ,EAAE;YACR,OAAO,EAAE,KAAK;SACf;KACF,CAAC;IACF,MAAM,CAAC,mBAAmB,GAAG;QAC3B,MAAM,EAAE;YACN,OAAO,EAAE,KAAK;SACf;QACD,OAAO,EAAE;YACP,OAAO,EAAE,KAAK;SACf;QACD,OAAO,EAAE;YACP,OAAO,EAAE,KAAK;SACf;KACF,CAAC;IAEF,MAAM,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC;QAC7B,+CAA+C;QAC/C,CAAC,0BAA0B,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC;QAC3E,CAAC,0BAA0B,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,WAAW;QAC9D,CAAC,0BAA0B,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC,gBAAgB;KACzE,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/lib/getComputerName.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Each OS has a different way of getting the computer name.
+ * @returns computer name for the current OS, or the hostname if it cannot be determined
+ */
+export declare function getComputerName(): string;

package/lib/getComputerName.js

@@ -0,0 +1,21 @@
+import { execSync } from 'child_process';
+import { hostname } from 'os';
+/**
+ * Each OS has a different way of getting the computer name.
+ * @returns computer name for the current OS, or the hostname if it cannot be determined
+ */
+export function getComputerName() {
+    try {
+        const computerNameGetters = {
+            win32: () => process.env.COMPUTERNAME,
+            darwin: () => execSync('scutil --get ComputerName').toString(),
+        };
+        const computerName = computerNameGetters[process.platform]?.() || hostname();
+        return computerName.trim();
+    }
+    catch (e) {
+        console.warn('Unable to get OS specific computer name for telemetry, falling back to hostname', e);
+        return hostname();
+    }
+}
+//# sourceMappingURL=getComputerName.js.map

package/lib/getComputerName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getComputerName.js","sourceRoot":"","sources":["../src/getComputerName.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI;QACF,MAAM,mBAAmB,GAA+D;YACtF,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY;YACrC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,QAAQ,EAAE;SAC/D,CAAC;QAEF,MAAM,YAAY,GAAG,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,QAAQ,EAAE,CAAC;QAE7E,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;KAC5B;IAAC,OAAO,CAAC,EAAE;QACV,OAAO,CAAC,IAAI,CAAC,iFAAiF,EAAE,CAAC,CAAC,CAAC;QAEnG,OAAO,QAAQ,EAAE,CAAC;KACnB;AACH,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export type { Span, Tracer } from '@opentelemetry/api';
+export { TelemetryClient } from './TelemetryClient.js';
+export type { LogLevel, TelemetryOptions } from './types.js';

package/lib/index.js

@@ -0,0 +1,2 @@
+export { TelemetryClient } from './TelemetryClient.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.34.4"
+    }
+  ]
+}

package/lib/types.d.ts

@@ -0,0 +1,25 @@
+export type LogLevel = 'debug' | 'verbose' | 'default';
+export interface TelemetryOptions {
+    /**
+     * The instrumentation key for the Application Insights.
+     */
+    instrumentationKey: string;
+    /**
+     * The log level for the telemetry client.
+     */
+    logLevel?: LogLevel;
+    /**
+     * The version of the product. This will be added as a shared attribute to all spans.
+     */
+    productVersion: string;
+    /**
+     * A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services.
+     * Possible values: cloudpack, cloudpack.services, etc.
+     */
+    serviceNamespace: string;
+    /**
+     * Logic name of the service
+     * Possible values: cli, bundler-service, etc.
+     */
+    serviceName: string;
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ms-cloudpack/telemetry",
+  "version": "0.1.0",
+  "description": "Helpers for logging tasks to the console.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./lib/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.4.0",
+    "@opentelemetry/resources": "^1.9.1",
+    "@opentelemetry/sdk-trace-node": "^1.9.1",
+    "@opentelemetry/semantic-conventions": "^1.9.1",
+    "applicationinsights": "^3.0.0-beta.2"
+  },
+  "devDependencies": {
+    "@ms-cloudpack/eslint-config-base": "*",
+    "@ms-cloudpack/scripts": "*"
+  },
+  "scripts": {
+    "api:update": "cloudpack-scripts api-update",
+    "api": "cloudpack-scripts api",
+    "build:watch": "cloudpack-scripts build-watch",
+    "build": "cloudpack-scripts build",
+    "lint:update": "cloudpack-scripts lint-update",
+    "lint": "cloudpack-scripts lint"
+  },
+  "files": [
+    "lib/**/!(*.test.*)"
+  ]
+}